codex-cli-model-bridge

Codex CLI 模型桥接

在 Codex 中管理由订阅支持的模型或本地代理模型，而不要把 Codex 当作 WorkBuddy。Codex 使用 Responses API Provider 和模型目录；WorkBuddy 使用独立的 JSON 条目。共享 CLIProxyAPI 基础设施和已验证的 Provider 信息，但让每个应用各自的写入器和状态保持独立。

Codex 会为一项任务选择一个 model_provider。模型目录条目不携带按模型划分的 Provider 路由。保留拥有大多数已索引任务历史记录的 Provider 身份（通常为 openai）。对于常规桌面应用使用，受支持的桥接设计会保持 model_provider = "openai"，保留 ChatGPT 订阅身份验证，并将内置 Provider 的 openai_base_url 指向一个仅限所有者访问、运行于本地回环地址的重写标头代理。随后，CLIProxyAPI 会在同一个目录下路由原生 GPT 订阅模型和已验证的第三方模型，同时不改变任务的 Provider 身份。将隔离的 $CODEX_HOME/cli-proxy.config.toml 配置文件作为 Windows 上的默认路径，以及其他平台上的备用路径。

这是透明的单 Provider 路由，不是按模型划分的 Provider 路由。如果大多数历史记录属于 openai，绝不要将桌面应用默认值设为 cli_proxy 或供应商 ZAI。

当用户想通过 Coding Plan 密钥使用 GLM-5.3 时，请阅读 glm-coding-plan.md。如果桌面应用已在 4202 端口使用 Codex Router，请在那里添加 zai-coding，并保留 OpenAI Provider 身份。不要运行 npx @z_ai/coding-helper。

在 Windows 上，从隔离配置文件开始。请阅读 windows.md。不要要求使用 Homebrew、LaunchAgents 或 Codex Router。

确定 Skill 目录

将此已加载 Skill 的目录解析为 <skill-dir>。将 <python> 解析为以下命令中第一个可用的命令：python3、py -3 和 python。使用确定性的入口点：

<python> <skill-dir>/scripts/bridge.py

以下示例使用 python3。如果该命令不可用，请替换为 <python>。

默认工作流

1. 修改前先审计

python3 <skill-dir>/scripts/bridge.py audit

审计必须脱敏秘密信息，并验证：

• Codex CLI 版本、~/.codex/config.toml、文件权限和 TOML 有效性
• 默认 model_provider、按 Provider 统计的已索引任务数量、SQLite 完整性，以及占主导地位的历史记录 Provider
• 当前桥接模式：桌面应用透明模式或隔离配置文件模式
• 桌面应用透明模式下的 openai_base_url、ChatGPT 身份验证连续性和本地回环健康状态，或隔离配置文件的命令支持身份验证
• 仅限本地回环的 CLIProxyAPI 可达性和实时 /v1/models
• 当前目录的有效性、可见模型 ID 和桥接所有权状态
• 过时的目录条目、托管模型缺失的实时路由、列出的原生模型或当前默认模型，以及代理中存在但 Codex 中缺失的模型

Codex 官方仅支持将 Responses 线路 API 用于自定义 Provider。不要注册仅支持 Chat Completions 的路由后就称其兼容 Codex。

如果默认 Provider 与占主导地位的已索引历史记录 Provider 不同，应优先将历史记录恢复作为首要修复。不要编辑任务行来迁就当前 Provider。

2. 恢复桌面应用默认设置和历史记录

预览：

python3 <skill-dir>/scripts/bridge.py restore-default

预览会报告一个问题 ID、当前配置的 SHA-256、精确的单文件差异，以及修改前的线程清单。仅在修复已获授权且 SHA 仍为当前值后应用：

python3 <skill-dir>/scripts/bridge.py restore-default \
  --expected-sha256 <approved-sha256> \
  --apply

默认目标是已索引任务数量最多的 Provider。除非显式指定 --allow-minority-provider，否则该命令会拒绝少数 Provider；它会恢复原生模型、移除自定义根目录覆盖、保留无关 TOML、创建权限为 0600 的备份，并证明任务清单摘要未发生变化。

3. 配置或修复隔离的 CLIProxyAPI 配置档

这是 Windows 上的默认路径。预览并应用：

python3 <skill-dir>/scripts/bridge.py configure
python3 <skill-dir>/scripts/bridge.py configure --apply

