Back to Details

codex-cli-model-bridge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex CLI Model Bridge

Codex CLI 模型桥接工具

Manage subscription-backed or local proxy models in Codex without treating Codex like WorkBuddy. Codex uses a Responses API Provider plus a model catalog; WorkBuddy uses independent JSON entries. Share CLIProxyAPI infrastructure and verified Provider facts, but keep each application's writer and state separate.
Codex selects one 
model_provider
for a task. Model catalog entries do not carry per-model Provider routing. Preserve the Provider identity that owns the majority of indexed task history (normally 
openai
). For normal Desktop use, the supported bridge design keeps 
model_provider = "openai"
, keeps ChatGPT subscription auth intact, and points the built-in Provider's 
openai_base_url
at an owner-only loopback header-rewriting proxy. CLIProxyAPI then routes native GPT subscription models and verified third-party models behind one catalog without changing the task Provider identity. Keep the isolated 
$CODEX_HOME/cli-proxy.config.toml
profile as the default path on Windows and as a fallback everywhere else.
This is transparent single-Provider routing, not per-model Provider routing. Never set the Desktop default to 
cli_proxy
or vendor 
ZAI
when most history belongs to 
openai
.
When the user wants GLM-5.3 from a Coding Plan key, read glm-coding-plan.md. If Desktop already uses Codex Router on port 4202, add 
zai-coding
there and keep the OpenAI Provider identity. Do not run 
npx @z_ai/coding-helper
.
On Windows, start with the isolated profile. Read windows.md. Do not require Homebrew, LaunchAgents, or Codex Router.
无需将Codex当作WorkBuddy使用，即可在Codex中管理订阅支持的模型或本地代理模型。Codex采用Responses API Provider加模型目录的架构；WorkBuddy则使用独立的JSON条目。两者共享CLIProxyAPI基础设施和已验证的Provider信息，但各自的应用写入器和状态相互独立。
Codex会为任务选择一个
model_provider
。模型目录条目不携带逐模型的Provider路由信息。保留拥有大部分索引任务历史的Provider身份（通常为
openai
）。对于常规桌面使用，受支持的桥接设计保持
model_provider = "openai"
，维持ChatGPT订阅认证有效，并将内置Provider的
openai_base_url
指向仅所有者可见的环回重写头代理。CLIProxyAPI随后在不更改任务Provider身份的情况下，通过单个目录路由原生GPT订阅模型和已验证的第三方模型。将隔离的
$CODEX_HOME/cli-proxy.config.toml
配置文件作为Windows系统的默认路径，同时作为其他系统的备用路径。
这是透明的单Provider路由，而非逐模型的Provider路由。当大部分历史属于
openai
时，切勿将桌面默认Provider设置为
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。

Resolve the Skill directory

解析Skill目录

Resolve this loaded Skill's directory as 
<skill-dir>
. Resolve 
<python>
as the first available of 
python3
, 
py -3
, and 
python
. Use the deterministic entry point:
bash
<python> <skill-dir>/scripts/bridge.py
Examples below use 
python3
. Substitute 
<python>
when that command is missing.
将已加载的Skill目录解析为
<skill-dir>
。将
<python>
解析为
python3
、
py -3
和
python
中的第一个可用版本。使用确定的入口点：
bash
<python> <skill-dir>/scripts/bridge.py
以下示例使用
python3
。当该命令不可用时，请替换为
<python>
。

Default workflow

默认工作流程

1. Audit before mutation

1. 变更前审计

bash
python3 <skill-dir>/scripts/bridge.py audit
The audit must redact secrets and verify:
  • Codex CLI version, 
    ~/.codex/config.toml
    , file permissions, and TOML validity
  • default 
    model_provider
    , indexed task counts by Provider, SQLite integrity, and the dominant history Provider
  • active bridge mode: Desktop-transparent or isolated-profile
  • Desktop-transparent 
    openai_base_url
    , ChatGPT auth continuity, loopback health, or the isolated profile's command-backed authentication
  • loopback-only CLIProxyAPI reachability and live 
    /v1/models
  • the active catalog's validity, visible model IDs, and bridge ownership state
  • stale catalog entries, missing live routes for managed models, listed native models, or the current default model, and models present in the proxy but absent from Codex
