提供商
提供商(provider) 是一个上游 LLM 端点,加上访问它的方式:一个 adapter、一个基础 URL、一种认证模式,以及一个可选的模型列表。提供商配置位于 ~/.opencodex/config.json 的 providers 下。
OpenAI 账户模式
Section titled “OpenAI 账户模式”| Provider id | 用途 | 凭证/账户规则 |
|---|---|---|
openai |
Codex 登录 | Pool(默认)选择主账户和添加账户;Direct 只使用当前 caller/主登录。 |
openai-apikey |
OpenAI API | 只使用配置的 API key/key pool;不读取 Codex 账户。 |
bare gpt-5.6-sol 遵循 Providers 页面中的 Pool/Direct 选项,
openai-apikey/gpt-5.6-sol 选择 API。凭证路径之间不会 fallback。API 元数据为 922,000 context /
922,000 max input;*-pro virtual id 保留在公开状态中,线上改写为 base 模型加
reasoning.mode: "pro"。
若内置 openai 提供商缺失或已禁用,可在仪表盘 Accounts 选择器或 Codex Auth 页面恢复:缺失行会从规范预设创建,已禁用的规范行会在不替换已保存模式/模型设置的情况下重新启用,非规范的 openai 行不会提供该恢复路径。
提供商概览中的账户池容量
Section titled “提供商概览中的账户池容量”Codex 登录使用 Pool 模式时,Providers 概览显示整个账户池的已用容量估算,而不是任意一个 账户的数值。同一行还会显示当前有效账户的原始配额使用率,便于区分账户池估算与下一次请求 将使用的账户状态。
如果有重置信息,概览会显示下一次重置时间以及届时恢复的账户池容量。覆盖不完整表示某些 账户无法安全计入估算,例如套餐或配额未知、读数过旧、账户已暂停或需要重新认证。
部分窗口覆盖不完整表示某些已计入账户只报告了部分显示的配额窗口。概览会保持各窗口相互 独立,逐一标记受影响的窗口,并且不会把缺失值当作该窗口的使用量。
此估算仅用于显示,不会改变账户选择、会话关联、自动切换、cooldown 或任何其他路由决策。 各账户状态和路由控制请参阅 Codex Auth 账户池。
shipped v1 配置自动迁移到 marker 2 的单一选项行。原配置只保留一次到
~/.opencodex/config.json.pre-openai-tiers-v2.bak;恢复命令:
cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json。
提供商配置支持三种 authMode,默认值为 key。内置注册表还会单独标记本地预设;这类预设通常会
同时省略 authMode 和 apiKey。
authMode |
如何进行认证 | 使用方 |
|---|---|---|
key |
发送你的 API 密钥(Authorization: Bearer …,或按 adapter 使用 x-api-key / api-key)。密钥可以是字面值,也可以是 ${ENV_VAR} 引用。 |
大多数提供商。 |
forward |
将你传入的 Codex 认证请求头原样转发给提供商——不存储任何密钥。这就是 ChatGPT 登录的透传方式。 | OpenAI(openai-responses adapter)。 |
oauth |
读取已存储的 OAuth 访问令牌(过期前自动刷新),并将其用作 bearer 密钥。 | xAI、Anthropic、Kimi、Kiro、Google Antigravity、Cursor、Command Code、GitHub Copilot、Nous Portal。 |
retryOn429(同 key 的 429 重试)仅适用于 API-key 提供商
(authMode: "key")。OAuth、forward 与本地预设均被排除——同一 token 绝不可重放,本地运行时
也没有需要保留的远程 key。仅在配置后启用,默认关闭;配置了对象即启用,除非 enabled: false。
1. ChatGPT 登录(forward / 透传)
Section titled “1. ChatGPT 登录(forward / 透传)”默认提供商不需要 API 密钥。它将你现有 codex login 的凭据直接转发到 OpenAI Responses 后端:
{ "openai": { "adapter": "openai-responses", "baseUrl": "https://chatgpt.com/backend-api/codex", "authMode": "forward" }}只有一组精选的请求头会被转发(FORWARD_HEADERS:authorization、ChatGPT account id、OpenAI beta/originator/session——参见 Adapters)。这条路径也为 web-search 和 vision sidecar 提供支持。
ChatGPT 透传目录也会加入 GPT-5.6 Sol/Terra/Luna 的裸 slug(gpt-5.6-sol、
gpt-5.6-terra、gpt-5.6-luna);账号具备相应权限时才能实际调用。
2. 账号登录(OAuth)
Section titled “2. 账号登录(OAuth)”有九个提供商预设使用 OAuth 登录,另加通过实验性非官方设备流桥接的 GitHub Copilot。
opencodex 会把凭据存入 ~/.opencodex/auth.json:可刷新的令牌会自动轮换;OrcaRouter
这类持久密钥会复用到提供商撤销为止。登录 CLI 也接受 ocx login codex,但它并不是上面这些提供商:
它会转到 Codex 账号池登录(与 ocx account login codex 相同的流程)。该账号池有独立的账号台账,
这条路径需要代理正在运行。chatgpt 和 openai 是同一条路径的别名。
ocx login xai # xAI Grokocx login anthropic # Anthropic Claude (Pro/Max)ocx login kimi # Moonshot Kimiocx login nous # Nous Portal(设备授权;免费 + 付费模型)ocx login kiro # 导入 kiro-cli 凭据(支持令牌回退)ocx login google-antigravityocx login cursor # 独立的 Cursor PKCE 登录ocx login command-code # Command Code 浏览器 OAuth(或导入 ~/.commandcode/auth.json)ocx login orcarouter-oauth # OrcaRouter 浏览器授权 + PKCEocx login devin # Cognition/Devin:优先导入 Devin CLI 凭据,否则走 Auth0 浏览器登录ocx login dsh-account # DeepSeek Harness Desktop(导入 ~/.dsh/.credentials.yaml 授权)ocx login github-copilot # GitHub 设备流 → Copilot 令牌(Copilot 账户)ocx login codex # Codex 账号池(别名:chatgpt、openai;需要代理正在运行)ocx logout <provider>| 提供商 | Adapter | 基础 URL | 备注 |
|---|---|---|---|
xai |
openai-chat |
https://cli-chat-proxy.grok.com/v1 |
OAuth 使用独立的 Grok CLI 订阅网关。API 密钥覆盖模式使用 https://api.x.ai/v1,并可能注入 Priority Processing。优先使用实时 Grok 目录;回退默认模型为 grok-4.5。 |
anthropic |
anthropic |
https://api.anthropic.com |
Claude 模型;实时模型列表从 /v1/models 获取。 |
kimi |
openai-chat |
https://api.kimi.com/coding/v1 |
Kimi Code Plan 编程模型。默认使用稳定的 kimi-for-coding 别名(当前指向 K2.8 Preview):100 万 token 上下文、可调 low/high/max 思考档(默认 max)、支持文本 + 图片输入。已下架的 kimi-k2.x 选择会在升级时自动迁移到该别名。进阶:添加 kimi-responses 预设可让同一 Kimi 账号登录走 OpenAI Responses 协议(思考内容在服务端保持加密,工具调用保持可见;Chat 预设保留明文推理)。 |
kimi-responses |
openai-responses |
https://api.kimi.com/coding/v1 |
同一 Kimi 账号登录(复用 kimi 的 OAuth 凭据)走 OpenAI Responses 协议。模型名单与能力与 kimi 相同;思考内容在服务端保持加密,工具调用与结果保持可见。 |
nous |
openai-chat |
https://inference-api.nousresearch.com/v1 |
Nous Research 订阅网关(与 Hermes Agent 使用同一后端)。通过设备授权登录 portal.nousresearch.com;access 令牌是每个请求的 inference JWT。付费 + :free 模型混合目录(tencent/hy3:free、stepfun/step-3.7-flash:free 等)会从已登录账户实时发现。Refresh 令牌是单次使用,每次刷新都会轮换。 |
kiro |
kiro |
https://runtime.us-east-1.kiro.dev |
首次登录会导入已安装并已登录的 Kiro CLI 会话(Unix 使用 curl -fsSL https://cli.kiro.dev/install | bash;Windows PowerShell 使用 irm 'https://cli.kiro.dev/install.ps1' | iex;然后运行 kiro-cli login)。添加账户会先退出 kiro-cli,再启动新的浏览器登录,从而切换 kiro-cli 自身使用的账户,并保存账户范围的配置文件元数据。现有 OpenCodex 账户会保留;如果取消或失败,则恢复之前的 kiro-cli 会话。 |
google-antigravity |
google |
https://daily-cloudcode-pa.googleapis.com |
通过 Cloud Code Assist 协议使用 Google OAuth。实时发现调用已认证的 CCA v1internal:fetchAvailableModels 端点,并仅发布当前登录账户可用的 agent 模型;维护中的目录仍作为回退。 |
cursor |
cursor |
https://api2.cursor.sh |
实验性 PKCE 登录、带可选 HTTP/1.1 兼容路径的 HTTP/2 传输,以及按账号筛选的模型发现。 |
orcarouter-oauth |
openai-chat |
https://api.orcarouter.ai/v1 |
浏览器授权与密钥交换走 https://www.orcarouter.ai + S256 PKCE。交换结果是用户自己的普通 sk-orca-… API key,保存在现有凭据库中并持续复用,直到被撤销。 |
devin |
devin |
https://server.codeium.com |
实验性的非官方 Cognition/Devin 桥接。登录会先导入已安装 Devin CLI 已持有的凭据(devin auth login 会把 devin-session-token 写入它自己的 credentials.toml);没有则打开 Auth0 浏览器页面,再用 RegisterUser 把粘贴的令牌换成长期 API 密钥。ocx login devin-cli 仍作为已弃用别名可用。模型列表按账号通过 GetCascadeModelConfigs 实时获取,流式仅走 Connect-RPC 上的 runTurn 路径。默认不在仪表盘预设中,需要手动启用。 |
dsh-account |
dsh-account |
https://api.deepseek.com/anthropic |
实验性优先导入账户提供商,复用已安装并登录的 DeepSeek Harness (DSH) Desktop 账户。在用户显式导入时严格以只读方式读取 ~/.dsh/.credentials.yaml 中的凭据。独立于 DeepSeek API Key 计费。 |
github-copilot |
openai-chat |
https://api.githubcopilot.com |
实验性。GitHub 设备流 + copilot_internal 交换(VS Code OAuth 客户端)。需要有效的 Copilot 订阅;不是官方第三方 API。 |
Google Antigravity 账户和提供方的配额查询(包括模型列表回退)使用固定的 Google 计量端点。这些目标支持透明 Fake-IP DNS,同时保留 TLS 验证、重定向拒绝和私有地址检查。自定义 base URL 仅改变模型请求,不改变配额目标;NO_PROXY 仍使用直连策略。
Google 工具架构损失诊断
Section titled “Google 工具架构损失诊断”Google 工具声明会按所选端点类别进行编译。通过 ocx debug provider on、仪表盘 Logs 开关或
OCX_DEBUG=1 启用提供方调试后,在省略策略或使用 compatible 的路径上,兼容性转换中的架构损失会输出一条
[ocx:google:google-tool-schema-loss] 记录(可用 ocx debug provider logs -f 持续查看),
其中仅包含报告版本、端点类别、lossy 指示器、有上限的不确定比较计数、带有上限计数的固定损失类别和截断标志,
绝不包含工具名、属性名、路径、值或架构文本。省略策略或使用 compatible 时只观察转换。
在 reject-lossy 下,如果初始编译有损或有界比较结果不确定,则会在发送前拒绝;被拒绝的
请求不会另行输出损失记录。在 reject-lossy 下,会移除约束的
Vertex 或 Cloud Code Assist 修复会输出同样不含内容的 google-tool-schema-repair 记录,并在不发送
修改请求的情况下返回原始 400;省略策略或使用 compatible 时,会像以前一样重放修复后的请求。
直连 AI Studio 不执行该修复。原生输出架构不属于这两条策略路径。
请参阅调试命令参考。
Nous refresh 发生终止性失败后,请运行 ocx login nous 重新认证。
对于规范的 Kimi Coding Plan 预设(kimi 账号登录和 kimi-code API key),opencodex
只会把调用方提供的稳定 prompt_cache_key 转发到 Chat Completions 请求(Responses 协议接受同名字段,但 opencodex 目前不在 Responses 发送它),绝不自行生成。Kimi
文档要求使用稳定的会话/任务 key 来提高 Code Plan 缓存命中率;没有 key 的请求仍保持不带 key。
若已 opt-in 的上游拒绝该字段,opencodex 不会删除字段后重试,也不会改动已保存配置;其他
provider 仍保持 deny-by-default。
Kimi Code 原生 Responses 路由会省略明确正文为空的 assistant 历史消息,避免
assistant must not be empty 拒绝。非空文本、空白字符、拒绝内容、推理与工具调用/结果
保持原样;不会改写客户端存储的历史。被同一输入中的 item_reference 引用的空消息也会保留,
避免留下悬空引用。
kimi、kimi-code 和 kimi-responses 中 k3、k3[1m]、k3-256k 的费用是 API 参考价格估算,
采用已公布的默认 5 分钟缓存写入价格,不代表 Code Plan 的实际账单或额度消耗:K3 的 1M 版本消耗
约为 k3-256k 两倍的额度。kimi-for-coding 已切换为 K2.8 Preview,因此不再使用旧 K2.7 价格;
除非用户配置 modelCosts,否则其估算保持未知。要求已知价格的路由策略或拒绝未知估算的费用上限
可能会排除此别名。参见 Kimi 模型配置 和
API 价格。
你也可以从 web 仪表盘 启动 OAuth。
多个 OAuth 账号
Section titled “多个 OAuth 账号”OAuth 凭据中带有稳定账号 id 或邮箱的提供商可以保存多个登录。Providers 页面会在下拉列表中显示这些
账号,允许继续添加,并在不登出其他账号的情况下切换当前账号。普通登录时,没有身份信息的 Kimi 凭据会替换
当前 active slot;显式 添加账号 会保留原有 slot 并激活一个独立的新 slot。Kiro 账户以配置文件 ARN 为键。
chatgpt 始终只有一个 slot,因为 Codex 账号池使用独立存储。令牌仍保存在
~/.opencodex/auth.json 中;/api/oauth/accounts 只返回脱敏后的 metadata。
Cockpit Tools Antigravity 导入
Section titled “Cockpit Tools Antigravity 导入”v1 中 OpenCodex 仅支持为 google-antigravity 提供商导入 Cockpit Tools Antigravity JSON 导出文件。在 Providers 仪表板中打开该提供商的 Accounts 标签并选择本地 JSON 文件。仪表板不会显示文件内容或凭据值,只报告已导入、已更新、失败和不支持的数量。v1 会拒绝其他 Cockpit 提供商的导入。
CLI 仅从文件或标准输入读取导出文件,不能将其粘贴到命令参数中:
ocx account import google-antigravity --format cockpit-tools --file <path> [--json]cat accounts.json | ocx account import google-antigravity --format cockpit-tools --stdin [--json]内联 JSON 和额外的位置参数会被拒绝。请将导出的文件保密,并在导入后删除或安全存储。
Kiro 凭据导入
Section titled “Kiro 凭据导入”Kiro 登录需要 Kiro CLI:Unix 使用 curl -fsSL https://cli.kiro.dev/install | bash 安装;Windows PowerShell 使用 irm 'https://cli.kiro.dev/install.ps1' | iex;然后先运行 kiro-cli login。如果没有 kiro-cli 会话,ocx login kiro 会回退到粘贴的访问令牌或 KIRO_ACCESS_TOKEN 环境变量。
普通的 ocx login kiro 导入会以只读方式打开 CLI SQLite 数据库,不修改数据库、WAL 或 SHM。
KIROCLI_DB_PATH用于选择非标准位置的 Kiro CLI SQLite 数据库;指定的数据库必须已经存在。KIROCLI_TOKEN_KEY在存在多个含糊的令牌行时选择确切的auth_kv行键。缺少选择值时,登录会失败而不会猜测。
导入的凭据会保存到 ~/.opencodex/auth.json。添加账户的回滚是独立流程:恢复之前的快照时会替换数据库,并删除当前的 WAL、SHM 和 journal 边车文件。
由于回滚依赖快照,当会话存储已存在但无法捕获时(文件不可读、架构不匹配、令牌选择有歧义),当 KIROCLI_DB_PATH / KIRO_CLI_DB_FILE 将导入路径指向与活动 CLI 存储不同的位置时,或当主 CLI 数据库没有可识别的令牌行时,添加账户会拒绝将 kiro-cli 登出。请修复或删除常规 kiro-cli 数据路径下的损坏数据库,并取消仅用于导入的选择器后重试。对于完全没有现有 kiro-cli 会话的机器,不受影响。
DeepSeek Account (DSH)
Section titled “DeepSeek Account (DSH)”dsh-account 是一个实验性的、优先导入已有凭据的账户提供商,用于复用已安装并登录的 DeepSeek Harness (DSH) Desktop 应用程序的认证凭据。
- 独立于 DeepSeek API Key:
dsh-account使用用户的 DeepSeek 认证会话配额(普通/赠送钱包余额与总消费),而deepseek提供商按平台的 API Key 余额扣费。这两个凭据体系和路由严格隔离,互不回退。 - 仅显式导入:OpenCodeX 会检测是否已安装 DeepSeek Harness 且已登录(
~/.dsh/.credentials.yaml),但绝不会在没有用户明确操作(ocx login dsh-account或在 Web 仪表盘点击导入)的情况下自动复制、导入或使用该令牌。 - 对 DSH 凭据库只读:OpenCodeX 将
~/.dsh/.credentials.yaml视为严格只读。OpenCodeX 绝不写入、修改、删除或更改任何属于 DeepSeek Harness 的文件权限。 - 隔离的凭据副本与登出:导入后,OpenCodeX 会通过 DeepSeek 权威身份端点(
/auth-api/v0/users/current)校验令牌,并在 OpenCodeX 认证库中保存独立副本。在 OpenCodeX 中登出或删除该账户仅会删除 OpenCodeX 本地副本,绝不会触发上游远程会话登出,也不会退出 DeepSeek Harness Desktop。 - 无后台令牌自动刷新与 401 重新导入:DSH 会话授权不支持自动后台刷新端点。若上游返回 HTTP 401(
ACCOUNT_TOKEN_INVALID),OpenCodeX 将该账户标记为needsReauth并停止路由。要恢复访问,用户必须通过ocx login dsh-account显式重新导入。 - 第三方免责声明:OpenCodeX 不主张 DeepSeek 官方对于第三方客户端复用会话授权提供背书或支持。
3. API 密钥目录
Section titled “3. API 密钥目录”opencodex 内置 104 个预设:84 个密钥预设、16 个 OAuth 预设、3 个本地预设,以及 1 个默认的 ChatGPT 转发预设。仪表盘的 Add provider 选择器会打开密钥提供商的控制台,验证并保存密钥。 验证因提供商而异。主要条目包括:
ClinePass 使用 Cline API 密钥连接官方订阅目录和
Chat Completions 端点。运营主体是
Cline 条款所列的 Cline Bot Inc.。
cline-pass/cline-pass/kimi-k3 这样的路由 ID 是预期格式:第一段选择 opencodex 提供商,
其余的 cline-pass/kimi-k3 是发送到上游的完整模型 slug。用量由账户的滚动 5 小时、每周和
每月限额共同管理。2026-08-13 的实测确认,所有静态 ClinePass 模型在网关输入端都接受
low、medium、high、xhigh 和 max。opencodex 会保留请求的档位;后端特定的规范化由 ClinePass 负责。
Cline 使用相同的 API 密钥和端点,按用量计费,可访问 100 多个模型
(OpenRouter 风格 ID,如 anthropic/claude-sonnet-4-6)。Cline 的促销免费模型仅在
Cline IDE/CLI 中提供,不能通过 API 使用;minimax/minimax-m2.5 是文档中通过 API
免费试用的模型。
| 提供商 | 基础 URL |
|---|---|
| OpenAI (API key) | https://api.openai.com/v1 |
| Anthropic (API key) | https://api.anthropic.com |
| OpenRouter | https://openrouter.ai/api/v1 |
| Cline | https://api.cline.bot/api/v1 |
| ClinePass | https://api.cline.bot/api/v1 |
| Ollama Cloud | https://ollama.com/v1 |
| Google Gemini · Google Vertex AI | https://generativelanguage.googleapis.com · https://aiplatform.googleapis.com |
| Azure OpenAI | https://{resource}.openai.azure.com/openai |
| Umans AI · Neuralwatt | https://api.code.umans.ai · https://api.neuralwatt.com/v1 |
| Mistral | https://api.mistral.ai/v1 |
| MiniMax · MiniMax (CN) | https://api.minimax.io/v1 · https://api.minimaxi.com/v1 |
| DeepSeek | https://api.deepseek.com |
| Cerebras | https://api.cerebras.ai/v1 |
| Chutes | https://llm.chutes.ai/v1 |
| DeepInfra | https://api.deepinfra.com/v1/openai |
| Hyperbolic | https://api.hyperbolic.xyz/v1 |
| Nscale Serverless Inference | https://inference.api.nscale.com/v1 |
| Vultr Serverless Inference | https://api.vultrinference.com/v1 |
| Baseten Model APIs | https://inference.baseten.co/v1 |
| Command Code | https://api.commandcode.ai/provider/v1 |
| SambaNova Cloud | https://api.sambanova.ai/v1 |
| Nebius Token Factory | https://api.tokenfactory.nebius.com/v1 |
| Crusoe | https://api.inference.crusoecloud.com/v1 |
| DigitalOcean Serverless Inference | https://inference.do-ai.run/v1 |
| Scaleway Generative APIs | https://api.scaleway.ai/v1 |
| Featherless AI | https://api.featherless.ai/v1 |
| Novita AI | https://api.novita.ai/openai/v1 |
| Together | https://api.together.xyz/v1 |
| Fireworks | https://api.fireworks.ai/inference/v1 |
| Moonshot (Kimi API) · Kimi (coding) | https://api.moonshot.ai/v1 · https://api.kimi.com/coding/v1 |
| Hugging Face | https://router.huggingface.co/v1 |
| NVIDIA NIM | https://integrate.api.nvidia.com/v1 |
| Z.AI (GLM Coding) | https://api.z.ai/api/coding/paas/v4 |
| 智谱 AI (BigModel) | https://open.bigmodel.cn/api/paas/v4 |
| BigModel Coding Plan — Responses (静态模型列表) | https://open.bigmodel.cn/api/v1 |
| Qwen Cloud | Token plan(默认): https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 · 按量付费: https://dashscope.aliyuncs.com/compatible-mode/v1 · 或自定义 |
| 腾讯云 Coding Plan | https://api.lkeap.cloud.tencent.com/coding/v3 |
| SiliconFlow | https://api.siliconflow.cn/v1 |
| 火山方舟 · Coding Plan · Agent Plan | https://ark.cn-beijing.volces.com/api/v3 · https://ark.cn-beijing.volces.com/api/coding/v3 · https://ark.cn-beijing.volces.com/api/plan/v3 |
| Xiaomi MiMo | https://api.xiaomimimo.com/anthropic |
| Xiaomi MiMo (OpenAI Chat) | https://api.xiaomimimo.com/v1 |
| Kilo | https://api.kilo.ai/api/gateway |
| OpenGateway | https://apis.opengateway.ai/v1 |
| GitLab Duo | https://cloud.gitlab.com/ai/v1/proxy/openai/v1 |
| Cloudflare AI Gateway | https://gateway.ai.cloudflare.com/v1/{account-id}/{gateway}/anthropic |
| ……以及更多 | opencode zen、Vercel AI Gateway、Venice、NanoGPT、Synthetic、Qianfan、Alibaba、Parallel、ZenMux、LiteLLM |
OpenGateway 是 Sionic AI 运营的 OpenAI 兼容网关,base URL 为
https://apis.opengateway.ai/v1。公开目录包含约 80 个活跃模型(2026-10-02 核实)。
预设通过公开 GET /v1/models 自动刷新列表,仅保留活跃的 Chat Completions 模型(以及仅支持 Responses、并固定走 Responses 的 openai/o3-pro)。
Sionic 提供的 deepseek/deepseek-v4.1-flash-ultrafast 和
z-ai/glm-5.3-flash-ultrafast 排在最前。请在
OpenGateway 控制台创建密钥,再运行
ocx provider add opengateway 或在控制台选择 OpenGateway。Chat 请求使用配置的
Bearer 密钥;公开模型列表不能验证密钥有效性。
MiniMax 和 MiniMax (CN) 的提供商卡片也会在配置的密钥有有效 Coding Plan 时显示用量。 仪表盘读取 5 小时窗口,以及套餐提供时的每周窗口;这些仅用于展示,不会改变模型路由。
OpenCode Zen(opencode-zen)使用 opencode.ai/auth 签发的 API 密钥访问 https://opencode.ai/zen/v1。免费模型可能触发每分钟约 15–20 次请求的短窗口限流(社区观测;OpenCode 未公布 RPM)。限流 429 缺少 Retry-After 时,opencodex 会添加说明和合成的 Retry-After;有效的上游头优先。同密钥重试仍须通过 retryOn429 启用。
在规范 opencode-zen 提供商中,使用 API 密钥认证和官方路由 https://opencode.ai/zen/v1 或 https://opencode.ai/inference/v1 时,Gemini 会在默认 googleMode: ai-studio 下自动使用 Google 原生 API。Zen 模型 ID 保持不变,包括没有 -tiered 后缀的 Flash ID。Claude 使用 Anthropic Messages,不受 googleMode 影响。加载已保存的配置时,仅忽略这些原生模型符合条件的旧 Chat/Responses 覆盖设置,以及符合条件的 Responses 专用 image_generation 托管工具偏好。自定义提供商、非密钥认证路由及其他偏好保持不变。
已移除 opencode-free 支持。 OpenCode 的上游免费层级门槛导致所有模型均返回 403 permission_denied(#7255)。加载现有配置时,会在内存中禁用相关条目和依赖的模型引用,每个进程仅警告一次,不修改文件。如果它原来是默认提供商,将改用标准 OpenAI OAuth 路径作为默认值。请使用 opencode-go、需要密钥的 opencode-zen 或其他提供商。OpenCode Zen 条款。
保留正常的 Claude Desktop 分配和默认值。源模型允许列表变空的规则会被禁用;注入模型被移除时,原生子代理同步也会被禁用。后续保存配置时不会恢复已移除的引用,并会保留正常的并发编辑。
大多数使用带 bearer 密钥的 openai-chat adapter;Xiaomi MiMo(xiaomi)等 Anthropic 兼容预设
使用 anthropic adapter(x-api-key)。小米还提供 OpenAI Chat 预设 xiaomi-mimo 和 token plan 预设
mimo。三个预设默认都使用 MiMo V2.6(mimo-v2.6-pro;xiaomi-mimo 使用 mimo-v2.6-flash)。
小米将在 2026-10-21 停用 mimo-v2.5 和 mimo-v2.5-pro,且不会重定向;若已将 V2.5 保存为默认模型,
请在此日期前手动切换,opencodex 不会替你改写配置。
火山方舟 Coding Plan 和 Agent Plan 都通过 openai-responses adapter 使用原生 Responses 端点。在已验证的 Ark Coding Plan 工具调用 continuation 中,回放上一次 Responses 返回的 reasoning item 会触发 400 InvalidParameter,因此 Coding Plan 预设会在转发 continuation input 前移除这类 replayed reasoning item;这会丢失该轮的 reasoning 状态,可用 dropResponsesReasoningItems: false 关闭。已经保存为 openai-chat 的 Coding Plan 配置不会被改写,仍按 Chat 走;如需切换,请手动把 adapter 改为 openai-responses 并把 responsesPath 设为 /responses,或删除后重新添加该预设。显式的逐模型 openai-chat override 仍可使用。
内置 DeepSeek preset 同样会让 deepseek-v4-flash 使用原生 Responses 端点,并保留上游 SSE
流式输出。如果该模型已经完成全部输出项却缺少最终 Responses 事件,opencodex 会应用模型级
5 秒宽限修复;不完整或格式异常的流会以 incomplete 结束,不会被误报为成功。
第一方 deepseek-flash 模型原生声明支持 text 和 image 输入,因此图像请求默认会直接发送给
DeepSeek,不经过 vision sidecar。显式的 noVisionModels 或纯文本声明仍然优先。第一方
deepseek-chat、deepseek-reasoner 和 deepseek-v4-flash 默认仍使用 sidecar;Zen 路由保持不变,
本次更新未进行探测。
三条火山方舟计费线路:
volcengine是按量付费方舟 API,volcengine-coding-plan消耗 Coding Plan 额度,volcengine-agent-plan消耗 Agent Plan 额度。密钥与端点需要属于 同一产品;已经订阅 Plan 时调用普通/api/v3端点仍可能产生按量费用。 三个 preset 使用经过筛选的静态模型目录:方舟/models同时返回文本、Embedding、图片、 视频和 3D 资源,Coding 网关也会返回这份宽泛目录,Agent Plan 网关没有/models资源。 按量付费默认使用doubao-seed-2-1-pro-260628,静态目录还包含当前 DeepSeek 和 GLM 文本模型。Coding Plan 默认使用ark-code-latest,Agent Plan 默认使用deepseek-v4-flash。
Chutes 发现:chutes 预设使用 Chutes 固定的共享 OpenAI 兼容 LLM gateway。它读取公开的
/v1/models 目录,仅保留 supported_features 包含 tools 的记录,保留含 / 的原生 model id 与
安全的实时 metadata,并把发现限制为 256 KiB 和 128 条原始记录。由于该目录公开,它无法证明输入的
密钥有效;chat 请求仍会使用已配置的 Bearer 密钥认证。用户自行部署的 custom Chute host 与非 LLM API
需要使用 custom provider。密钥可在 Chutes dashboard 创建。
DeepInfra 发现:deepinfra 是使用 openai-chat adapter 和 Bearer API 密钥的密钥型
OpenAI Chat Completions 提供商。registry 固定的 DeepInfra 模型列表 URL 仅保留带 chat 标签的记录,
同时保留含 / 的原生模型 id,并把实时发现限制为 512 KiB 和 512 条原始记录。
密钥可在 DeepInfra 控制台创建。
**Hyperbolic 发现:**该预设会使用已配置的 bearer 密钥读取 /v1/models,保留含 / 的原生模型 id,
并将实时发现限制为 256 KiB 和 256 条原始记录。它仅覆盖 serverless text 与 vision-language chat;独立的
image、audio 和 GPU 端点不在范围内。密钥可在 Hyperbolic 创建。
**Nscale 与 Vultr 发现:**两个预设都会读取需要认证的 /v1/models 目录、保留原生模型 id,并将发现限制为
256 KiB 和 256 条原始记录。Nscale 的目录没有 modality 字段,却混合了 chat、image 与 embedding 模型,
所以预设仅允许其官方工具调用 API 示例使用的 meta-llama/Llama-3.1-8B-Instruct。Vultr 目前只明确
kimi-k2-instruct 支持工具调用,因此其预设仅暴露这一模型。其他记录会保持隐藏,直到提供商发布同等的
agent-tool 证据。Nscale service token 可在 Nscale Console 创建;Vultr
inference key 可从 Vultr Console 的订阅概览复制。
**Command Code 发现:**该预设从固定的 Provider API 主机读取 Command Code 的
/provider/v1/models 列表,保留提供商原生模型 id,并将实时发现限制为 256 KiB 和 256 条原始记录。
ocx login command-code 支持通过浏览器进行 OAuth 登录(现有 Command Code CLI 用户还可选择从
~/.commandcode/auth.json 导入本地 CLI 凭据);模型目录按账户隔离,并在登录后从经过认证的发现
端点获取。Provider API 预设(commandcode)使用当前配置的密钥:大多数模型 id 通过带 Bearer 头的
Chat Completions 请求调用;claude-* 模型 id 则通过带 x-api-key 的 Anthropic Messages 请求调用,
因为 Command Code 只在 /provider/v1/messages 上提供这些模型。若其他提供商复用 commandcode 名称
但使用不同端点,它仍保持自己的请求协议。OAuth 预设(command-code)使用已保存的账户 bearer 令牌
进行认证后的模型发现,并从 /alpha/generate 以 NDJSON 流式生成。若网关将 MiMo 工具调用标记作为文本
回显,而实际工具调用已存在,则会移除重复标记。对于 MiMo 模型,只有在响应正常结束后,才会将没有
对应原生调用的完整声明工具调用恢复为实际调用;中断或被过滤的轮次会保留文本形式的标记。
Provider API 密钥可在 Command Code Studio 创建。
**OrcaRouter 认证与模型发现:**可用 ocx login orcarouter-oauth 走浏览器一键授权,
也可用 ocx login orcarouter 粘贴已有 API key。PKCE 流程会先监听本机回环端口,为每次登录
生成新的 S256 challenge 和 state;授权页使用 https://www.orcarouter.ai/auth,并通过
https://www.orcarouter.ai/api/v1/auth/keys 交换一次性 code,再把返回的
用户自有 key 保存到 ~/.opencodex/auth.json;手填 key 仍使用项目原有的 provider key 存储。
两种模式都访问 https://api.orcarouter.ai/v1,并使用 capability=chat 实时发现模型;图片生成、
视频和 rerank 条目会被排除,模型返回的 input modalities 决定 Codex 是否允许图片附件。
由于模型目录本身是公开的,手填 key 时会诚实显示“无法验证”,不会把公开目录的 200 响应误当成
密钥有效证明。
OrcaRouter 浏览器登录(ocx login orcarouter-oauth)的密钥交换成功响应正文必须是不超过
64 KiB 的有效 UTF-8 JSON。该交换请求现有的 30 秒时限覆盖响应头和完整正文的接收;超大或
格式错误的正文会在保存密钥前被拒绝。这些限制仅适用于登录密钥交换,不是推理请求负载的
限制。scope 校验规则保持不变:允许省略,明确无效的值仍会被拒绝。
单域名自托管环境可在第一次 PKCE 登录前设置统一 origin;推理地址会从同一个 origin 派生:
ORCAROUTER_BASE_URL=https://router.example ocx login orcarouter-oauth若自托管环境也分离登录域名与 API 域名,可分别设置 ORCAROUTER_AUTH_BASE_URL 和
ORCAROUTER_API_BASE_URL。
该值必须是 HTTPS origin(本地开发可使用 HTTP loopback),且不能包含用户名密码、query 或 fragment。
首次登录回环或私有网络中的自托管服务前,必须在 ~/.opencodex/config.json 中明确允许访问该地址。
例如,将以下条目合并到现有的 providers 对象中,用于本地开发服务:
{ "orcarouter-oauth": { "adapter": "openai-chat", "baseUrl": "http://127.0.0.1:9999/v1", "authMode": "oauth", "allowPrivateNetwork": true }}然后运行 ORCAROUTER_BASE_URL=http://127.0.0.1:9999 ocx login orcarouter-oauth。
登录会保留这项明确授权;仅设置 URL 不会自动启用私有网络访问。
未设置此选项时,目标地址校验会拒绝该服务的推理和模型发现请求。
此要求针对 provider 的服务地址,浏览器回调监听器不需要此选项。
若 relay 返回 401,重新运行登录即可;OrcaRouter 签发的是长期 API key,不存在 refresh-token grant。
**Command Code 配额:**仪表盘和 ocx account refresh 会在规范主机 https://api.commandcode.ai 上探测 /alpha/billing/credits 窗口(5 小时和每周)。OAuth 预设 (command-code) 使用已保存的账户 bearer;Provider-API 密钥预设 (commandcode) 使用当前配置的有效密钥。用户改写后的仿冒 base URL 不会被探测。当 Command Code 同时返回周期消耗时,剩余的 monthly / purchased / free credits 会显示为 USD 窗口。
**SambaNova Cloud 发现:**该预设从固定 API 主机读取 SambaNova Cloud 的公开 /v1/models 列表,保留提供商原生
模型 id,并将发现限制为 128 KiB 和 128 条原始记录。该目录无需鉴权,因此 CLI 登录流程不会把公开响应
当作密钥有效性的证明,而会将密钥报告为无法验证。chat 请求仍使用已配置的 Bearer 密钥;由于 SambaNova
尚不支持并行 function call,该能力会被禁用。私有 SambaStudio 部署端点不在范围内。
密钥可在 SambaNova Cloud 创建。
**Nebius Token Factory 发现:**该预设请求需要鉴权的 verbose 模型目录,仅保留 architecture 输出 text
的记录,从而排除 embedding 和 image-generation 模型。它保留含 / 的原生模型 id、上游报告的 context
和 input modality metadata,并将发现限制为 512 KiB 和 512 条原始记录。dedicated deployment 主机不在
范围内。密钥可在 Nebius Token Factory 创建。
**Crusoe 发现:**密钥预设使用 openai-chat adapter,并只向 Crusoe 固定的 Serverless Inference 主机发送
Bearer key。/v1/models 会以 401 拒绝未认证请求,因此成功列出模型即视为密钥验证通过。发现会按 Crusoe
返回的原样保留 zai-org/GLM-5.3、moonshotai/Kimi-K2.6 这类带斜杠的原生 id,上限为 256 KiB 和 256 条原始记录。只保留 is_public: true 且 architecture.modality 为 text 或 multimodal 的记录,因此账户私有部署以及 embedding、媒体类记录会被排除。
推理模型通过 Chat Completions 的 reasoning 字段返回思考内容,adapter 会读取该字段。只有
openai/gpt-oss-120b 接受 reasoning_effort 档位(low、medium、high),其他推理模型把该字段当作
开关,因此预设不声明 provider-wide effort 档位,也不声明 provider-wide parallel tool calls。速率限制按
project 和 model 生效(超限返回 429,共享部署扩容时返回 503),新账户可获得 $5 免费额度。密钥可在
Crusoe Cloud 控制台 的 Intelligence Foundry > Inference 中创建。
**DigitalOcean 发现:**该预设使用 model access key 访问固定的共享 Serverless Inference 主机,只公开
已鉴权 /v1/models 响应与 DigitalOcean 官方文档确认的 Chat Completions allowlist 的交集。未知、
Responses-only、embedding 和 media-generation 模型 id 会按 fail closed 原则排除。发现上限为 256 KiB
和 256 条原始记录;agent 专属及 dedicated 主机不在范围内。密钥可在
DigitalOcean Control Panel 创建。
**Scaleway 发现:**该预设只公开已鉴权模型列表与官方文档确认的 Serverless Chat Completions allowlist 的交集。未知、Responses-only、embedding、transcription 及其他 media-model id 会按 fail closed 原则排除; 发现上限为 128 KiB 和 128 条原始记录。它使用默认 Project 的共享 endpoint;带 Project ID 的 URL 和 dedicated deployment 需要配置为 custom provider。API 密钥可在 Scaleway 控制台 创建。
**Featherless 发现:**该预设在固定的 OpenAI 兼容主机上鉴权,只请求按 chat 和当前 plan 过滤后的热门
模型第一页,最多 100 条。registry 随后按 fail closed 原则要求每条记录分别报告当前 plan 可用、无需
Hugging Face gate,且 features.tool_use: true。发现上限为 128 KiB 和 100 条原始记录,因此不会下载或
缓存包含数万模型的完整目录。由于 /v1/models 在文档中可带或不带鉴权调用,它无法证明输入的密钥有效;chat 请求仍会使用已配置的 Bearer 密钥认证。个人 plan 仅适用于 interactive/prototype 用途;任意 application 需要使用
Scale plan。密钥可在 Featherless dashboard 创建。
**Novita 发现:**密钥预设使用 openai-chat adapter,并只向 Novita 的固定 OpenAI 兼容主机发送
Bearer key。公开模型列表只保留同时报告 model_type: chat 和 chat/completions endpoint 的记录,
发现上限为 512 KiB 和 256 条原始记录。由于 catalog 是公开的,login 会报告密钥无法验证,而不会把
成功列出模型当作密钥有效的证明。模型能力各不相同,因此预设不会声明 provider-wide parallel tool calls
或 OpenAI reasoning_effort。密钥可在
Novita key manager 创建。
**Baseten 范围:**该预设仅覆盖 Baseten 的共享 Model APIs。 本地使用可选择个人 API 密钥;共享或生产用途请使用具备 Call Model APIs 权限的团队密钥。 专用 Truss
predict端点使用不同的主机和请求 schema,不由此预设路由。 该预设的实时发现上限为 1 MiB 响应和 256 条原始模型记录。
A6API 信用额度
Section titled “A6API 信用额度”使用 openai-chat、authMode: "key" 以及规范地址 https://api.a6api.com 或
https://api.a6api.com/v1 的自定义提供商,会在仪表板和 ocx account refresh <provider>
中显示 A6API 信用使用情况;提供商名称可以自定义。系统依据账户的 hard credit limit 将令牌单位换算为 USD,并显示已用百分比和剩余额度。
令牌到期不代表额度补充,因此不会显示为配额重置。只有当前活动密钥会发送到规范主机,重定向会被拒绝;负数
或内部不一致的计费总数不会生成报告。
**腾讯云 Coding Plan 使用限制:**腾讯将此订阅限定为交互式编程工具使用。禁止通用 API 自动化、自定义应用后端和非交互式批量调用;违规使用可能导致套餐密钥被停用。
GLM 计费线路:
zai是 Z.AI 的国际 coding plan 订阅,zhipu-bigmodel是智谱国内 BigModel 的按量付费端点。二者主机、密钥与计费均不同,为其中一方签发的密钥无法在另一方通过鉴权。
多个 API 密钥
Section titled “多个 API 密钥”基于密钥的提供商也可以保存多个 key。通过 Providers 页面添加密钥时,它会存入
provider.apiKeyPool、被设为 active,并同步到 provider.apiKey,这样路由和 adapter 仍读取原来的
字段。同一个下拉列表可以切换或移除密钥;管理 API 是 /api/providers/keys,并且只返回脱敏后的密钥。
从终端切换账号
Section titled “从终端切换账号”无需打开仪表盘,即可使用 ocx account list、ocx account current 和 ocx account use 查看或
切换同一组 Codex、OAuth 和 API-key pool。完整命令、JSON 输出和新 session 生效规则请参阅
CLI 参考。
GPT-5.6 预览路径
Section titled “GPT-5.6 预览路径”GPT-5.6 Sol/Terra/Luna 会预置在提供商的回退列表中,因此即使实时模型目录暂时滞后,ocx sync
也能继续显示这些模型。
| Codex 路由 | 预置模型 id | Codex 中显示的上下文 |
|---|---|---|
| Codex 登录(Pool 或 Direct) | gpt-5.6-* |
922,000 |
| OpenAI (API key) | openai-apikey/gpt-5.6-* 和 *-pro |
922,000(max input 922,000) |
| OpenRouter | openrouter/openai/gpt-5.6-sol、openrouter/openai/gpt-5.6-terra、openrouter/openai/gpt-5.6-luna |
922,000 |
| Cursor | cursor/gpt-5.6-sol、cursor/gpt-5.6-terra、cursor/gpt-5.6-luna |
1,000,000 |
原生 GPT-5.6 条目保留固定的上游 reasoning 档位,例如 Luna 有 max,但没有 ultra。路由条目
则使用各提供商的元数据和 reasoning 映射。四条路径最终都受上游账号权限限制;Cursor 还会根据实时
发现结果,仅保留当前账号可用的模型。
Ollama Cloud
Section titled “Ollama Cloud”Ollama Cloud 是托管(而非本地)的 Ollama,配置地址为 https://ollama.com/v1,密钥来自 ollama.com/settings/keys。opencodex 通过 Ollama 自身的 REST API(POST /api/chat)连接,而不是 OpenAI 兼容接口,并从提供方动态发现模型列表,因此新的 Ollama Cloud 模型无需改动配置即可出现。opencodex 按视觉能力对其云端阵容进行分类,使 vision sidecar 仅对纯文本模型生效。纯文本模型(例如 glm-5.2、deepseek-v4-flash、gpt-oss、qwen3-coder、minimax-m2.x、nemotron-3-*)列在 noVisionModels 中;原生支持视觉的模型(例如 kimi-k2.6、minimax-m3、gemma4、qwen3.5、gemini-3-flash-preview)则不在其中。匹配能容忍 Ollama 的 :size 标签,因此 gpt-oss 涵盖 gpt-oss:120b 和 gpt-oss:20b。
Ollama 目前在文档中说明结构化输出在 Ollama Cloud 上不受支持。因此对正典 ollama-cloud,
opencodex 会以明确的错误拒绝结构化输出请求(text.format),而不是悄悄返回不受约束的自由
文本;本地 / 自定义 ollama-native 端点保留 Ollama 原生的 format 行为。
4. 本地提供商
Section titled “4. 本地提供商”让 opencodex 指向本地的 OpenAI 兼容服务器——通常使用空密钥:
| 提供商 | 基础 URL |
|---|---|
| Ollama (local) | http://localhost:11434/v1 |
| vLLM | http://localhost:8000/v1 |
| LM Studio | http://localhost:1234/v1 |
任意 OpenAI 兼容端点
Section titled “任意 OpenAI 兼容端点”如果某个提供商使用 Chat Completions,openai-chat adapter 即可处理它——在仪表盘中选择 Custom,或在 ocx init 中选择 custom 并输入基础 URL。每个提供商字段(headers、noReasoningModels、noVisionModels、models……)请参见 配置参考。

