返回归档

Codex App 远程模式切换官方 Plan 与 API：SOP

发布于
计算中...

Codex App 远程模式切换官方 Plan 与 API：SOP

适用场景：笔记本上的 Codex App 通过 SSH 连接远端服务器，远端运行 Codex CLI / app-server。

规则先记住

  1. model_provider 没有配置（被注释或删除）时，使用官方 Plan。
  2. 配置 model_provider 后，使用对应的自定义 API provider。
  3. 两种模式都保留 requires_openai_auth = true。
  4. 切换认证后，必须让 Codex App 重新连接远端，并从原会话 fork 新会话。

远端配置文件

在远端服务器编辑：

~/.codex/config.toml

配置结构如下。真实 provider 名称和地址只写在远端，不要复制到博客、截图或 Git：

# 中转站模式：启用下面三项（删除行首的 #）
model_provider = "relay_provider"
model = "gpt-5.6-sol"
disable_response_storage = true

model_reasoning_effort = "high"
network_access = "enabled"

sandbox_mode = "workspace-write"
service_tier = "default"

[model_providers.relay_provider]
name = "OpenAI"
base_url = "https://api.example/v1"
wire_api = "responses"
requires_openai_auth = true

relay_provider 和 https://api.example/v1 仅为占位符，请替换为你自己的 provider ID 和地址。

A. 切换到官方 Plan

1. 修改配置

在当前中转站配置中，给以下三行加上行首 #：

# model_provider = "relay_provider"
# model = "gpt-5.6-sol"
# disable_response_storage = true

其中最关键的是 model_provider 被注释或删除；没有指定它时，Codex 自动使用官方上游。model 和 disable_response_storage 按这套远端配置一起注释。

2. 在远端 CLI 重新登录

以下命令必须在远端服务器执行：

codex logout
codex login

按提示完成官方账号登录。

3. 重连并 fork

  1. 在笔记本 Codex App 中断开远端连接。
  2. 重新连接同一远端。
  3. 对原会话执行 Fork，使用 fork 出来的新会话继续开发。

B. 切换到自定义 API

1. 修改配置

去掉中转站配置项前的 #，启用以下三行：

model_provider = "relay_provider"
model = "gpt-5.6-sol"
disable_response_storage = true

确认对应 provider 使用：

wire_api = "responses"
requires_openai_auth = true

2. 在远端 CLI 使用 API Key 登录

codex logout
codex login --with-api-key

按提示输入 API Key。不要把真实 Key 写在命令参数、脚本、博客、截图或 Git 提交中。

3. 重连并 fork

  1. 在笔记本 Codex App 中断开远端连接。
  2. 重新连接同一远端。
  3. 对原会话执行 Fork，在新会话中继续开发。

为什么必须 fork

会话创建时会记录当时使用的 provider。修改 config.toml 和重新登录只影响新请求或新会话，不能可靠地改变已经创建的旧会话。

Fork 会保留已完成的对话历史、计划和工作目录上下文，但会创建新的会话并读取当前配置。因此切换上游后，应当 fork，不要直接在旧会话中点击继续。

Fork 前先确保原会话没有正在执行的 turn。新旧会话不要同时修改同一个 worktree。

快速切换清单

官方 Plan -> 自定义 API

1. 远端 config.toml：去掉 model_provider、model、disable_response_storage 前的 #
2. 远端执行 codex logout
3. 远端执行 codex login --with-api-key
4. 笔记本 App 断开并重新连接远端
5. Fork 原会话

自定义 API -> 官方 Plan

1. 远端 config.toml：给 model_provider、model、disable_response_storage 前加 #
2. 远端执行 codex logout
3. 远端执行 codex login
4. 笔记本 App 断开并重新连接远端
5. Fork 原会话

验证是否切换成功

在远端项目目录先运行一次最小请求：

codex exec "只回复 provider-ok"

然后在 App 的 fork 会话中发送一条测试消息。

如果仍然报官方额度不足或 401 Unauthorized，按以下顺序检查：

  1. 远端 config.toml 是否真的保存到了当前远端用户的 ~/.codex/。
  2. model_provider 是否处于正确的注释/启用状态。
  3. 官方模式是否执行了 codex login。
  4. API 模式是否执行了 codex login --with-api-key。
  5. App 是否重新连接过远端。
  6. 是否从原会话 fork 了新会话。
  7. base_url 是否可访问，provider 的 wire_api 是否为 responses。

只有在 app-server 明显卡住、无法重连时，才需要结束远端 app-server 进程后重新连接；单纯 kill 进程不会改变登录模式或旧会话的 provider 绑定。

敏感信息保护

  • 不在文章、Issue、截图、日志或 Git 中出现真实 API Key。

  • 不公开真实 API 地址、账号 ID、access token、refresh token 或 auth.json 原文。

  • 远端检查权限：

    chmod 600 ~/.codex/auth.json
chmod 600 ~/.codex/config.toml