Codex officially supports only the Responses wire API for custom Providers. Do not register a Chat Completions-only route and call it Codex-compatible.
If the default Provider differs from the dominant indexed-history Provider, treat history restoration as the first repair. Do not edit task rows to make the current Provider fit.
bash
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 wire API作为自定义Provider。请勿注册仅支持Chat Completions的路由并声称其与Codex兼容。
如果默认Provider与主导索引历史Provider不同，请先恢复历史记录再进行修复。请勿编辑任务行以适配当前Provider。

2. Restore the desktop default and history

2. 恢复桌面默认配置及历史记录

Preview:
bash
python3 <skill-dir>/scripts/bridge.py restore-default
The preview reports one finding ID, the current config SHA-256, the exact single-file diff, and the before-state thread inventory. Apply only after the repair is authorized and the SHA is still current:
bash
python3 <skill-dir>/scripts/bridge.py restore-default \
  --expected-sha256 <approved-sha256> \
  --apply
The default target is the Provider with the largest indexed task count. The command refuses a minority Provider unless 
--allow-minority-provider
is explicit, restores a native model, removes the custom root catalog override, preserves unrelated TOML, creates a 
0600
backup, and proves the task inventory digest did not change.
预览：
bash
python3 <skill-dir>/scripts/bridge.py restore-default
预览报告会显示一个发现ID、当前配置的SHA-256值、精确的单文件差异以及变更前的线程清单。仅在修复获得授权且SHA值仍为当前值时应用：
bash
python3 <skill-dir>/scripts/bridge.py restore-default \
  --expected-sha256 <approved-sha256> \
  --apply
默认目标是拥有最多索引任务数量的Provider。除非明确指定
--allow-minority-provider
，否则命令会拒绝选择少数派Provider；该命令会恢复原生模型、移除自定义根目录覆盖、保留无关的TOML配置、创建权限为
0600
的备份，并证明任务清单摘要未发生变化。

3. Configure or repair the isolated CLIProxyAPI profile

3. 配置或修复隔离的CLIProxyAPI配置文件

This is the default path on Windows. Preview and apply:
bash
python3 <skill-dir>/scripts/bridge.py configure
python3 <skill-dir>/scripts/bridge.py configure --apply
The command does not rewrite 
~/.codex/config.toml
. It preserves unrelated profile sections, creates timestamped 
0600
backups, installs an owner-only credential helper that reads the existing CLIProxyAPI client key without copying it, and configures 
~/.codex/cli-proxy.config.toml
with:
  • model_provider = "cli_proxy"
  • model_catalog_json = "~/.codex/model-catalog-cli-proxy.json"
  • [model_providers.cli_proxy]
    with a loopback URL and 
    wire_api = "responses"
  • [model_providers.cli_proxy.auth]
    using the local helper command
The helper is Python by default so Windows does not need Ruby. An existing 
.rb
helper is left in place. Do not set or change the user's default model unless they explicitly ask. Do not overwrite built-in Provider IDs. After this profile exists, use 
codex --profile cli-proxy
.
这是Windows系统的默认路径。预览并应用：
bash
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"
  • 包含环回URL和
    wire_api = "responses"
    的
    [model_providers.cli_proxy]
    配置段
  • 使用本地助手命令的
    [model_providers.cli_proxy.auth]
    配置段
默认使用Python编写助手，因此Windows系统无需Ruby。已存在的
.rb
助手会保留原样。除非用户明确要求，否则请勿设置或更改用户的默认模型。请勿覆盖内置Provider ID。该配置文件创建后，使用
codex --profile cli-proxy
命令调用。

4. Synchronize the profile model catalog

4. 同步配置文件模型目录

