·6 分鐘閱讀
如何在 Codex 使用 Doubao 豆包編碼

想在 Codex 使用 Doubao(豆包)編碼,可以透過火山方舟 Coding Plan,把 Codex CLI 連到豆包模型。方舟目前已有官方接入文件,並支援 Responses API,因此這條路線可以直接配置模型供應商,無須另外架設 LiteLLM。本文以 macOS/Linux 終端為主,從設定到第一個程式修復任務逐步說明。 方舟 Codex 文件
接入後,Codex 負責專案內的檔案操作與工具流程,選定的豆包模型負責推理和生成。第一次設定建議先使用練習資料夾,確認修改內容與測試結果,再帶進正式專案。
先確認帳號、模型與計費路線
本文使用 Coding Plan 專用 API Key 和專用地址。一般方舟 API、豆包聊天產品與 Coding Plan 是不同的使用入口。請先在控制台確認套餐已啟用、模型可選,再開始設定。個人 Coding Plan 的用途是支援的 AI 編程工具,正式應用程式的模型呼叫應另走適用的 API 服務。 套餐說明
為了讓「使用豆包」這件事清楚可追蹤,範例直接指定 doubao-seed-2.1-pro。若使用 ark-code-latest,則應在方舟控制台確認目前選到的是豆包,避免把自動路由到其他模型的結果混在一起。可用名稱以自己的控制台為準。 模型設定
安裝 Codex,先保留現有設定
已安裝的讀者可以先查看版本。全新安裝前,先準備目前受支援的 Node.js 環境,再執行安裝命令。
npm install -g @openai/codex codex --version
手動修改前請備份 ~/.codex/config.toml。已有檔案時,只合併下方相關鍵值,保留原來的 MCP、專案與其他設定,避免整份覆寫。若檔案已經有 model 或 model_provider,直接更新原本那一行,重複的 TOML 鍵值會造成解析失敗。
配置豆包供應商,使用 Responses 協定
將以下內容合併到使用者層級的 ~/.codex/config.toml。這裡的 env_key 是環境變數名稱,實際憑證在下一步輸入。 Codex 設定參考
model = "doubao-seed-2.1-pro" model_provider = "volcengine-coding-plan" [model_providers.volcengine-coding-plan] name = "Volcengine Coding Plan" base_url = "https://ark.cn-beijing.volces.com/api/coding/v3" env_key = "ARK_API_KEY" wire_api = "responses"
這組端點和協定對應方舟目前的 Codex 接入方式。Base URL 保留 /api/coding/v3 即可,由客戶端組合請求路徑,無須自行加上 /responses。使用套餐時,也要避免換成 /api/v3,因為一般 API 地址會走不同的計費路線。 官方接入範例
供應商設定應放在使用者設定層。現在的 Codex 會忽略專案 .codex/config.toml 中的供應商與認證重新導向鍵值,因此不要把它們只寫進專案資料夾。 設定層級說明
在終端載入 Key,啟動新的會話
以下做法讓 Bash 或 Zsh 在當前終端隱藏輸入 Key,之後從同一個終端啟動 Codex。檢查命令只顯示是否設定成功。
# macOS / Linux, Bash or Zsh printf 'ARK_API_KEY: ' read -rs ARK_API_KEY printf '\n' export ARK_API_KEY test -n "$ARK_API_KEY" && printf 'ARK_API_KEY is set\n'
先進入準備測試的專案目錄,再啟動新會話。若要明確選擇這個供應商,可使用單次命令列覆寫。
codex --model doubao-seed-2.1-pro \ -c 'model_provider="volcengine-coding-plan"'
命令列覆寫可指定本次執行的模型和供應商,仍需有前面的供應商定義。 Codex 命令列覆寫
桌面使用者還要確認執行應用程式的程序能取得 ARK_API_KEY。僅在某個終端 export,無法證明已開啟的桌面程序也已讀到同一份環境。建議先完成 CLI 路線,再處理桌面端的環境與重新啟動。
第一個編碼練習,修復折扣計算
單純請模型說一句話,只能確認基本回覆。我們建議用一個有明確預期值的任務,依序觀察它是否讀到檔案、修改函式並執行測試。以下是讀者可操作的練習,本文未使用真實方舟憑證執行端到端測試。
在另一個終端建立練習專案。首次執行會因為刻意放入的公式錯誤而失敗。
mkdir codex-doubao-demo
cd codex-doubao-demo
git init
cat > pricing.py <<'PY'
def discounted_price(cents, percent):
return cents * percent // 100
PY
cat > test_pricing.py <<'PY'
import unittest
from pricing import discounted_price
class PricingTests(unittest.TestCase):
def test_twenty_percent_off(self):
self.assertEqual(discounted_price(1000, 20), 800)
if __name__ == "__main__":
unittest.main()
PY
python3 -m unittest -v
原價 1000 分、折扣 20% 的應付金額是 800 分。目前程式回傳 200 分,把折抵金額當成了應付金額。從這個資料夾啟動已配置好的 Codex,再輸入下列任務。
先閱讀 pricing.py 和 test_pricing.py。 修正 discounted_price,讓它回傳折扣後的應付金額。 保留現有斷言,新增 0% 與 100% 折扣的測試。 不要新增依賴,也不要修改其他檔案。 執行 python3 -m unittest -v,最後列出修改內容與測試結果。
完成後自行執行 git diff 和 python3 -m unittest -v。應看到既有斷言保留、新增兩個邊界案例,且三個測試都通過。若助手只貼出程式碼、沒有落盤修改,或沒有執行測試,這個工作流程仍需繼續確認。
遇到錯誤,按這個順序排查
憑證錯誤先檢查啟動 Codex 的同一程序環境。接著比對 Base URL 與 Key 所屬服務,再核對模型名稱及帳號權限。出現找不到路徑或協定相關錯誤時,重新比對 /api/coding/v3 和 wire_api 設定,不要靠隨機更換網址嘗試。
能回答問題卻無法改檔時,先查看工具呼叫、工作目錄、審批與沙箱訊息。遇到限流或用量問題,先到方舟控制台查看套餐狀態,再縮小任務與上下文。保留可重現的最小任務,比一次要求重構整個專案更容易找出問題。
常見問題
一定要使用 LiteLLM 嗎?
本文這條路線直接連接方舟的 Responses 相容端點,不需要額外的轉換層。只有另有統一路由需求,或所用服務的協定不同時,才需要重新評估閘道方案。
能沿用 ChatGPT 訂閱的額度嗎?
此配置使用方舟的專用 Key 與 Coding Plan,應在方舟端確認可用量和計費。原本的 ChatGPT 訂閱無法作為已配置方舟額度的證明。
可以宣稱豆包在 Codex 一定更快、更便宜嗎?
要有同一專案、相同任務與可核對用量才能比較。本文提供接入方法與驗證練習,沒有延遲、成功率或成本實測資料。讀者可以先記錄一次小任務的完成情況,再決定是否投入更大的工作。
官方來源與核驗日期
本文於 2026 年 11 月 8 日核對官方文件。模型供應與帳號權限仍以控制台當下顯示為準。