Codex Plan Switcher

Codex CLI 一键切换火山方舟（Volcengine Ark）Coding Plan / Agent Plan 与多款模型的 Bash 脚本。

在同一个火山方舟账号下同时持有 Coding Plan 与 Agent Plan 时，用一个脚本管理两套 Base URL、两套 API Key、两套模型清单，并在 Codex CLI 中以友好名称显示当前模型。

✨ 特性

🖥️ Codex 界面可视：Codex 菜单直接显示当前 Plan 名称（如 Volcengine Agent Plan），/model 菜单显示全部模型友好名（如 GLM 5.3 Flash），同一 Plan 内无需退出 Codex 即可切换模型
🔄 双层三态切换：全局 / Codex profile 两层各自支持 Coding Plan / Agent Plan / OpenAI 官方默认，互不覆盖
🔢 序号 + 模型名双模式：coding 1 或 coding glm-5.3 均可，且不允许把 Coding Plan 的模型误写到 Agent Plan
🔑 双 Key 隔离：两个 Plan 各自独立环境变量，互不混用，便于单独轮换
🏷️ 友好显示名：自动生成 model_catalog_json 模型目录，告别千篇一律的 custom 标签
🛡️ 安全写入：原地编辑 ~/.codex/config.toml，只改 model 相关键，插件 / MCP / 项目信任等配置原样保留，每次修改前自动时间戳备份
📋 状态自检：status 随时查看当前 Plan 与模型，list 查看两套 Plan 的序号清单

📸 效果预览

切换完成后，Plan 与模型名称在 Codex 中一目了然，无需猜、无需翻配置：

① Codex 菜单显示当前 Plan 名称（Volcengine Agent Plan）：

② Codex 的 Model 菜单显示全部模型友好名并可直接切换（当前 GLM 5.3 Flash ✓）——同一 Plan 内换模型不用退出 Codex、不用改配置：

③ 终端脚本一键切换 + 状态自检（跨 Plan 切换走这里）：

💡 分工：跨 Plan 切换（Coding ↔ Agent ↔ OpenAI）用本脚本；同一 Plan 内换模型可直接在 Codex 的 Model 菜单点选完成。

📦 环境要求

依赖	说明
macOS / Linux	Bash 环境
Codex CLI	已安装并可正常运行
python3	仅用标准库，无需 pip 安装

🚀 快速开始

1. 获取脚本

git clone https://github.com/geekma/codex-plan-switcher.git
cd codex-plan-switcher
chmod +x switch-codex.sh

codex-base-prompt.md 需与 switch-codex.sh 放在同一目录（脚本按自身路径查找它，用于生成模型目录）。

2. 配置 API Key

复制 .env.example 的变量名，写入 ~/.zshrc（Key 只存环境变量，不落盘到本仓库）：

export ARK_CODING_PLAN_API_KEY="你的 Coding Plan Key"
export ARK_AGENT_PLAN_API_KEY="你的 Agent Plan Key"
source ~/.zshrc

两个 Plan 的 Key 完全分开，不能混用
若两个 Plan 由同一账号发放，也可填同一个 Key 值，但建议保持两个变量分开
Codex 启动时读取环境变量，改完 Key 需重启 Codex

3. 一键切换

./switch-codex.sh                 # 交互式菜单（全局配置 / Codex profile / 模型清单）
./switch-codex.sh global coding   # 全局 → Coding Plan（App 与默认 codex 生效）
./switch-codex.sh profile agent 4 # profile → Agent Plan 第 4 个模型（仅 codex -p volcengine 生效）
./switch-codex.sh global default  # 全局切回 OpenAI 官方
./switch-codex.sh status          # 查看全局 + profile 两层状态

📖 命令一览

命令	作用
`./switch-codex.sh`	交互式菜单（全局配置 / Codex profile / 模型清单）
`./switch-codex.sh global coding [序号\|模型名]`	全局切到 Coding Plan
`./switch-codex.sh global agent [序号\|模型名]`	全局切到 Agent Plan
`./switch-codex.sh global model [序号\|模型名]`	全局：当前 Plan 内切换模型
`./switch-codex.sh global default`	全局切回 OpenAI 官方默认 (`gpt-5.6-terra`)
`./switch-codex.sh profile coding [序号\|模型名]`	Codex profile 切到 Coding Plan
`./switch-codex.sh profile agent [序号\|模型名]`	Codex profile 切到 Agent Plan
`./switch-codex.sh profile model [序号\|模型名]`	profile：当前 Plan 内切换模型
`./switch-codex.sh profile default`	profile 切回 OpenAI 默认（清空 overlay）
`./switch-codex.sh coding / agent / model / default`	旧命令，等价于 `profile` 前缀
`./switch-codex.sh status`	显示全局 + profile 两层状态
`./switch-codex.sh list`	显示两套 Plan 的序号清单