Preview bundled models:
bash
python3 <skill-dir>/scripts/bridge.py sync
Apply after live route verification:
bash
python3 <skill-dir>/scripts/bridge.py sync --apply
The sync command starts with Codex's native model cache only to inherit required runtime metadata, overlays verified model manifests from 
<skill-dir>/models/
, preserves unmanaged/manual profile entries, refuses to overwrite an unowned collision unless 
--adopt
is explicit, backs up the target, writes atomically, and records managed IDs under 
~/.config/codex-cli-model-bridge/state.json
.
The picker policy lives at 
<skill-dir>/policies/catalog.json
. IDs in 
hidden_native_model_ids
remain in the catalog with Codex's native 
visibility = "hide"
semantics, so existing tasks and routes keep working while those entries disappear from the model picker. Always change this canonical policy instead of hand-editing the generated catalog; every later sync reapplies it after a Codex update refreshes 
models_cache.json
.
IDs in 
protected_native_model_ids
must also remain under their exact native slugs. Codex App 
create_thread
validates those IDs independently of cosmetic catalog aliases, so a managed manifest must never 
supersede
them. Represent Fast through the service tier; do not replace 
gpt-5.6-sol
with a 
*-standard
picker alias. If WorkBuddy needs extra Fast/standard aliases, CLIProxyAPI 
oauth-model-alias
must set 
fork: true
so the native slug stays in live 
/v1/models
. Audit fails when a listed catalog model or the current default model is missing from that live list.
Native entries copied into the bridge catalog are metadata only. In isolated-profile mode they route through 
cli_proxy
; in Desktop-transparent mode they route through the built-in 
openai
Provider identity and its loopback 
openai_base_url
. The catalog itself never chooses the Provider.
Use 
--models <comma-separated-ids>
to select a subset. Use 
--catalog-policy <path>
only for an explicit alternate policy or an isolated test. Use 
--prune-managed
only when the user explicitly asked to remove stale bridge-managed models. Never prune native or manual entries; hide native picker entries through the policy.
When onboarding a new model, read model-manifests.md. A manifest is metadata, not proof. Its route must appear in live 
/v1/models
, and a real 
codex exec
probe must pass before success is reported.
预览捆绑模型：
bash
python3 <skill-dir>/scripts/bridge.py sync
在验证实时路由后应用：
bash
python3 <skill-dir>/scripts/bridge.py sync --apply
同步命令仅从Codex的原生模型缓存开始，继承所需的运行时元数据，叠加来自
<skill-dir>/models/
的已验证模型清单，保留非托管/手动配置的条目；除非明确指定
--adopt
，否则拒绝覆盖未拥有的冲突条目；备份目标文件、原子写入，并在
~/.config/codex-cli-model-bridge/state.json
中记录托管ID。
选择器策略位于
<skill-dir>/policies/catalog.json
。
hidden_native_model_ids
中的ID会保留在目录中，并使用Codex原生的
visibility = "hide"
语义，因此现有任务和路由可继续工作，同时这些条目会从模型选择器中消失。始终修改此标准策略，而非手动编辑生成的目录；每次Codex更新刷新
models_cache.json
后，后续的同步操作都会重新应用该策略。
protected_native_model_ids
中的ID必须保持其精确的原生slug。Codex应用的
create_thread
接口会独立于目录别名验证这些ID，因此托管清单绝不能
supersede
它们。通过服务层级表示Fast模式；请勿将
gpt-5.6-sol
替换为
*-standard
选择器别名。如果WorkBuddy需要额外的Fast/标准别名，CLIProxyAPI的
oauth-model-alias
必须设置
fork: true
，以便原生slug保留在实时
/v1/models
接口中。当列出的目录模型或当前默认模型未出现在该实时列表中时，审计会失败。
复制到桥接目录中的原生条目仅包含元数据。在隔离配置文件模式下，它们通过
cli_proxy
路由；在桌面透明模式下，它们通过内置的
openai
Provider身份及其环回
openai_base_url
路由。目录本身从不选择Provider。
使用
--models <逗号分隔的ID>
选择子集。仅在使用明确的替代策略或隔离测试时，才使用
--catalog-policy <路径>
。仅当用户明确要求移除过期的桥接托管模型时，才使用
--prune-managed
。切勿修剪原生或手动条目；通过策略隐藏原生选择器条目。
引入新模型时，请阅读model-manifests.md。清单仅为元数据，而非有效性证明。其路由必须出现在实时
/v1/models
接口中，且必须通过真实的
codex exec
探测后，才能报告成功。

