配置 Codex CLI

把 Codex CLI 指向 StoryClaw 的 OpenAI Responses 接口，手动写配置文件或用 CC Switch 图形界面都可以。

Codex 默认连 OpenAI。改用 StoryClaw 需要两样东西：一段供应商配置，和一把放在环境变量里的密钥。

还没装 Codex 的话，先看安装 Codex CLI。密钥在控制台「API 密钥」页创建，见 API 密钥。下面两种方式二选一，结果完全相同。

Codex 走的是 Responses 协议，只能用 GPT 系列模型，见可用模型。Claude、DeepSeek、Kimi 等模型在 Codex 里用不了，要用它们去 Claude Code。

方式 A：手动配置

把下面的内容写进 ~/.codex/config.toml（文件不存在就新建）：

~/.codex/config.toml

model_provider = "storyclaw"
model = "gpt-5.6-sol"

[model_providers.storyclaw]
name = "StoryClaw"
base_url = "https://llm.storyclaw.com/v1"
env_key = "STORYCLAW_API_KEY"
wire_api = "responses"
disable_response_storage = true

这段配置里有几点容易搞错：

storyclaw 是你自己起的名字，但 model_provider = "storyclaw" 和 [model_providers.storyclaw] 这两处必须写成同一个词，想改名要两处一起改。别用 openai、ollama、lmstudio，这三个是 Codex 的保留名。
env_key 填的是环境变量的名字，不是密钥本身——密钥在下一步单独设置，不会出现在这个文件里。
base_url 要带 /v1，Codex 会在后面拼接 /responses。
disable_response_storage = true 必须加。StoryClaw 不保存 response，不关掉的话 Codex 会尝试用 previous_response_id 续接对话并报错。
model 只能填一个，它是默认模型，可用的 ID 见可用模型。想临时换用别的，启动时加 --model 即可。

macOS / Linux 可以一条命令写完：

下面这条命令会整份覆盖 ~/.codex/config.toml，已有的其他供应商、MCP 服务器等配置都会丢失。文件已存在的话，先备份（cp ~/.codex/config.toml ~/.codex/config.toml.bak），或者按上面的方式手动追加。

mkdir -p ~/.codex && cat > ~/.codex/config.toml <<'EOF'
model_provider = "storyclaw"
model = "gpt-5.6-sol"

[model_providers.storyclaw]
name = "StoryClaw"
base_url = "https://llm.storyclaw.com/v1"
env_key = "STORYCLAW_API_KEY"
wire_api = "responses"
disable_response_storage = true
EOF

再把密钥配成环境变量：

# macOS / Linux——写进 ~/.zshrc 或 ~/.bashrc 可持久生效
export STORYCLAW_API_KEY="你的 StoryClaw 密钥"

# Windows (PowerShell)——设置后需重新打开终端
setx STORYCLAW_API_KEY "你的 StoryClaw 密钥"

model_provider 和 model_providers 只在用户级的 ~/.codex/config.toml 里生效。写进项目级的 .codex/config.toml 不会被读取。

方式 B：CC Switch 图形界面

CC Switch 是一款开源的供应商管理工具，可视化操作，无需手写 TOML。它会把设置写进 ~/.codex/config.toml，结果和方式 A 相同。macOS 上 brew install --cask cc-switch 即可装完，其他平台见 CC Switch。

新增供应商

启动 CC Switch，切换到顶部的 Codex 标签页，点击右上角的 + 按钮。

填写配置

在「添加新供应商」弹窗中点「自定义配置」，先按下表填写基本信息。

选择自定义配置并填写表单

配置项	值	说明
供应商名称	`StoryClaw-Codex`	自定义，方便识别
官网链接	`https://storyclaw.com`	可选
API Key	你的 StoryClaw API 密钥	在控制台「API 密钥」页获取
API 请求地址	`https://llm.storyclaw.com/v1`	末尾不要加斜杠，标签旁的「完整 URL」开关保持关闭
默认模型	`gpt-5.6-sol`	留空且配了模型映射时，取映射表第一行
上游格式	Responses（原生）	在高级选项里。StoryClaw 原生就是 Responses API，选它即直连、不转换格式

请求地址填到 /v1 为止，不要开启旁边的「完整 URL」开关——后面的 /responses 由 Codex 自己拼接。开关开了会把 /v1 当成完整地址直接请求，报 404。

再展开表单底部的「高级选项」：

