agent-Specialization/.astrion/memory/ocr_client_initialization.md

name	description
ocr_client_initialization	当 OCRClient/OpenAI 初始化报错、WebTerminal 创建失败、或升级 openai 包时，应该索引本记忆

OCRClient 初始化与 OpenAI 包兼容性

问题

modules/ocr_client.py 在 __init__ 中直接创建 OpenAI(api_key=OCR_API_KEY)。

• openai 包较新版本（>= 2.40）在 api_key 为空时会抛出 openai.OpenAIError: Missing credentials
• 服务器 settings.json 通常未配置 OCR_API_KEY
• 这会导致 WebTerminal/MainTerminal 初始化失败，所有依赖 terminal 的 API 都返回 500

修复

在 OCRClient.__init__ 中，仅在 OCR_API_KEY 存在时才创建 OpenAI 客户端：

self.client = None
if OCR_API_KEY:
    self.client = OpenAI(
        api_key=OCR_API_KEY,
        base_url=base_url or None,
        http_client=self.http_client,
    )

在 vlm_analyze 中同时检查 self.client：

if not self.client or not OCR_API_KEY or not OCR_API_BASE_URL or not self.model:
    return {"success": False, "error": "VLM 配置缺失，请设置 OCR_API_BASE_URL / OCR_API_KEY / OCR_MODEL_ID", "warnings": warnings}

教训

• 升级依赖包后要检查破坏性变更
• 可选功能（OCR/VLM）的客户端初始化不应阻塞主终端启动
• 服务器环境缺少某个 API key 时，应优雅降级而不是直接崩溃