---
name: ocr_client_initialization
description: 当 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` 客户端：

```python
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`：

```python
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 时，应优雅降级而不是直接崩溃