CC Switch 高级选项面板

选项	说明
需要本地路由映射	保持关闭。StoryClaw 原生支持 Responses 协议，Codex 直连即可，不需要本地转换。
支持思考等级	可选。开启后 Codex 的 `reasoning.effort`（low / medium / high）会自动转换为上游参数，适合需要控制推理预算的场景。

模型映射决定 Codex 里 /model 命令和桌面版模型下拉能看到哪些模型，在高级选项下面，按三步填：

点获取模型列表，按刚填好的地址和密钥拉取可用模型。
点添加模型，表格里会多出一行。
点这一行的下拉三角，从刚拉取到的列表里选模型；也可以直接手工输入，实际请求模型一列要与可用模型一致。

要几个模型就重复第 2、3 步几次。改完要重启 Codex 才会刷新。

最后继续下滑到 config.toml（TOML） 区块——这里能看到 CC Switch 实际会写进去的内容。勾选右上角的应用通用配置，配置才会写进全局的 ~/.codex/config.toml、对所有项目生效；然后点右下角添加完成。

CC Switch 会把配置连同密钥一起写进 ~/.codex/config.toml，不需要手动编辑任何文件，方式 A 里设环境变量那步也不用做。

启用供应商

添加完成后回到列表，鼠标移到 StoryClaw-Codex 一行，点击右侧出现的启用按钮。该行高亮即表示当前生效。

验证配置

先重启终端——Codex 启动时才读环境变量。然后进入任意项目目录：

codex

终端输入 codex 启动

启动界面顶部会显示当前使用的模型。发送任意消息（如「你好」），收到正常回复即表示接入成功。

Codex 启动后发送对话验证模型正常响应

使用 Codex 桌面版的话，同一份配置即刻生效，见 Codex 桌面版。

可用模型

Codex 走的是 OpenAI Responses 协议，它在 2026 年 2 月移除了对 Chat Completions 的支持。StoryClaw 目前对 Responses 开放的是 GPT 系列三款：

模型 ID	说明
`gpt-5.6-sol`	综合能力均衡
`gpt-5.6-luna`	响应更快
`gpt-5.6-terra`	偏重复杂任务

随时可以查最新清单：

curl https://llm.storyclaw.com/v1/models \
  -H "Authorization: Bearer 你的密钥"

返回结果里带 responses_api_url 字段的模型，就是 Codex 能直接使用的。

指定模型

会话里用 /model 切换，或启动时指定：

codex --model gpt-5.6-luna

常用调整

需求	做法
调整推理强度	配置里加 `model_reasoning_effort = "high"`，可选 `minimal`、`low`、`medium`、`high`
多套配置切换	存成 `~/.codex/<名字>.config.toml`，用 `codex --profile <名字>` 启动
长回复中途断开	供应商块里加 `stream_idle_timeout_ms = 600000`（默认 300000）

常见问题排查

现象	解决办法
报 `POST /v1/responses is not supported for model`	这个模型不支持 Responses 协议，Codex 用不了。换成 GPT 系列。
报 `Unknown model`	模型 ID 拼错了。用 `curl https://llm.storyclaw.com/v1/models` 核对准确写法。
多轮对话第二轮开始报错	配置里漏了 `disable_response_storage = true`。StoryClaw 不保存 response，Codex 用 `previous_response_id` 续接会失败。
报 `401` / 鉴权错误	密钥没设置或无效。用 `echo $STORYCLAW_API_KEY` 确认（PowerShell 用 `echo $env:STORYCLAW_API_KEY`），确认后重启终端。
报 `wire_api = "chat"` 不再支持	Codex 已移除 Chat Completions 支持，把配置改成 `wire_api = "responses"`。
改了配置不生效	没重启终端；或配置写进了项目级 `.codex/config.toml`——`model_provider` / `model_providers` 只从用户级 `~/.codex/config.toml` 读取。
请求仍然发往 OpenAI	`model_provider` 的值和 `[model_providers.…]` 里的名字没对上。
用方式 B 时报 `404`	请求地址多带了路径，或「完整 URL」开关误开了。地址填到 `https://llm.storyclaw.com/v1` 为止，开关保持关闭。
用方式 B 时配置没写进全局	编辑页的 config.toml（TOML）区块里，右上角的「应用通用配置」没勾。

装不上或 codex 命令找不到，见安装 Codex CLI。

On this page