此命令不会重写 ~/.codex/config.toml。它会保留无关的配置档部分，创建带时间戳的 0600 备份，安装一个仅所有者可访问的凭据助手（读取现有的 CLIProxyAPI 客户端密钥，而不复制该密钥），并将 ~/.codex/cli-proxy.config.toml 配置为：

• model_provider = "cli_proxy"
• model_catalog_json = "~/.codex/model-catalog-cli-proxy.json"
• [model_providers.cli_proxy]，包含环回 URL 和 wire_api = "responses"
• [model_providers.cli_proxy.auth]，使用本地助手命令

默认情况下，助手使用 Python，因此 Windows 无需 Ruby。现有的 .rb 助手会保留。除非用户明确要求，否则不要设置或更改用户的默认模型。不要覆盖内置的 Provider ID。此配置档创建后，使用 codex --profile cli-proxy。

4. 同步配置档模型目录

预览内置模型：

python3 <skill-dir>/scripts/bridge.py sync

完成实时路由验证后应用：

python3 <skill-dir>/scripts/bridge.py sync --apply

同步命令首先使用 Codex 的原生模型缓存，仅用于继承必需的运行时元数据；然后叠加来自 <skill-dir>/models/ 的已验证模型清单，保留未托管的手动配置档条目，除非显式指定 --adopt，否则拒绝覆盖非本工具拥有的冲突项；它还会备份目标文件、以原子方式写入，并将受管理的 ID 记录在 ~/.config/codex-cli-model-bridge/state.json 中。

选择器策略位于 <skill-dir>/policies/catalog.json。hidden_native_model_ids 中的 ID 会保留在目录中，并沿用 Codex 原生的 visibility = "hide" 语义，因此现有任务和路由仍可正常工作，同时这些条目会从模型选择器中隐藏。始终修改此规范策略，而不要手动编辑生成的目录；每次 Codex 更新刷新 models_cache.json 后，后续同步都会重新应用该策略。

protected_native_model_ids 中的 ID 也必须保留其确切的原生 slug。Codex App 的 create_thread 会独立于外观上的目录别名验证这些 ID，因此受管理的清单绝不能 supersede 它们。通过服务层级表示 Fast；不要用 *-standard 选择器别名替换 gpt-5.6-sol。如果 WorkBuddy 需要额外的 Fast/standard 别名，CLIProxyAPI 的 oauth-model-alias 必须设置 fork: true，以便原生 slug 保留在实时 /v1/models 中。如果目录中列出的模型或当前默认模型不在该实时列表中，审计将失败。

复制到桥接目录中的原生条目仅包含元数据。在隔离配置档模式下，它们通过 cli_proxy 路由；在 Desktop 透明模式下，它们通过内置的 openai Provider 身份及其环回 openai_base_url 路由。目录本身不会选择 Provider。

使用 --models <comma-separated-ids> 选择子集。仅在明确指定备用策略或进行隔离测试时，才使用 --catalog-policy <path>。只有在用户明确要求移除过时的桥接托管模型时，才使用 --prune-managed。绝不要清除原生条目或手动配置的条目；应通过策略隐藏原生选择器条目。

添加新模型时，请阅读模型清单。清单仅包含元数据，并非证明。其路由必须出现在实时 /v1/models 中，并且真实的 codex exec 探测必须通过，才能报告成功。

5. 启用透明的 Desktop 共存

除非 Windows 用户明确希望使用常规 Desktop 选择器并愿意保持 Node 进程运行，否则请跳过此步骤。隔离配置文件已足够。

先预览精确的根配置差异和历史记录保护检查：

python3 <skill-dir>/scripts/bridge.py configure-desktop

授权发现级差异后，使用报告的 SHA-256 应用更改：

python3 <skill-dir>/scripts/bridge.py configure-desktop \
  --expected-sha256 <approved-sha256> \
  --apply

只有在 openai 拥有大部分已索引历史记录、auth.json 仍包含有效的 ChatGPT 令牌、两个端点都仅限环回地址，且所选默认模型存在于目录中时，该命令才会继续。它会安装：

• ~/.config/codex-cli-model-bridge/transparent_proxy.mjs，设置为所有者可执行
• 在 macOS 上，~/Library/LaunchAgents/com.zhijian.codex-cli-model-bridge-transparent-proxy.plist
• 在 Windows 和 Linux 上，启动一个分离的 node 进程，而不是 LaunchAgent
• 监听 127.0.0.1:8318，在转发到经过身份验证、位于 127.0.0.1:8317 的 CLIProxyAPI 之前，仅改写下游 Authorization 标头

