Codex CLI · 接入

Codex CLI 用 OpenAI Responses 协议。前置准备见 接入前准备，本文只讲 Codex 专属配置。

Codex 接入地址 https://api.637274.xyz/v1（必须带 /v1）。

配置文件

如果文件不存在就手动创建。如果已经有 MCP、项目规则或其它配置，只合并下面这些字段，不要整文件覆盖。

config.toml：

model_provider = "astra"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
model_verbosity = "high"
disable_response_storage = true

[features]
web_search_request = true
responses_websockets_v2 = true

[model_providers.astra]
name = "Astra API"
base_url = "https://api.637274.xyz/v1"
wire_api = "responses"
supports_websockets = true

auth.json：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-xxx"
}

Codex 实际读取的是 auth.json，不是 auth.js。auth_mode 必须写 apikey，表示用上面的 API Key 走 OpenAI Responses API。不要写 chatgpt；chatgpt 是本机 ChatGPT 登录态，不适合 Astra API Key 接入。

model 可以换成控制台首页「可用模型与价格」里当前用户等级可调用的任意启用模型，例如：

测试

启动 Codex：

codex

检查模型列表：

curl https://api.637274.xyz/v1/models \
  -H "Authorization: Bearer sk-xxx"

WSS 模式

WSS 只给 Codex CLI 用。普通 OpenAI SDK、Cherry Studio、raw curl 调 /v1/responses 仍然走 HTTPS POST。

配置里保留 HTTPS base URL，并开启 WebSocket 支持：

[features]
responses_websockets_v2 = true

[model_providers.astra]
base_url = "https://api.637274.xyz/v1"
wire_api = "responses"
supports_websockets = true

不要把 base_url 改成 wss://。Codex 会从 HTTPS base URL 自动升级到 WSS。

手机遥控（Remote Control）

Codex 2026 年 5 月上线的 Remote Control：用 ChatGPT 手机 App 接管桌面 Codex 会话、审批命令、查看输出。手机端 iOS / Android 均支持，桌面端同上面 Windows / macOS / Linux。

与 apikey 模式互斥

Remote Control 要在 OpenAI 账号维度上做设备配对，而上面「配置文件」一节的 apikey 模式完全跳过了账号登录，两者只能二选一。下面这套配置实质是用 OpenAI 账号登录占位以满足配对要求，实际 API 调用通过 experimental_bearer_token 仍走 Astra。

属非官方组合。Codex 后续版本可能调整 experimental_* 字段或 requires_openai_auth 行为；升级后如失效请回退到上面的 apikey 标准模式。

启用步骤

1. 备份并删除 ~/.codex/auth.json 和 ~/.codex/config.toml（Windows 同理 %userprofile%\.codex）

2. 启动 codex，选 Sign in，用任意 OpenAI 账号登录（Free 普号即可），登录完成后退出 codex

3. 重写 config.toml，把 sk-xxx 替换为在 /settings 创建的完整 Astra Key：

   model_provider = "astra"
   
   [model_providers.astra]
   name = "Astra API"
   base_url = "https://api.637274.xyz/v1"
   wire_api = "responses"
   experimental_bearer_token = "sk-xxx"
   requires_openai_auth = true
   
   [features]
   collaboration_modes = true
   remote_connections = true
   remote_control = true
   goals = true
   

4. 重启 codex。此时界面是完整登录态——插件、模型速度切换、/goal 命令全部可用——但对话实际走 Astra。

账号安全

用第三方接码绑定的 OpenAI 普号请开启 MFA，避免账号被找回带走配对的设备。

手机配对

桌面代理开 TUN / 全局模式（分应用代理大概率失败），然后：

1. ChatGPT App → 左上角头像 → 更多 → Codex → 连接桌面 Codex
2. 弹出登录框时再次输入上面步骤 2 的 OpenAI 账号密码
3. 桌面端弹「允许此设备」→ 同意
4. 等待手机端显示「设置完成」（首次配对约 1–2 分钟，失败重试几次即可）

配对完成后手机端列表显示已授权设备，绿色 = 在线，红色 = 离线。配对只做一次，之后自动连接。

注意事项

• provider 名称别改：会话和 model_providers.<name> 绑定，改名会清空所有会话历史；切换中转站只改 base_url 和 experimental_bearer_token，保持 astra 不变
• 模型列表以桌面 config.toml 为准：手机端切换模型时看到的是 Astra 暴露的列表，不是 OpenAI 原生列表
• 插件、Fast 模式开关只在桌面端可见：手机端是遥控器不是控制台
• /goal 至死方休：Goal 任务会反复重试直到目标达成，手机端容易因为锁屏忘了它还在跑，Token 烧光是常见事故，建议配合预算上限并定期检查进度
• 设备丢失立即吊销：在 OpenAI 账号设置里撤销那台设备的授权

常见错误

通用错误（401/403/404/503/...）见 故障排查。下表只列 Codex 特有的：

网关行为（参考）

网关读请求里的 x-codex-installation-id / x-codex-turn-state / x-codex-window-id / Originator（TUI 发 codex-tui，部分版本/surface 发 codex_cli_rs）这几个 Codex CLI 自带 header 来判断是不是 Codex 客户端。命中时，针对 GPT 模型会自动走通道（ChatGPT 账号订阅入口）；普通 OpenAI SDK 调用 /v1/responses 或 /v1/chat/completions 不会走这条线，仍走标准 API key 通道。

WSS 模式要求 CDN/反代透传 WebSocket 升级。 Codex 开 responses_websockets_v2 后对 /v1/responses 发 GET + Upgrade: websocket。若域名前置的 CDN（如腾讯云 EdgeOne）未开启 WebSocket，会剥掉 Upgrade/Connection 头并按普通 GET（甚至加 Range）回源，握手必失败、Codex 报错；此时关掉 responses_websockets_v2 回退 HTTPS POST 可正常使用。

这件事配置上你不用关心，但能解释为什么同一 Key 在 Codex CLI 和 raw curl 下面对同一个 GPT 模型计费方式可能不同。