5. Enable transparent Desktop coexistence

5. 启用透明桌面共存模式

Skip this on Windows unless the user explicitly wants the normal Desktop picker and will keep a Node process running. Isolated profile is enough.
First preview the exact root config diff and history guard:
bash
python3 <skill-dir>/scripts/bridge.py configure-desktop
After the finding-level diff is authorized, apply with the reported SHA-256:
bash
python3 <skill-dir>/scripts/bridge.py configure-desktop \
  --expected-sha256 <approved-sha256> \
  --apply
The command refuses to proceed unless 
openai
owns the majority of indexed history, 
auth.json
still contains healthy ChatGPT tokens, both endpoints are loopback-only, and the selected default model exists in the catalog. It installs:
  • ~/.config/codex-cli-model-bridge/transparent_proxy.mjs
    , owner-executable
  • on macOS, 
    ~/Library/LaunchAgents/com.zhijian.codex-cli-model-bridge-transparent-proxy.plist
  • on Windows and Linux, a detached 
    node
    process instead of a LaunchAgent
  • a listener on 
    127.0.0.1:8318
    that rewrites only the downstream Authorization header before forwarding to authenticated CLIProxyAPI on 
    127.0.0.1:8317
It then keeps 
model_provider = "openai"
, sets 
openai_base_url = "http://127.0.0.1:8318/v1"
, activates the verified catalog, preserves ChatGPT login and unrelated TOML, creates a 
0600
backup, and proves the task inventory digest did not change. Do not run a second CLIProxyAPI instance against the same OAuth directory; concurrent token refresh can invalidate credentials.
Windows系统上请跳过此步骤，除非用户明确希望使用常规桌面选择器且愿意保持Node进程运行。隔离配置文件已足够。
首先预览精确的根配置差异和历史记录保护：
bash
python3 <skill-dir>/scripts/bridge.py configure-desktop
在发现级差异获得授权后，使用报告的SHA-256值应用：
bash
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
    上的监听器，仅重写下游Authorization头，然后转发到运行在
    127.0.0.1:8317
    上的已认证CLIProxyAPI
随后保持
model_provider = "openai"
，设置
openai_base_url = "http://127.0.0.1:8318/v1"
，激活已验证的目录，保留ChatGPT登录状态和无关的TOML配置，创建权限为
0600
的备份，并证明任务清单摘要未发生变化。请勿针对同一OAuth目录运行第二个CLIProxyAPI实例；并发令牌刷新可能会使凭据失效。

6. Handle Fast mode correctly

6. 正确处理Fast模式

Codex Fast mode is a service tier on a model, not normally a second model entry. For a model whose catalog advertises the Fast tier, use:
toml
service_tier = "fast"
or launch a one-off run with:
bash
codex -c 'service_tier="fast"'
Codex maps 
fast
to the priority request value. Do not create 
*-fast
as a cosmetic catalog alias. A separate route is acceptable only when the upstream truly requires it and a live Responses probe verifies the distinct routing semantics.
Codex Fast模式是模型的服务层级，通常不是第二个模型条目。对于目录中声明支持Fast层级的模型，请使用：
toml
service_tier = "fast"
或通过以下命令启动一次性运行：
bash
codex -c 'service_tier="fast"'
Codex会将
fast
映射为优先级请求值。请勿创建
*-fast
作为目录别名。仅当上游确实需要且实时Responses探测验证了独特的路由语义时，才允许使用单独的路由。

7. Probe through Codex itself

7. 通过Codex自身进行探测

After catalog sync, probe affected models:
bash
python3 <skill-dir>/scripts/bridge.py probe --models grok-4.6,deepseek-v4-pro
The probe runs 
codex exec --profile cli-proxy
in ephemeral, read-only mode for each model and verifies a successful final response. Use 
--fast
only for a model that advertises Fast. Keep prompts non-sensitive and do not persist sessions.
For the normal Desktop-transparent path, probe without switching Provider identity:
bash
python3 <skill-dir>/scripts/bridge.py probe \
  --desktop \
  --models grok-4.6,deepseek-v4-pro,deepseek-v4-flash,gpt-5.6-sol