全局配置与 Codex profile

交互式菜单会分别显示两类状态：

🌐 全局配置（Codex 默认 / ChatGPT chat）: ...
📌 Codex profile（codex -p volcengine）: ...

全局配置：写入 ~/.codex/config.toml 顶层键
Codex profile：写入 ~/.codex/volcengine.config.toml（overlay），只影响带 -p volcengine 的 Codex
两个作用域菜单结构相同：Coding Plan / Agent Plan / 在当前 Plan 内切换模型 / 恢复 OpenAI 默认

⚠️ 生效范围（必读）

入口	读哪层	受哪层控制
ChatGPT 桌面 App 的 chat	全局 `config.toml` 顶层	仅「全局配置」
ChatGPT 桌面 App 内的 Codex	全局 `config.toml` 顶层	仅「全局配置」
终端 `codex`（不带 -p）	全局 `config.toml` 顶层	仅「全局配置」（安装 wrapper 且 profile 激活时，会自动挂载 `-p volcengine` 走 profile 层）
终端 `codex -p volcengine`	全局 + profile overlay	仅「Codex profile」

关键结论：

App 的 chat 与 App 内的 Codex 共用同一份全局配置，App 内部无法把两者分开——全局层一切就一起切。不存在「App chat 保持默认 + App 内 Codex 走火山」的组合
App 永远不加载 profile。profile 只对显式 -p volcengine 的终端 Codex 生效
常见误区：只切了 profile（菜单 2），然后到 App 里找火山模型——App 显示默认模型是正常现象，不是切换失败
验证 profile 生效：新开一个终端窗口运行 codex（安装 wrapper 且 profile 已激活时自动挂载）或直接 codex -p volcengine，会话内查看模型名 / /status

典型组合：

# 全局默认 + 终端 codex 走火山（推荐，两层互不干扰）
./switch-codex.sh global default
./switch-codex.sh profile coding 9

# 全部走火山（App chat + App 内 Codex + 默认 codex 一起切）
./switch-codex.sh global coding

# 全部恢复默认
./switch-codex.sh global default
./switch-codex.sh profile default

只让终端 Codex 使用自定义模型

./switch-codex.sh global default                 # App / 默认 codex 保持默认
./switch-codex.sh profile agent glm-5.3-flash    # Codex profile 使用自定义模型
codex -p volcengine                              # 或安装 wrapper 后直接敲 codex

profile 配置写入 ~/.codex/volcengine.config.toml，只在启动时加 -p volcengine 生效，不改变全局 config.toml。

🧩 模型清单

Coding Plan（Base URL: `.../api/coding/v3`）

序号	模型
1	`doubao-seed-2.0-lite`
2	`kimi-k2.7-code`
3	`minimax-m3`
4	`doubao-seed-2.1-turbo`
5	`deepseek-v4-flash`
6	`glm-5.3`
7	`doubao-seed-evolving`
8	`deepseek-v4-pro`
9	`glm-5.3-flash`

Agent Plan（Base URL: `.../api/plan/v3`）

序号	模型
1	`doubao-seed-2.0-lite`
2	`doubao-seed-2.0-mini`
3	`kimi-k2.7-code`
4	`kimi-k3`
5	`minimax-m3`
6	`doubao-seed-2.1-turbo`
7	`deepseek-v4-flash`
8	`glm-5.3`
9	`doubao-seed-evolving`
10	`deepseek-v4-pro`
11	`glm-5.3-flash`

⚠️ 请勿使用 https://ark.cn-beijing.volces.com/api/v3，接入会产生额外费用。两套 Plan 均不支持 Auto 模式，需要 Auto 时请到火山方舟控制台切换。

⚙️ 工作原理

脚本按作用域对目标配置文件做原地编辑——「全局配置」编辑 ~/.codex/config.toml，「Codex profile」编辑 ~/.codex/volcengine.config.toml，两层文件互不触碰：