随后，它会保留 model_provider = "openai"，设置 openai_base_url = "http://127.0.0.1:8318/v1"，激活已验证的目录，保留 ChatGPT 登录状态和无关的 TOML，创建权限为 0600 的备份，并证明任务清单摘要未发生变化。不要针对同一个 OAuth 目录运行第二个 CLIProxyAPI 实例；并发刷新令牌可能会使凭据失效。

6. 正确处理 Fast 模式

Codex Fast 模式是模型上的服务层级，通常不是第二个模型条目。对于目录中标注支持 Fast 层级的模型，请使用：

service_tier = "fast"

或者通过以下命令启动一次性运行：

codex -c 'service_tier="fast"'

Codex 会将 fast 映射为优先级请求值。不要将 *-fast 创建为仅供展示的目录别名。只有在上游确实要求单独路由，且实时 Responses 探测验证了不同的路由语义时，才可以使用单独的路由。

7. 通过 Codex 自身进行探测

同步目录后，探测受影响的模型：

python3 <skill-dir>/scripts/bridge.py probe --models grok-4.6,deepseek-v4-pro

对于每个模型，探测会在临时只读模式下运行 codex exec --profile cli-proxy，并验证最终响应是否成功。仅对标注支持 Fast 的模型使用 --fast。提示词应避免包含敏感信息，也不要持久化会话。

对于常规的 Desktop 透明路径，在不切换 Provider 身份的情况下进行探测：

python3 <skill-dir>/scripts/bridge.py probe \
  --desktop \
  --models grok-4.6,deepseek-v4-pro,deepseek-v4-flash,gpt-5.6-sol

使用 --desktop 时，探测会从 ~/.codex/config.toml 读取当前活动的根 model_catalog_json；仅在明确要覆盖时才使用 --catalog。

直接进行 HTTP 探测可以帮助诊断代理，但无法证明 Codex 使用了 Provider 和模型目录。必须通过 Codex 级别的探测才能完成验证。

当模型能够聊天，但 Codex 报告 Shell 载荷为空或不兼容时，要求实际发生只读命令事件：

python3 <skill-dir>/scripts/bridge.py probe \
  --desktop \
  --shell \
  --models grok-4.6

只有 Codex 记录到成功执行 pwd 命令时，此项检查才会通过；仅打印或模拟路径的模型不能通过。如果出现故障的自定义模型继承了 OpenAI 模板中的 tool_mode = "code_mode_only"，请在该模型清单中设置 "tool_mode": null 并重新同步。不要全局移除原生 OpenAI 模型的 code mode。

7.1 修复 Codex Multi-Agent 对第三方模型的输入

Codex Multi-Agent v2 使用名为 agent_message 的私有 Responses 输入项。原生 OpenAI/Codex 路由接受该输入项，而 xAI 和其他第三方 Responses 端点可能会以 HTTP 422 和 ModelInput 拒绝请求。CLIProxyAPI 7.2.125+ 已包含兼容性转换；不要在透明头部代理中重复此协议改写。

在规范的 CLIProxyAPI 配置中预览并启用该功能：

python3 <skill-dir>/scripts/bridge.py configure-multi-agent
python3 <skill-dir>/scripts/bridge.py configure-multi-agent \
  --expected-sha256 <approved-sha256> \
  --apply

此操作仅将 codex.optimize-multi-agent-v2 改为 true，创建权限为 0600 的备份，在存在 macOS Homebrew 服务时重启 CLIProxyAPI，并等待透明路由恢复。在 Windows 上，如果实时 /v1/models 检查未恢复，请告知用户在本地重启 CLIProxyAPI。该转换仅对官方 Codex 用户代理生效。对于 xAI，它会将 agent_message 转换为标准的 user message，规范化其加密内容封装，并保持正常的 OpenAI 历史记录和提供方身份不变。

验证确切的失败输入形态，然后运行常规 Codex 探测：

python3 <skill-dir>/scripts/bridge.py probe-multi-agent --models grok-4.6
python3 <skill-dir>/scripts/bridge.py probe --desktop --tool-sequence --models grok-4.6

要将 Grok 用于 Agentic 工作，需要 CLIProxyAPI 7.2.130 或更高版本，并且上述两项探测都通过。纯文本补全或一次成功的 pwd 不足以证明该模型适用于多工具或 Subagent 工作。较旧的代理版本可能无法正确处理 Responses 工具身份、增量工具状态或 Codex 多 Agent 命名空间。

8. 验证使用情况