With 
--desktop
, the probe reads the active root 
model_catalog_json
from 
~/.codex/config.toml
; use 
--catalog
only as an explicit override.
Direct HTTP probes can diagnose the proxy, but they do not prove that Codex consumed the Provider and model catalog. Completion requires the Codex-level probe.
When a model can chat but Codex reports an empty or incompatible Shell payload, require an actual read-only command event:
bash
python3 <skill-dir>/scripts/bridge.py probe \
  --desktop \
  --shell \
  --models grok-4.6
This passes only when Codex records a successful 
pwd
command execution; a model that merely prints or simulates a path does not pass. If the failing custom model inherited 
tool_mode = "code_mode_only"
from an OpenAI template, set 
"tool_mode": null
in that model manifest and resync. Do not remove code mode from native OpenAI models globally.
目录同步完成后，探测受影响的模型：
bash
python3 <skill-dir>/scripts/bridge.py probe --models grok-4.6,deepseek-v4-pro
探测会以临时只读模式为每个模型运行
codex exec --profile cli-proxy
，并验证最终响应是否成功。仅对声明支持Fast的模型使用
--fast
参数。提示信息需非敏感且不保留会话。
对于常规桌面透明路径，无需切换Provider身份即可进行探测：
bash
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负载时，需要执行实际的只读命令事件：
bash
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模型的代码模式。

7.1 Repair Codex Multi-Agent input for third-party models

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

Codex Multi-Agent v2 uses a private Responses input item named 
agent_message
. Native OpenAI/Codex routes accept it, while xAI and other third-party Responses endpoints may reject it with HTTP 422 and 
ModelInput
. CLIProxyAPI 7.2.125+ contains the compatibility transform; do not duplicate this protocol rewrite in the transparent header proxy.
Preview and enable it in the canonical CLIProxyAPI config:
bash
python3 <skill-dir>/scripts/bridge.py configure-multi-agent
python3 <skill-dir>/scripts/bridge.py configure-multi-agent \
  --expected-sha256 <approved-sha256> \
  --apply
This changes only 
codex.optimize-multi-agent-v2
to 
true
, creates a 
0600
backup, restarts CLIProxyAPI when a macOS Homebrew service exists, and waits for the transparent route to recover. On Windows, tell the user to restart CLIProxyAPI locally if the live 
/v1/models
check does not recover. The transform is gated to official Codex user agents. For xAI, it converts 
agent_message
into a standard user 
message
, normalizes its encrypted content wrapper, and leaves normal OpenAI history/provider identity untouched.
Verify the exact failing shape, then run the normal Codex probe:
bash
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
For Grok agentic use, require CLIProxyAPI 
7.2.130
or newer plus both probes above. A plain text completion or one successful 
pwd
does not qualify the model for multi-tool or Subagent work. Older proxy versions may mishandle Responses tool identity, incremental tool state, or Codex multi-agent namespaces.
Codex Multi-Agent v2使用名为
agent_message
的私有Responses输入项。原生OpenAI/Codex路由接受该输入项，而xAI和其他第三方Responses端点可能会返回HTTP 422错误和
ModelInput
拒绝信息。CLIProxyAPI 7.2.125及以上版本包含兼容性转换；请勿在透明头代理中重复此协议重写。
预览并在标准CLIProxyAPI配置中启用：
bash
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
转换为标准用户
message
，规范化其加密内容包装器，并保持正常的OpenAI历史/Provider身份不变。
验证失败的具体格式，然后运行常规Codex探测：
bash
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的代理使用，需要CLIProxyAPI 7.2.130或更高版本，且上述两个探测均需通过。纯文本补全或单次成功的
pwd
操作不足以使模型具备多工具或子代理工作的资格。旧版本代理可能会错误处理Responses工具身份、增量工具状态或Codex多代理命名空间。

8. Verify consumption

8. 验证使用情况