只修改顶层 model / model_provider / model_catalog_json 等键，其余配置原样保留（全局层恢复默认时会把 model_reasoning_effort 归位）
确保存在两个 provider 块（已存在则尊重现有内容）：

[model_providers.volcengine-coding]
name = "Volcengine Coding Plan"
base_url = "https://ark.cn-beijing.volces.com/api/coding/v3"
env_key = "ARK_CODING_PLAN_API_KEY"
wire_api = "responses"
requires_openai_auth = false

[model_providers.volcengine-agent]
name = "Volcengine Agent Plan"
base_url = "https://ark.cn-beijing.volces.com/api/plan/v3"
env_key = "ARK_AGENT_PLAN_API_KEY"
wire_api = "responses"
requires_openai_auth = false

生成 ~/.codex/codex-switch-models.json 模型目录并通过顶层 model_catalog_json 指向它，Codex（0.151.0-alpha.7.2+）即可显示友好模型名（如 Doubao Seed 2.0 Lite、Kimi K2.7 Code），且 /model 菜单会列出全部模型，在 Codex 内点选即可切换
每次修改前自动备份为 config.toml.bak.<时间戳>，恢复时先停 Codex，再把备份复制回去即可

🔋 Coding Plan 配额用完怎么办

Codex CLI 目前没有配额感知的 provider fallback（配额报错时不会自动换 provider）。检测到 Coding Plan 配额用完后，手动切换即可：

./switch-codex.sh agent <序号>

然后重启或新开 Codex 会话。

❓ FAQ

Codex 报 401 / API Key 错误

确认当前 Plan 对应的 Key 已设置，然后重新 source ~/.zshrc 并重启 Codex：

echo "${ARK_CODING_PLAN_API_KEY-}"
echo "${ARK_AGENT_PLAN_API_KEY-}"

App（chat / Codex）里看不到火山模型

App 只读全局配置，永远不会加载 profile。只切了 profile（菜单 2）后 App 显示默认模型是正常现象。想让 App 走火山模型请用全局切换（菜单 1 或 ./switch-codex.sh global coding），注意 App 的 chat 和 App 内 Codex 会一起切。验证 profile 生效请到终端运行 codex 或 codex -p volcengine。

切换后 Codex 仍显示旧模型

先运行 ./switch-codex.sh status：若输出已是新值，重启 Codex 即可；若仍是旧值，检查是否自定义了 CODEX_CONFIG_FILE 环境变量导致脚本写入了另一份配置。

旧版 Codex 显示 custom

不支持 model_catalog_json 的版本对自定义模型/provider 会显示 custom，这是 UI 展示限制，不影响配置与调用。真实 Plan 和模型以 ./switch-codex.sh status 输出为准。

📄 文件说明

文件	说明
`switch-codex.sh`	主脚本
`codex-base-prompt.md`	模型目录的 instructions 模板（源自开源 Codex CLI），需与脚本同目录
`.env.example`	环境变量名参考

License

MIT

Name		Name	Last commit message	Last commit date
docs/images		docs/images
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
codex-base-prompt.md		codex-base-prompt.md
codex_model_switching_guide.md		codex_model_switching_guide.md
switch-codex.sh		switch-codex.sh

Navigation Menu

Repository files navigation

Codex Plan Switcher

✨ 特性

📸 效果预览

📦 环境要求

🚀 快速开始

1. 获取脚本

2. 配置 API Key

3. 一键切换

📖 命令一览

全局配置与 Codex profile

⚠️ 生效范围（必读）

只让终端 Codex 使用自定义模型

🧩 模型清单

Coding Plan（Base URL: `.../api/coding/v3`）

Agent Plan（Base URL: `.../api/plan/v3`）

⚙️ 工作原理

🔋 Coding Plan 配额用完怎么办

❓ FAQ

📄 文件说明

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Codex Plan Switcher

✨ 特性

📸 效果预览

📦 环境要求

🚀 快速开始

1. 获取脚本

2. 配置 API Key

3. 一键切换

📖 命令一览

全局配置与 Codex profile

⚠️ 生效范围（必读）

只让终端 Codex 使用自定义模型

🧩 模型清单

Coding Plan（Base URL: .../api/coding/v3）

Agent Plan（Base URL: .../api/plan/v3）

⚙️ 工作原理

🔋 Coding Plan 配额用完怎么办

❓ FAQ

📄 文件说明

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Coding Plan（Base URL: `.../api/coding/v3`）

Agent Plan（Base URL: `.../api/plan/v3`）