再次运行 audit 并重复执行 sync；第二次同步必须是幂等的。常规桌面任务必须继续使用占主导地位的历史记录提供方。在桌面透明模式下，所有选定的模型都通过环回桥接路由，同时任务身份仍为 openai；不要将此描述为按模型独立选择提供方。Windows 用户和进行回退诊断时，请使用 codex --profile cli-proxy。

报告以下信息：

• Codex 和 CLIProxyAPI 版本及本地端点
• 默认提供方、按提供方统计的任务数量，以及已验证未变化的任务清单摘要
• 配置文件提供方和目录路径，省略机密信息
• 已添加、更新、移除、保留或冲突的模型
• 实时路由和 codex exec 探测结果
• 用户请求时的 Fast 语义
• 备份路径、重载操作和回滚命令

修复工作流

1. 审计并区分历史记录范围不匹配、TOML 无效、代理未运行、助手/身份验证失败、路由缺失、配置文件目录无效、任务过时和提供方协议不匹配。
2. 处理模型之前，先恢复占主导地位的历史记录提供方；不要改写任务行。
3. 修复出现故障的最小层；不要重新安装运行正常的代理。
4. 仅当 CLIProxyAPI 身份验证确实缺失或被拒绝时，才通过 WorkBuddy 桥接重新授权上游提供方。
5. 重新运行配置文件目录同步和受影响的 Codex 级探测。
6. 验证默认提供方下仍能看到正常的桌面历史记录。

如果 Subagent 故障的 HTTP 422 响应正文提到 ModelInput，请检查失败任务是否包含 agent_message 输入项。在 CLIProxyAPI 7.2.125+ 上，启用 codex.optimize-multi-agent-v2，然后运行 probe-multi-agent；不要在透明头部代理中不加区分地扁平化所有请求。

请阅读 troubleshooting.md，了解故障分类和回滚。

安全边界

• 将 CLIProxyAPI 保持为显式回环模式，并禁用远程管理。
• 当当前 Desktop 会话正在使用 Grok 等第三方模型时，不要重启 CLIProxyAPI 或 8318 透明代理。重启会导致实时路由中断几秒，并可能以 unknown provider 错误终止此会话。请等 Sol/Grok 修复经过验证后再重启，或事先告知用户。
• 保留无关的 config.toml 部分、MCP 服务、钩子、技能、权限和项目可信设置。
• 切勿打印 API 密钥、Bearer 请求头、OAuth 文件、一次性代码、原始凭据助手输出或包含凭据的 TOML 块。
• 如果 config.toml、目录/状态文件、代理配置、助手和备份可能泄露私有基础设施信息，请将其权限设为仅所有者可访问。Unix 系统的目标权限为 0600；在 Windows 上，请将文件保存在当前用户配置文件目录中，且不要分享。
• 使用由命令提供的身份验证，或仅所有者可访问的透明请求头重写器；不要嵌入 experimental_bearer_token 或重复代理客户端密钥。
• 将原生 models_cache.json 视为上游输入，而不是此 Skill 所有的文件。
• 不要直接编辑 Codex SQLite 状态或桌面应用程序包，以强行将模型加入选择器。
• 切换默认 Provider 前，务必先读取已编入索引的 Provider 分布。如果切换会隐藏大多数历史记录，则拒绝切换，除非用户明确接受此结果。
• 不要宣称支持按模型进行 Provider 路由。桌面端之所以能够共存，仅仅是因为内置 openai Provider 身份会将每个选定的目录模型透明地路由到同一个回环桥接服务。
• 遵守 Provider 订阅条款、配额和账户所有权要求。

完成门槛

完成须满足以下条件：

• 默认 Codex TOML 以已编入索引的历史记录中占主导地位的 Provider 为基准
• 修复前后任务清单保持不变，并通过完整性检查
• 存在有效的隔离回退配置，或健康的 Desktop 透明回环桥接服务，且保留 ChatGPT 身份验证
• 当前模型目录有效，且不存在未经批准的冲突
• 保留请求中要求的原生选择器排除项，并设置 visibility = "hide"
• CLIProxyAPI 中可见每条新管理的路由
• 对每个受影响的模型，通过当前模式执行一次成功的临时 codex exec 探测
• 如果用户有此要求，则将 Fast 作为服务层级纳入配置并进行测试
• 第二次同步无任何更改
• 报告备份和回滚途径

如果 Codex 无法通过某条路由完成 Responses 请求，请将其报告为未经验证；不要仅因为 /v1/models 列出了该名称，就宣称它可用。