設定 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