Run 
audit
again and repeat 
sync
; the second sync must be idempotent. Normal Desktop tasks must remain on the dominant history Provider. In Desktop-transparent mode all selected models route through the loopback bridge while task identity remains 
openai
; do not describe this as independent per-model Provider selection. Use 
codex --profile cli-proxy
for Windows and for fallback diagnosis.
Report:
  • Codex and CLIProxyAPI versions and local endpoint
  • default Provider, task counts by Provider, and the verified unchanged task-inventory digest
  • profile Provider and catalog paths, with secrets omitted
  • models added, updated, removed, preserved, or conflicted
  • live route and 
    codex exec
    probe results
  • Fast semantics when requested
  • backup paths, reload action, and rollback command
再次运行
audit
并重复
sync
；第二次同步必须是幂等的。常规桌面任务必须保留在主导历史Provider下。在桌面透明模式下，所有选定模型通过环回桥接路由，同时任务身份仍为
openai
；请勿将此描述为独立的逐模型Provider选择。Windows系统和备用诊断请使用
codex --profile cli-proxy
。
报告内容包括：
  • Codex和CLIProxyAPI版本及本地端点
  • 默认Provider、按Provider统计的任务数量及已验证未更改的任务清单摘要
  • 配置文件Provider和目录路径（省略机密信息）
  • 添加、更新、移除、保留或冲突的模型
  • 实时路由和
    codex exec
    探测结果
  • 按需提供的Fast语义
  • 备份路径、重新加载操作及回滚命令

Repair workflow

修复工作流程

  1. Audit and distinguish history-scope mismatch, invalid TOML, proxy-down, helper/auth failure, missing route, invalid profile catalog, stale task, and Provider protocol mismatch.
  2. Restore the dominant history Provider before model work; do not rewrite task rows.
  3. Repair the smallest failing layer; do not reinstall a healthy proxy.
  4. Re-authorize upstream Providers with the WorkBuddy bridge only when CLIProxyAPI authentication is actually absent or rejected.
  5. Re-run profile catalog sync and the affected Codex-level probes.
  6. Verify normal desktop history remains visible under the default Provider.
For a Subagent failure whose HTTP 422 body mentions 
ModelInput
, inspect the failed task for an 
agent_message
input item. On CLIProxyAPI 7.2.125+, enable 
codex.optimize-multi-agent-v2
, then run 
probe-multi-agent
; do not flatten all requests indiscriminately in the transparent header proxy.
Read troubleshooting.md for failure classification and rollback.
  1. 审计并区分历史范围不匹配、无效TOML、代理宕机、助手/认证失败、路由缺失、配置文件目录无效、任务过期及Provider协议不匹配等问题。
  2. 在处理模型前恢复主导历史Provider；请勿重写任务行。
  3. 修复最小的故障层；请勿重新安装健康的代理。
  4. 仅当CLIProxyAPI认证确实缺失或被拒绝时，才通过WorkBuddy桥接重新授权上游Provider。
  5. 重新运行配置文件目录同步及受影响的Codex级探测。
  6. 验证常规桌面历史记录在默认Provider下仍可见。
对于HTTP 422响应体提及
ModelInput
的子代理故障，请检查失败任务是否包含
agent_message
输入项。在CLIProxyAPI 7.2.125及以上版本中，启用
codex.optimize-multi-agent-v2
，然后运行
probe-multi-agent
；请勿在透明头代理中随意扁平化所有请求。
请阅读troubleshooting.md了解故障分类及回滚方法。

Safety boundaries

