Gate.AI›博客›如何在 Gate.AI 上設定 Claude Code

    如何在 Gate.AI 上設定 Claude Code

    指南

    Gate.AI Claude Code CLI 網關接入設定

    Gate.AI 支援將 Claude Code CLI 連接至相容 Anthropic 協議的網關，開發者可透過 Gate.AI API Key 與支援的 Claude 模型 ID，在終端環境下運行 AI 程式設計工作流程。此功能適用於希望透過 Gate.AI 路由 Claude Code 請求，而非僅使用 Anthropic 官方通道的開發者。本文將詳細介紹 Gate.AI Claude Code CLI 的接入流程、介面驗證、模型設定及常見問題排查，不涉及 Claude Desktop、Cursor 或 Codex 的設定。

    內容依據：Gate.AI 官方文件及 Claude Code 文件，截止 2026年6月。

    前置條件

    • 已註冊 Gate.AI 帳號，並擁有 API Key 與充足餘額。
    • 可於 macOS、Linux 或 WSL 環境存取 Claude Code CLI。

    完成本指南後你將獲得哪些能力？

    完成 gate.ai claude code 設定後，你可以在專案目錄下啟動 Claude Code，並透過 https://api.gate.ai/anthropic 路由 Claude Code 請求。

    本指南涵蓋推薦的使用者級 settings.json 設定、介面連通性測試，以及 401、404、認證衝突、逾時、npm 安裝等常見問題的解決方法。

    步驟一：建立 Gate.AI API Key

    請先建立 Gate.AI Key，因為 Claude Code 需依賴該密鑰後續設定 Base URL 與模型。

    操作方法：

    1. 登入 Gate.AI。
    2. 進入 Dashboard → API Keys。
    3. 新增 API Key。
    4. 複製以 sk-or-v1- 開頭的密鑰。
    5. 確認帳戶餘額充足。

    請勿將真實密鑰貼至公開倉庫、問題追蹤、共享截圖或已提交的專案檔案中。

    步驟二：檢測網關連通性

    在安裝或設定 Claude Code 之前，先測試 Anthropic 相容介面，以便將密鑰或網路問題與 CLI 設定問題區分開。

    將 YOUR_GATEAI_API_KEY 替換為你的真實 Gate.AI 密鑰：

    1. export GATEAI_API_KEY="YOUR_GATEAI_API_KEY"
    3. curl -s -o /dev/null -w "%{http_code}" \
    4.   -H "x-api-key: $GATEAI_API_KEY" \
    5.   -H "content-type: application/json" \
    6.   -H "anthropic-version: 2023-06-01" \
    7.   -d '{"model":"anthropic/claude-sonnet-4.6","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
    8.   https://api.gate.ai/anthropic/v1/messages

    你應看到以下結果之一：

    結果 含義 後續操作
    200 Gate.AI 網關可達 繼續進行 Claude Code 安裝
    401 API Key 無效、已過期或複製錯誤 檢查 Gate.AI 後台的密鑰
    Timeout 本地網路、DNS 或防火牆問題 檢查網路連線後重試
    404 路徑或 Base URL 設定錯誤 按上述要求使用正確的 Anthropic 路徑

    關鍵要點：Claude Code 必須使用相容 Anthropic 協議的 Gate.AI 路由，而非一般的 https://api.gate.ai/v1 路徑。

    步驟三：安裝 Claude Code CLI

    在 Gate.AI 網關測試通過後再安裝 Claude Code CLI，後續僅需本地 CLI 設定。

    推薦安裝方式（macOS、Linux 或 WSL）：

    1. curl -fsSL https://claude.ai/install.sh | bash

    npm 方式安裝：

    1. npm install -g @anthropic-ai/claude-code

    安裝後，驗證指令可用性：

    1. claude --version

    如終端顯示 command not found: claude，請重啟終端並確認安裝目錄已加入 PATH。

    步驟四：設定 Claude Code 相關參數

    在 ~/.claude/settings.json 中設定 Gate.AI 的 Anthropic Base URL、API Key 與模型 ID。

    如需所有專案皆統一使用 Gate.AI Claude Code，可採用使用者級設定：

    1. mkdir -p ~/.claude
    3. cat > ~/.claude/settings.json <<'EOF'
    4. {
    5.   "env": {
    6.     "ANTHROPIC_BASE_URL": "https://api.gate.ai/anthropic",
    7.     "ANTHROPIC_API_KEY": "YOUR_GATEAI_API_KEY",
    8.     "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6"
    9.   },
    10.   "includeCoAuthoredBy": false
    11. }
    12. EOF

    隨後清理可能與 Gate.AI API Key 衝突的舊 Anthropic 或代理會話：

    1. claude /logout 2>/dev/null || true
    2. unset ANTHROPIC_AUTH_TOKEN

    建議統一存放憑證。如 ~/.zshrc、~/.bashrc 或其他 shell 設定檔中仍有 ANTHROPIC_AUTH_TOKEN 或重複的 ANTHROPIC_API_KEY，請註解重複項並重啟終端。

    步驟五：於專案中驗證 Claude Code

    在你希望使用 AI 程式設計輔助的專案目錄下啟動 Claude Code。

    執行：

    1. cd YOUR_PROJECT_DIRECTORY
    2. claude

    Claude Code 啟動後，執行：

    1. Plain / status

    請確認 Base URL 為 https://api.gate.ai/anthropic，認證方式為 ANTHROPIC_API_KEY。隨後可發送測試提示：

    1. In one sentence, describe this repository.

    如回傳正常結果且無認證、路由或模型錯誤，表示 Claude Code 已成功透過 Gate.AI 請求。

    正確設定應為何？一覽表

    以下表格可用於快速核查 gate.ai claude code 設定：

    項目 正確值 說明
    Claude Code Base URL https://api.gate.ai/anthropic Claude Code 設定中使用此項
    Curl key-check URL https://api.gate.ai/anthropic/v1/messages 僅用於介面連通性驗證
    API key 變數 ANTHROPIC_API_KEY Claude Code 以此作為 API Key
    Model 變數 ANTHROPIC_MODEL 範例：anthropic/claude-sonnet-4.6
    模型 ID 格式 provider/model-name Gate.AI 需填寫完整模型 ID，勿用內建別名

    最常見錯誤是將 Claude Code 設定 URL 與原始 API 請求 URL 混用。Claude Code 應使用 Base URL，curl 驗證則需完整 /v1/messages 路徑。

    哪些 Base URL 是錯誤的？

    錯誤的 Base URL 通常會導致 404 錯誤或請求路由至錯誤協議。

    使用場景 正確值 常見錯誤值
    Claude Code CLI Base URL https://api.gate.ai/anthropic https://api.gate.ai/v1
    Anthropic curl 檢查 https://api.gate.ai/anthropic/v1/messages https://api.gate.ai/anthropic/messages
    OpenAI 相容工具 https://api.gate.ai/openai/v1 https://api.gate.ai/v1/chat/completions
    Claude Code 設定 https://api.gate.ai/anthropic https://api.gate.ai/anthropic/v1/messages

    Claude Code 必須使用 Anthropic 路徑，OpenAI 路徑僅供 OpenAI 相容工具使用。

    Claude Code 無法正常運作？排查清單

    • 症狀：Claude Code 顯示 Auth conflict: Both a token and an API key are set
      • 原因：ANTHROPIC_AUTH_TOKEN 與 ANTHROPIC_API_KEY 均被啟用
      • 解決：執行 claude /logout，取消設定 ANTHROPIC_AUTH_TOKEN，僅保留 ANTHROPIC_API_KEY
    • 症狀：Claude Code 回傳 401 或認證失敗
      • 原因：Gate.AI 密鑰錯誤、過期、未匯出或被其他 shell 設定覆蓋
      • 解決：重新從 Dashboard → API Keys 複製密鑰，並用 echo $ANTHROPIC_API_KEY 確認目前值
    • 症狀：Claude Code 回傳 404
      • 原因：Base URL 使用了 OpenAI 路由或完整請求路徑
      • 解決：將 Claude Code 設定為 https://api.gate.ai/anthropic，勿用 /openai/v1、/v1 或 /anthropic/v1/messages
    • 症狀：介面測試逾時
      • 原因：本地網路、DNS、代理或防火牆阻擋請求
      • 解決：嘗試更換網路、檢查 DNS，並於更改 Claude Code 設定前重試 curl
    • 症狀：npm 安裝出現 ETIMEDOUT 或 ECONNRESET
      • 原因：npm 源連線不穩，與 Gate.AI 網關無關
      • 解決：使用鏡像源重試：
    1. npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

    如 npm 安裝出現權限錯誤，請設定使用者級 npm prefix，避免使用不安全的提權安裝。

    後續可設定或整合的內容

    完成 Gate.AI Claude Code 設定後，可進一步拓展開發者工作流程：

    • 參考 Gate.AI API 整合指南，連接 OpenAI 相容 SDK 及標準 API 工作流程。
    • 如團隊需於 Cursor 中使用 Gate.AI 模型，可參考 Gate.AI Cursor 設定指南。
    • 檢查 Gate.AI 當前模型目錄後，為 Sonnet、Opus 或 Haiku 等不同檔位新增明確模型 ID。

    常見問題解答

    Claude Code 可以用 https://api.gate.ai/openai/v1 嗎？
    不能。Claude Code 必須使用相容 Anthropic 協議的 Gate.AI Base URL：https://api.gate.ai/anthropic。OpenAI 路徑僅供 OpenAI 風格工具、SDK 與介面使用。

    為什麼 /models 回傳 200，但 Claude Code 仍然失敗？
    模型列表介面回傳 200 並不能證明目前密鑰適用於 Claude Code。請務必用相容 Anthropic 的 /anthropic/v1/messages 進行 curl 檢查，因為該測試會發送帶認證的訊息請求。

    Gate.AI API Key 應存於 shell 變數還是 settings.json？
    建議二擇一，避免重複。對於本地穩定設定，使用者級 ~/.claude/settings.json 較易於稽核；臨時會話可用 shell 變數。

    Claude Code 可以將模型設定為 auto 嗎？
    建議先使用明確的 Gate.AI 模型 ID，如 anthropic/claude-sonnet-4.6。如 Gate.AI 已開啟自動路由且你的環境支援，可測試 auto，如遇路由錯誤請切回明確模型 ID。