Skip to content

Commit f58b0f2

Browse files
stay-foolish-foreverstay-foolish-forever
authored
feat: Add OpenAI Responses API support and refactor protocol handling (#363)
* feat(llm): add OpenAI Responses API support Add `openai-responses` as a third LLM protocol alongside `anthropic` and `openai-chat-completions`, enabling code review via the OpenAI Responses API (/v1/responses) for GPT-5.x / o-series models. Protocol naming refactor (backward-compatible): - Canonicalize "openai" -> "openai-chat-completions" (alias still accepted) - Add NormalizeProtocol / ValidateProtocol / IsAnthropicProtocol helpers - Registry uses canonical constants; resolver normalizes everywhere New OpenAIResponsesClient (stateless replay, per DESIGN_STATE_CACHE_PHASE.md): - system messages -> Instructions; tool calls -> function_call items keyed by CallID so the agent loop pairs results correctly - store=false (privacy); prompt_cache_key = sha256(instructions)[:32] - Phase fields (commentary/final_answer) dropped with TODO for gpt-5.3-codex+ Config plumbing: - llm.protocol field + OCR_LLM_PROTOCOL env (priority over use_anthropic / OCR_USE_ANTHROPIC); TUI exposes all three protocols in Custom & Manual - anthropic-vertex rejected with friendly "not yet implemented" message Docs: protocol reference, config examples, env var table, and Responses API notes (store=false caching caveat, cache key derivation, Phase TODO) updated across en/zh-CN/ko-KR/ja-JP/ru-RU READMEs. * refactor(llm): switch PromptCacheKey to precomputed scheme via ChatRequest.CacheKey Replace per-turn sha256 computation inside buildResponsesParams with a precomputed cache key that callers compute once per session and pass through ChatRequest.CacheKey (json:"-"). The key now incorporates the first user message alongside instructions, so different files under review land in distinct cache buckets — the previous instructions-only key was identical across all files. Changes: - ChatRequest gains CacheKey string field (json:"-", zero impact on Chat Completions / Anthropic clients which never read it) - New llm.ComputeCacheKey helper: sha256(instructions + "\x00" + firstUser)[:32] - responses_client.go: reads req.CacheKey directly, removes promptCacheKey function and first-user-message scanning - loop.go: RunPerFile computes cacheKey once before the loop, reuses every turn - All 8 remaining call sites (agent, scan, relocation, compression, llm_cmd) compute once at request construction - Update PLAN_RESPONSES_SUPPORT.md and DESIGN_STATE_CACHE_PHASE.md to reflect the precomputed scheme - Update tests: passthrough tests for client, dedicated TestComputeCacheKey * refactor(llm): use canonical protocol name "openai" and UUID-based session ID for cache key Two changes to maximize backward compatibility and simplify the design: 1. Protocol naming: revert ProtocolOpenAIChatCompletions value from "openai-chat-completions" back to "openai". Old config files with protocol: "openai" are now identical to what new configs write — zero behavioral difference. The alias direction in NormalizeProtocol is reversed: "openai-chat-completions" -> "openai" (for configs written during this branch's testing phase only). 2. Cache key: replace content-based sha256 hash (ComputeCacheKey) with a random UUID session ID. The agent loop generates one UUID per file in RunPerFile and passes it via ChatRequest.SessionID; the Responses client uses it as prompt_cache_key. Single-turn call sites no longer set a cache key (no multi-turn caching benefit). This removes the need to scan messages or compute hashes, and eliminates collision risk between files with similar content. ChatRequest.CacheKey is renamed to SessionID to reflect its actual semantic — a per-session identifier that the Responses client repurposes as prompt_cache_key. Also updates PLAN_RESPONSES_SUPPORT.md, all 5 README translations, test expectations, and promotes google/uuid to a direct dependency. * refactor(llm): remove IsAnthropicProtocol helper and anthropic-vertex special case * refactor(llm): remove openai-chat-completions branch-internal alias * docs: remove DESIGN_STATE_CACHE_PHASE and PLAN_RESPONSES_SUPPORT design notes * fix(llm): address code review findings on Responses API support - provider_cmd: clear stale use_anthropic when switching to openai-responses - resolver: validate preset protocol with ValidateProtocol for consistency - responses_client: swap usage mapping to resolveUsage-first (matches OpenAIClient) - responses_client: map failed/cancelled statuses to 'error' finish reason - usage_resolver: add Responses API field paths (input_tokens, output_tokens, input_tokens_details.cached_tokens) - add tests for all four fixes * fix(llm): mirror use_anthropic when setting llm.protocol - config_cmd: 'ocr config set llm.protocol' now mirrors use_anthropic (anthropic -> true, OpenAI family -> false) for backward compat with older binaries that predate llm.protocol - provider_cmd: openai-responses now sets use_anthropic=false instead of nil, so older binaries fall back to the OpenAI family rather than wrongly defaulting to anthropic - update tests for both write paths * fix(llm): mirror protocol when setting llm.use_anthropic - config_cmd: 'ocr config set llm.use_anthropic' now mirrors protocol (true -> anthropic, false -> openai) so the two fields never disagree, matching the reverse llm.protocol mirroring added previously - without this, setting use_anthropic=true while protocol=openai-responses left a contradictory config that misled older binaries into using the anthropic protocol against an OpenAI endpoint - extend tests to cover both values and stale-protocol overwrite * docs(llm): fix NormalizeProtocol comment to match lowercasing behavior The comment claimed unknown values are 'returned unchanged', but the default branch lowercases and trims them (corroborated by the 'gRPC -> grpc' test). Update the wording to describe the actual behavior so callers aren't misled about round-trip fidelity. * docs(llm): drop OpenAI Responses API implementation notes from READMEs * fix(llm): address code review findings on Responses API support - config: preserve openai-responses when setting llm.use_anthropic=false (only mirror to openai when protocol is unset or a legacy anthropic/openai) - config: add Protocol values guidance to unknown-key error message - protocol: extract normalized local var in NormalizeProtocol - responses_client: align SDK base URL trimming with NewOpenAIClient - responses_client: drop unused test-only sdkBaseURL method * fix(llm): use protocol constants consistently - providers: edenai now uses ProtocolOpenAIChatCompletions like the rest of the registry instead of the "openai" string literal - provider_cmd: print the normalized protocol variable (what is actually saved) instead of the raw TUI value * fix(llm): drop stream key and surface non-completed status in Responses client Address two PR review comments on OpenAI Responses API support: 1. extra_body.stream=true was forwarded to Responses.New, making the API return SSE while the SDK expects JSON and breaking every call. Skip the 'stream' key (like OpenAIClient treats it as a non-forwarded key) while still forwarding other extra_body entries. 2. The Responses API returns HTTP 200 even for failed/cancelled (terminal) and queued/in_progress (background) states, so the SDK reports nil error. Surface these as real errors so callers branching on err != nil (ocr llm test, review loop) fail instead of treating a dead response as success. Add table-driven tests covering both fixes.
1 parent a32f852 commit f58b0f2

25 files changed

Lines changed: 2055 additions & 108 deletions

‎README.ja-JP.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ ocr config set custom_providers.my-gateway.api_key your-api-key-here
219219
ocr config set custom_providers.my-gateway.model gpt-4o
220220
```
221221

222-
> カスタムプロバイダーでは`url`と`protocol`が必須です。サポートされるプロトコル：`anthropic`、`openai`。
222+
> カスタムプロバイダーでは`url`と`protocol`が必須です。サポートされるプロトコル：`anthropic`、`openai`、`openai-responses`。
223223
224224
オプション設定：
225225

@@ -253,6 +253,17 @@ export OCR_LLM_MODEL=claude-opus-4-6
253253
export OCR_USE_ANTHROPIC=true
254254
```
255255

256+
OpenAI Responses API（GPT-5.x / o-シリーズモデル）を使うには、`OCR_USE_ANTHROPIC` の代わりに `OCR_LLM_PROTOCOL` を設定してください:
257+
258+
```bash
259+
export OCR_LLM_URL=https://api.openai.com/v1
260+
export OCR_LLM_TOKEN=your-openai-key
261+
export OCR_LLM_MODEL=gpt-5.4
262+
export OCR_LLM_PROTOCOL=openai-responses
263+
```
264+
265+
`OCR_LLM_PROTOCOL` は `anthropic`、`openai`、`openai-responses`を受け付け、`OCR_USE_ANTHROPIC` と同時に設定した場合は優先されます。
266+
256267
Claude Codeの環境変数（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`）とも互換性があり、`~/.zshrc` / `~/.bashrc`からこれらのexportをパースします。
257268

258269
> **CC-Switchユーザー向けの注意**: [CC-Switch](https://github.com/farion1231/cc-switch)を[ルーティングサービス](https://www.ccswitch.io/en/docs?section=proxy&item=service)有効で使用している場合、プロバイダーの`url`をCC-Switchのプロキシアドレスに向けることで、追加設定なしで利用できます：
@@ -752,7 +763,7 @@ OCRは4層の優先度チェーンを使ってレビュールールを解決し
752763
| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` |
753764
| `providers.<name>.api_key` | string | プロバイダー固有のAPIキー |
754765
| `providers.<name>.url` | string | プロバイダーのベースURLオーバーライド |
755-
| `providers.<name>.protocol` | string | `anthropic` \| `openai` |
766+
| `providers.<name>.protocol` | string | `anthropic` \| `openai` \| `openai-responses` |
756767
| `providers.<name>.model` | string | プロバイダーのモデル名 |
757768
| `providers.<name>.models` | array | 対話的選択に使う任意のプロバイダーモデル一覧 |
758769
| `providers.<name>.auth_header` | string | `x-api-key` \| `authorization` |
@@ -767,7 +778,8 @@ OCRは4層の優先度チェーンを使ってレビュールールを解決し
767778
| `llm.timeout_sec` | integer | リクエストごとのHTTPタイムアウト（秒）、デフォルト `300` |
768779
| `llm.extra_headers` | string | カンマ区切りの `key=value` HTTPヘッダー |
769780
| `llm.model` | string | `claude-opus-4-6` |
770-
| `llm.use_anthropic` | boolean | `true` \| `false` |
781+
| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`；`llm.use_anthropic` より優先 |
782+
| `llm.use_anthropic` | boolean | `true` \| `false`（レガシー；`llm.protocol` を推奨） |
771783
| `mcp_servers.<name>.command` | string | MCPサーバーを起動するコマンド |
772784
| `mcp_servers.<name>.args` | array | MCPサーバーのコマンドライン引数 |
773785
| `mcp_servers.<name>.env` | array | 環境変数（`KEY=VALUE`形式） |
@@ -827,9 +839,9 @@ ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index'
827839
| `OCR_LLM_AUTH_HEADER` | Anthropic認証ヘッダー（`x-api-key`または`authorization`） |
828840
| `OCR_LLM_EXTRA_HEADERS` | カンマ区切りの `key=value` HTTPヘッダー |
829841
| `OCR_LLM_MODEL` | モデル名 |
842+
| `OCR_LLM_PROTOCOL` | プロトコル：`anthropic` \| `openai` \| `openai-responses`；`OCR_USE_ANTHROPIC` より優先 |
830843
| `OCR_LLM_TIMEOUT` | リクエストごとのHTTPタイムアウト（秒）、設定ファイルの `timeout_sec` を上書き |
831-
| `OCR_USE_ANTHROPIC` | `true` = Anthropic、`false` = OpenAI |
832-
844+
| `OCR_USE_ANTHROPIC` | `true` = Anthropic、`false` = OpenAI Chat Completions（レガシー；`OCR_LLM_PROTOCOL` を推奨） |
833845

834846
## テレメトリー
835847

‎README.ko-KR.md‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ ocr config set custom_providers.my-gateway.api_key your-api-key-here
219219
ocr config set custom_providers.my-gateway.model gpt-4o
220220
```
221221

222-
> 커스텀 provider에서는 `url`과 `protocol`이 필수입니다. 지원 프로토콜: `anthropic`, `openai`.
222+
> 커스텀 provider에서는 `url`과 `protocol`이 필수입니다. 지원 프로토콜: `anthropic`, `openai`, `openai-responses`
223223
224224
선택 설정:
225225

@@ -253,6 +253,17 @@ export OCR_LLM_MODEL=claude-opus-4-6
253253
export OCR_USE_ANTHROPIC=true
254254
```
255255

256+
OpenAI Responses API(GPT-5.x / o-시리즈 모델)를 사용하려면 `OCR_USE_ANTHROPIC` 대신 `OCR_LLM_PROTOCOL`을 사용하세요:
257+
258+
```bash
259+
export OCR_LLM_URL=https://api.openai.com/v1
260+
export OCR_LLM_TOKEN=your-openai-key
261+
export OCR_LLM_MODEL=gpt-5.4
262+
export OCR_LLM_PROTOCOL=openai-responses
263+
```
264+
265+
`OCR_LLM_PROTOCOL`은 `anthropic`, `openai`, `openai-responses`를 허용하며, `OCR_USE_ANTHROPIC`과 함께 설정하면 우선 적용됩니다.
266+
256267
Claude Code 환경 변수(`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`)와도 호환되며, `~/.zshrc` / `~/.bashrc`의 export도 파싱합니다.
257268

258269
> **CC-Switch 사용자 참고**: [CC-Switch](https://github.com/farion1231/cc-switch)를 [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service)와 함께 사용한다면, provider의 `url`을 CC-Switch proxy 주소로 지정하여 추가 설정 없이 사용할 수 있습니다:
@@ -710,7 +721,7 @@ Config file: `~/.opencodereview/config.json`
710721
| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` |
711722
| `providers.<name>.api_key` | string | Provider별 API key |
712723
| `providers.<name>.url` | string | Provider base URL override |
713-
| `providers.<name>.protocol` | string | `anthropic` \| `openai` |
724+
| `providers.<name>.protocol` | string | `anthropic` \| `openai` \| `openai-responses` |
714725
| `providers.<name>.model` | string | Provider의 model 이름 |
715726
| `providers.<name>.models` | array | 대화형 선택에 사용할 optional provider model 목록 |
716727
| `providers.<name>.auth_header` | string | `x-api-key` \| `authorization` |
@@ -725,7 +736,8 @@ Config file: `~/.opencodereview/config.json`
725736
| `llm.timeout_sec` | integer | 요청당 HTTP timeout(초), 기본값 `300` |
726737
| `llm.extra_headers` | string | 쉼표로 구분된 `key=value` HTTP 헤더 |
727738
| `llm.model` | string | `claude-opus-4-6` |
728-
| `llm.use_anthropic` | boolean | `true` \| `false` |
739+
| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; `llm.use_anthropic`보다 우선 |
740+
| `llm.use_anthropic` | boolean | `true` \| `false` (레거시; `llm.protocol` 권장) |
729741
| `mcp_servers.<name>.command` | string | MCP 서버를 시작하는 명령어 |
730742
| `mcp_servers.<name>.args` | array | MCP 서버의 커맨드라인 인수 |
731743
| `mcp_servers.<name>.env` | array | 환경 변수 (`KEY=VALUE` 형식) |
@@ -785,8 +797,9 @@ ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index'
785797
| `OCR_LLM_AUTH_HEADER` | Anthropic auth header (`x-api-key` 또는 `authorization`) |
786798
| `OCR_LLM_EXTRA_HEADERS` | 쉼표로 구분된 `key=value` HTTP 헤더 |
787799
| `OCR_LLM_MODEL` | Model name |
800+
| `OCR_LLM_PROTOCOL` | 프로토콜: `anthropic` \| `openai` \| `openai-responses`; `OCR_USE_ANTHROPIC`보다 우선 |
788801
| `OCR_LLM_TIMEOUT` | 요청당 HTTP timeout(초), config file의 `timeout_sec`를 override |
789-
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI |
802+
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (레거시; `OCR_LLM_PROTOCOL` 권장) |
790803

791804
## Telemetry
792805

‎README.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ ocr config set custom_providers.my-gateway.api_key your-api-key-here
219219
ocr config set custom_providers.my-gateway.model gpt-4o
220220
```
221221

222-
> `url` and `protocol` are required for custom providers. Supported protocols: `anthropic`, `openai`.
222+
> `url` and `protocol` are required for custom providers. Supported protocols: `anthropic`, `openai`, `openai-responses`.
223223
224224
Optional settings:
225225

@@ -253,6 +253,17 @@ export OCR_LLM_MODEL=claude-opus-4-6
253253
export OCR_USE_ANTHROPIC=true
254254
```
255255

256+
To use the OpenAI Responses API (GPT-5.x / o-series), set `OCR_LLM_PROTOCOL` instead of `OCR_USE_ANTHROPIC`:
257+
258+
```bash
259+
export OCR_LLM_URL=https://api.openai.com/v1
260+
export OCR_LLM_TOKEN=your-openai-key
261+
export OCR_LLM_MODEL=gpt-5.4
262+
export OCR_LLM_PROTOCOL=openai-responses
263+
```
264+
265+
`OCR_LLM_PROTOCOL` accepts `anthropic`, `openai`, `openai-responses`, and takes priority over `OCR_USE_ANTHROPIC` when both are set.
266+
256267
Also compatible with Claude Code environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) and parses `~/.zshrc` / `~/.bashrc` for those exports.
257268

258269
> **Note for CC-Switch Users**: If you are using [CC-Switch](https://github.com/farion1231/cc-switch) with [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service) enabled, you can point the provider's `url` to the CC-Switch proxy address without additional configuration:
@@ -759,7 +770,7 @@ Config file: `~/.opencodereview/config.json`
759770
| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` |
760771
| `providers.<name>.api_key` | string | Provider-specific API key |
761772
| `providers.<name>.url` | string | Provider base URL override |
762-
| `providers.<name>.protocol` | string | `anthropic` \| `openai` |
773+
| `providers.<name>.protocol` | string | `anthropic` \| `openai` \| `openai-responses` |
763774
| `providers.<name>.model` | string | Model name for the provider |
764775
| `providers.<name>.models` | array | Optional provider model list for interactive selection |
765776
| `providers.<name>.auth_header` | string | `x-api-key` \| `authorization` |
@@ -774,7 +785,8 @@ Config file: `~/.opencodereview/config.json`
774785
| `llm.timeout_sec` | integer | Per-request HTTP timeout in seconds (default: `300`) |
775786
| `llm.extra_headers` | string | Comma-separated `key=value` HTTP headers |
776787
| `llm.model` | string | `claude-opus-4-6` |
777-
| `llm.use_anthropic` | boolean | `true` \| `false` |
788+
| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; takes priority over `llm.use_anthropic` |
789+
| `llm.use_anthropic` | boolean | `true` \| `false` (legacy; prefer `llm.protocol`) |
778790
| `mcp_servers.<name>.command` | string | Command to start the MCP server |
779791
| `mcp_servers.<name>.args` | array | Command-line arguments for the MCP server |
780792
| `mcp_servers.<name>.env` | array | Environment variables in `KEY=VALUE` format |
@@ -834,9 +846,9 @@ ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index'
834846
| `OCR_LLM_AUTH_HEADER` | Anthropic auth header (`x-api-key` or `authorization`) |
835847
| `OCR_LLM_EXTRA_HEADERS` | Comma-separated `key=value` HTTP headers |
836848
| `OCR_LLM_MODEL` | Model name |
849+
| `OCR_LLM_PROTOCOL` | Protocol: `anthropic` \| `openai` \| `openai-responses`; takes priority over `OCR_USE_ANTHROPIC` |
837850
| `OCR_LLM_TIMEOUT` | Per-request HTTP timeout in seconds (overrides config file `timeout_sec`) |
838-
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI |
839-
851+
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (legacy; prefer `OCR_LLM_PROTOCOL`) |
840852

841853
## Telemetry
842854

‎README.ru-RU.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ ocr config set custom_providers.my-gateway.api_key your-api-key-here
219219
ocr config set custom_providers.my-gateway.model gpt-4o
220220
```
221221

222-
> Для пользовательских провайдеров `url` и `protocol` обязательны. Поддерживаемые протоколы: `anthropic`, `openai`.
222+
> Для пользовательских провайдеров `url` и `protocol` обязательны. Поддерживаемые протоколы: `anthropic`, `openai`, `openai-responses`.
223223
224224
Дополнительные настройки:
225225

@@ -253,6 +253,17 @@ export OCR_LLM_MODEL=claude-opus-4-6
253253
export OCR_USE_ANTHROPIC=true
254254
```
255255

256+
Чтобы использовать OpenAI Responses API (модели GPT-5.x / o-series), задайте `OCR_LLM_PROTOCOL` вместо `OCR_USE_ANTHROPIC`:
257+
258+
```bash
259+
export OCR_LLM_URL=https://api.openai.com/v1
260+
export OCR_LLM_TOKEN=your-openai-key
261+
export OCR_LLM_MODEL=gpt-5.4
262+
export OCR_LLM_PROTOCOL=openai-responses
263+
```
264+
265+
`OCR_LLM_PROTOCOL` принимает значения `anthropic`, `openai`, `openai-responses` и имеет приоритет над `OCR_USE_ANTHROPIC`, если заданы обе переменные.
266+
256267
Также совместим с переменными окружения Claude Code (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) и разбирает `~/.zshrc` / `~/.bashrc` в поисках соответствующих export'ов.
257268

258269
> **Примечание для пользователей CC-Switch**: если вы используете [CC-Switch](https://github.com/farion1231/cc-switch) с включённым [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service), можно указать в `url` провайдера адрес прокси CC-Switch без дополнительной настройки:
@@ -756,7 +767,7 @@ OCR разрешает правила ревью по цепочке приор
756767
| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` |
757768
| `providers.<name>.api_key` | string | API-ключ провайдера |
758769
| `providers.<name>.url` | string | Переопределение base URL провайдера |
759-
| `providers.<name>.protocol` | string | `anthropic` \| `openai` |
770+
| `providers.<name>.protocol` | string | `anthropic` \| `openai` \| `openai-responses` |
760771
| `providers.<name>.model` | string | Имя модели провайдера |
761772
| `providers.<name>.models` | array | Необязательный список моделей для интерактивного выбора |
762773
| `providers.<name>.auth_header` | string | `x-api-key` \| `authorization` |
@@ -771,7 +782,8 @@ OCR разрешает правила ревью по цепочке приор
771782
| `llm.timeout_sec` | integer | Таймаут HTTP-запроса в секундах, по умолчанию `300` |
772783
| `llm.extra_headers` | string | HTTP-заголовки `key=value` через запятую |
773784
| `llm.model` | string | `claude-opus-4-6` |
774-
| `llm.use_anthropic` | boolean | `true` \| `false` |
785+
| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; имеет приоритет над `llm.use_anthropic` |
786+
| `llm.use_anthropic` | boolean | `true` \| `false` (устаревшее; предпочтительнее `llm.protocol`) |
775787
| `mcp_servers.<name>.command` | string | Команда для запуска MCP-сервера |
776788
| `mcp_servers.<name>.args` | array | Аргументы командной строки для MCP-сервера |
777789
| `mcp_servers.<name>.env` | array | Переменные окружения в формате `KEY=VALUE` |
@@ -831,9 +843,9 @@ ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index'
831843
| `OCR_LLM_AUTH_HEADER` | Заголовок авторизации Anthropic (`x-api-key` или `authorization`) |
832844
| `OCR_LLM_EXTRA_HEADERS` | HTTP-заголовки `key=value` через запятую |
833845
| `OCR_LLM_MODEL` | Имя модели |
846+
| `OCR_LLM_PROTOCOL` | Протокол: `anthropic` \| `openai` \| `openai-responses`; имеет приоритет над `OCR_USE_ANTHROPIC` |
834847
| `OCR_LLM_TIMEOUT` | Таймаут HTTP-запроса в секундах (переопределяет `timeout_sec` из файла конфигурации) |
835-
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI |
836-
848+
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (устаревшее; предпочтительнее `OCR_LLM_PROTOCOL`) |
837849

838850
## Телеметрия
839851

‎README.zh-CN.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ ocr config set custom_providers.my-gateway.api_key your-api-key-here
219219
ocr config set custom_providers.my-gateway.model gpt-4o
220220
```
221221

222-
> 自定义供应商的 `url` 和 `protocol` 为必填项。`protocol` 支持 `anthropic` 和 `openai` 两种。
222+
> 自定义供应商的 `url` 和 `protocol` 为必填项。`protocol` 支持 `anthropic`、`openai`、`openai-responses`。
223223
224224
可选配置项：
225225

@@ -253,6 +253,17 @@ export OCR_LLM_MODEL=claude-opus-4-6
253253
export OCR_USE_ANTHROPIC=true
254254
```
255255

256+
若要走 OpenAI Responses API（GPT-5.x / o-系列模型），请改用 `OCR_LLM_PROTOCOL`：
257+
258+
```bash
259+
export OCR_LLM_URL=https://api.openai.com/v1
260+
export OCR_LLM_TOKEN=your-openai-key
261+
export OCR_LLM_MODEL=gpt-5.4
262+
export OCR_LLM_PROTOCOL=openai-responses
263+
```
264+
265+
`OCR_LLM_PROTOCOL` 接受 `anthropic`、`openai`、`openai-responses`，与 `OCR_USE_ANTHROPIC` 同时设置时优先使用前者。
266+
256267
同时兼容 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。
257268

258269
> **CC-Switch 用户特别提醒**：如果你使用 [CC-Switch](https://github.com/farion1231/cc-switch) 并开启了[路由服务](https://www.ccswitch.io/zh/docs?section=proxy&item=service)，可以将供应商的 `url` 配置成 CC-Switch 启动的代理地址，无需额外配置：
@@ -741,7 +752,7 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
741752
| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` |
742753
| `providers.<name>.api_key` | string | 供应商 API 密钥 |
743754
| `providers.<name>.url` | string | 供应商 Base URL 覆盖 |
744-
| `providers.<name>.protocol` | string | `anthropic` \| `openai` |
755+
| `providers.<name>.protocol` | string | `anthropic` \| `openai` \| `openai-responses` |
745756
| `providers.<name>.model` | string | 供应商模型名称 |
746757
| `providers.<name>.models` | array | 用于交互式选择的可选供应商模型列表 |
747758
| `providers.<name>.auth_header` | string | `x-api-key` \| `authorization` |
@@ -756,7 +767,8 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
756767
| `llm.timeout_sec` | integer | 每次请求的 HTTP 超时时间（秒），默认 `300` |
757768
| `llm.extra_headers` | string | 逗号分隔的 `key=value` HTTP 头 |
758769
| `llm.model` | string | `claude-opus-4-6` |
759-
| `llm.use_anthropic` | boolean | `true` \| `false` |
770+
| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`；优先级高于 `llm.use_anthropic` |
771+
| `llm.use_anthropic` | boolean | `true` \| `false`（兼容字段，推荐改用 `llm.protocol`） |
760772
| `mcp_servers.<name>.command` | string | 启动 MCP 服务器的命令 |
761773
| `mcp_servers.<name>.args` | array | MCP 服务器的命令行参数 |
762774
| `mcp_servers.<name>.env` | array | 环境变量，`KEY=VALUE` 格式 |
@@ -816,9 +828,9 @@ ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index'
816828
| `OCR_LLM_AUTH_HEADER` | Anthropic 认证头（`x-api-key` 或 `authorization`） |
817829
| `OCR_LLM_EXTRA_HEADERS` | 逗号分隔的 `key=value` HTTP 头 |
818830
| `OCR_LLM_MODEL` | 模型名称 |
831+
| `OCR_LLM_PROTOCOL` | 协议：`anthropic` \| `openai` \| `openai-responses`；优先级高于 `OCR_USE_ANTHROPIC` |
819832
| `OCR_LLM_TIMEOUT` | 每次请求的 HTTP 超时时间（秒），覆盖配置文件中的 `timeout_sec` |
820-
| `OCR_USE_ANTHROPIC` | `true` = Anthropic，`false` = OpenAI |
821-
833+
| `OCR_USE_ANTHROPIC` | `true` = Anthropic，`false` = OpenAI Chat Completions（兼容字段，推荐改用 `OCR_LLM_PROTOCOL`） |
822834

823835
## 遥测
824836

0 commit comments

Comments
 (0)