安全边界

  • Keep CLIProxyAPI on explicit loopback and remote management disabled.
  • Do not restart CLIProxyAPI or the 8318 transparent proxy while the current Desktop session is using a third-party model such as Grok. A restart drops live routes for a few seconds and can abort this session with 
    unknown provider
    . Wait until after the Sol/Grok repair is verified, or tell the user first.
  • Preserve unrelated 
    config.toml
    sections, MCP servers, hooks, skills, permissions, and project trust settings.
  • Never print API keys, bearer headers, OAuth files, one-time codes, raw credential-helper output, or credential-bearing TOML blocks.
  • Keep 
    config.toml
    , catalog/state files, proxy config, helper, and backups owner-only when they can reveal private infrastructure. Unix mode 
    0600
    is the target; on Windows keep the files in the current user profile and do not share them.
  • Use command-backed auth or the owner-only transparent header rewriter; do not embed 
    experimental_bearer_token
    or duplicate the proxy client key.
  • Treat native 
    models_cache.json
    as upstream input, not a file this Skill owns.
  • Do not directly edit Codex SQLite state or the desktop app bundle to force a model into the picker.
  • Never switch the default Provider without first reading the indexed Provider distribution. Refuse a switch that would hide the majority of history unless the user explicitly accepts that result.
  • Do not advertise per-model Provider routing. Desktop coexistence works only because the built-in 
    openai
    Provider identity transparently routes every selected catalog model through the same loopback bridge.
  • Respect Provider subscription terms, quotas, and account ownership.
  • 保持CLIProxyAPI处于明确的环回模式，禁用远程管理。
  • 当前桌面会话正在使用Grok等第三方模型时，请勿重启CLIProxyAPI或8318透明代理。重启会导致实时路由中断数秒，可能会使会话因
    unknown provider
    错误而中止。请在Sol/Grok修复验证完成后再重启，或提前告知用户。
  • 保留无关的
    config.toml
    部分、MCP服务器、钩子、Skill、权限及项目信任设置。
  • 切勿打印API密钥、Bearer头、OAuth文件、一次性验证码、原始凭据助手输出或包含凭据的TOML块。
  • 当文件可能泄露私有基础设施时，将
    config.toml
    、目录/状态文件、代理配置、助手及备份设置为仅所有者可见。Unix系统目标权限为
    0600
    ；Windows系统请将文件保存在当前用户配置文件中，请勿共享。
  • 使用命令式认证或仅所有者可见的透明头重写器；请勿嵌入
    experimental_bearer_token
    或复制代理客户端密钥。
  • 将原生
    models_cache.json
    视为上游输入，而非本Skill拥有的文件。
  • 请勿直接编辑Codex SQLite状态或桌面应用包以强制模型显示在选择器中。
  • 在读取索引Provider分布前，切勿切换默认Provider。除非用户明确接受结果，否则拒绝会隐藏大部分历史记录的切换操作。
  • 请勿宣传逐模型Provider路由。桌面共存仅能工作，是因为内置的
    openai
    Provider身份将所有选定的目录模型通过同一环回桥接进行透明路由。
  • 遵守Provider订阅条款、配额及账户所有权规定。

Completion gate

完成标准

Completion requires:
  • default Codex TOML anchored to the dominant indexed-history Provider
  • unchanged, integrity-checked task inventory across the repair
  • valid isolated fallback profile or a healthy Desktop-transparent loopback bridge with ChatGPT auth preserved
  • valid active model catalog with no unapproved collision
  • requested native picker exclusions retained with 
    visibility = "hide"
  • every newly managed route visible from CLIProxyAPI
  • a successful ephemeral 
    codex exec
    probe for every affected model through the active mode
  • Fast represented and tested as a service tier when requested
  • a second sync with no changes
  • backups and rollback paths reported
If Codex cannot complete a Responses request through a route, report it as unverified and do not advertise it as usable merely because 
/v1/models
lists the name.
完成需满足以下条件：
  • 默认Codex TOML锚定到主导索引历史Provider
  • 修复过程中任务清单保持不变且完整性已验证
  • 存在有效的隔离备用配置文件，或健康的桌面透明环回桥接且ChatGPT认证已保留
  • 存在有效的活动模型目录，无未批准的冲突
  • 请求的原生选择器排除项通过
    visibility = "hide"
    保留
  • 每个新托管路由在CLIProxyAPI中可见
  • 每个受影响的模型通过活动模式完成成功的临时
    codex exec
    探测
  • 按需将Fast表示为服务层级并进行测试
  • 第二次同步无任何更改
  • 已报告备份路径及回滚命令
如果Codex无法通过路由完成Responses请求，请报告为未验证状态，切勿仅因
/v1/models
列出模型名称就宣传其可用。