Codex CLI 接入

    建立 Gate.AI API 金鑰

    1. 打開 gate.ai → 控制台 → API 金鑰，建立並複製 sk-v1-… 開头的 Key
    2. 確認帳戶有餘額

    網路连通性驗證

    將 GATEAI_API_KEY 替換為您的金鑰：

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"

    OpenAI 相容端點（Codex / 標準 API）：

    bash
    1curl -s -o /dev/null -w "%{http_code}" \2  -H "Authorization: Bearer $GATEAI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model":"openai/gpt-5.2","input":"hi","max_output_tokens":16}' \5  https://api.gate.ai/openai/v1/responses
    • 回傳 200：閘道连通，可繼續安裝與設定
    • 回傳 401：金鑰無效或已過期，請檢查控制台
    • 連線逾時：檢查本地網路或 DNS；確認未誤用 https://api.gate.ai/v1

    安裝 Codex CLI

    bash
    1npm install -g @openai/codex

    或使用

    bash
    1curl -fsSL https://chatgpt.com/codex/install.sh | sh

    若已安裝 Homebrew

    bash
    1brew install --cask codex

    驗證：codex --version

    若 npm 安裝失敗

    通常是因為訪問 registry.npmjs.org 逾時或不穩定，與 Gate.AI 閘道無關。可按需選用以下方式：

    方式 A：單次安裝臨時指定鏡像（推薦先試）

    bash
    1npm install -g @openai/codex --registry=https://registry.npmmirror.com2npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

    方式 B：全域永久切換鏡像

    bash
    1# 設為 npmmirror（原淘宝 npm 鏡像，國內常用）2npm config set registry https://registry.npmmirror.com34# 驗證當前鏡像5npm config get registry67# 然後重新安裝8npm install -g @openai/codex9npm install -g @anthropic-ai/claude-code

    方式 C：僅當前終端工作階段臨時生效

    bash
    1export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com2npm install -g @openai/codex
    現象處理
    ETIMEDOUT / ECONNRESET使用方式 A 或 B 切換鏡像後重试
    EACCES 權限錯誤設定 npm 全域目录：mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global，並將 export PATH=~/.npm-global/bin:$PATH 寫入 ~/.zshrc
    command not found: claude / codex安裝成功但 PATH 未生效：重新啟動終端，或檢查 npm config get prefix 下的 bin 是否在 PATH 中

    設定模型

    將下文所有 sk-v1-你的金鑰 替換為您的真實 Key。設定完成後無需重複執行，除非更換 Key 或模型。

    bash
    1mkdir -p ~/.codex23cat > ~/.codex/config.toml <<'EOF'4model_provider = "gateai"5model = "openai/gpt-5.2"67[model_providers.gateai]8name = "Gate.AI"9base_url = "https://api.gate.ai/openai/v1"10env_key = "GATEAI_API_KEY"11wire_api = "responses"12requires_openai_auth = false13EOF1415grep -q 'GATEAI_API_KEY=' ~/.zshrc 2>/dev/null || cat >> ~/.zshrc <<'EOF'1617# Gate.AI for Codex CLI18export GATEAI_API_KEY="sk-v1-你的金鑰"19EOF2021source ~/.zshrc

    Codex 閘道相關設定必须寫在用戶級 ~/.codex/config.toml；專案目录下的 .codex/config.toml 無法覆寫這些項。

    驗證接入是否成功

    進入專案目录，啟動 CLI，即可在終端内進行 AI 輔助程式。

    使用 codex

    bash
    1codex

    若回傳正常回复且无 401 / 404，即表示已通過 Gate.AI 路由成功。

    進階設定

    設定参考

    欄位說明範例
    model_providerProvider 名称"gateai"
    modelGate.AI 模型 ID"openai/gpt-5.2"
    base_urlGate OpenAI 相容端點https://api.gate.ai/openai/v1
    env_keyAPI Key 環境變數名"GATEAI_API_KEY"
    wire_apiCodex 协议類型"responses"
    requires_openai_authGate Key 非 OpenAI 官方格式時false
    model_reasoning_effort推理強度（可選）"low" / "medium" / "high"

    備選設定方式

    內建 OpenAI Provider（方式 A 鑑權失敗時嘗試）

    toml
    1model = "openai/gpt-5.2"2openai_base_url = "https://api.gate.ai/openai/v1"

    環境變數：export OPENAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"

    命令列臨時覆寫

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"2codex --config openai_base_url='"https://api.gate.ai/openai/v1"' --config model='"openai/gpt-5.2"'

    切換模型

    修改 ~/.codex/config.toml 中的 model，或：codex --model openai/gpt-5.2

    恢復直連 OpenAI 官方（可選）

    刪除 ~/.codex/config.toml 中的 Gate 相關設定，並取消 GATEAI_API_KEY 環境變數。

    故障排除

    Base URL 常見錯誤

    bash
    1# ❌ 錯誤（缺 /openai 前綴，404）2https://api.gate.ai/v13https://api.gate.ai/v1/chat/completions45# ❌ 錯誤（Codex 設定項不要写完整 API 路徑）6https://api.gate.ai/openai/v1/messages7https://api.gate.ai/openai/messages89# ✅ 正確10https://api.gate.ai/openai/v1          # Codex CLI11https://api.gate.ai/anthropic/v1/messages  # curl 驗 Key（Anthropic）12https://api.gate.ai/openai/v1/responses    # curl 驗 Key（Codex）
    • /openai/v1/chat/completions 可用，但 Codex 必须走 Responses API；若报 404 on /responses，檢查 wire_api = "responses"，不是改 URL。
    • /openai/v1/models 不校驗 Key（無效 Key 也可能 200）；驗 Key 請用上面兩個 curl 地址。

    現象速查表

    現象錯誤類型處理建議
    401 / 鑑權失敗鑑權錯誤檢查 Key 是否正確、是否過期；Codex 確認 requires_openai_auth = false
    404 on URL路徑錯誤Claude → https://api.gate.ai/anthropic；Codex → https://api.gate.ai/openai/v1。勿用 https://api.gate.ai/v1/...
    404 on /responses协议錯誤Base URL 可能對，但未走 Responses API。檢查 ~/.codex/config.toml：wire_api = "responses"，base_url = "https://api.gate.ai/openai/v1"
    curl /models 回傳 200 但 CLI 仍 401驗 Key 方法錯誤/openai/v1/models 不校驗 Key。改用 /openai/v1/responses 或 /anthropic/v1/messages 驗 Key
    模型不存在模型 ID 錯誤使用 provider/model-name 格式（如 anthropic/claude-sonnet-4.6、openai/gpt-5.2），對照模型廣場
    仍連官方網域設定未生效確認寫在用戶級設定：Claude → ~/.claude/settings.json；Codex → ~/.codex/config.toml（專案级 .codex/config.toml 無法覆寫閘道設定）
    402 / 429配額 / 限流充值或檢查 Key 預算與呼叫頻率
    npm 安裝失敗網路 / 權限見「若 npm 安裝失敗」