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 需要使用 Gate.AI 的相容 Anthropic 協議路由，而不是通用路徑。

    步驟三：安裝 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 為 /anthropic，認證方式為 ANTHROPIC_API_KEY。接著可以送出測試提示：

    1. In one sentence, describe this repository.

    若回傳正常結果，且沒有出現認證、路由或模型錯誤，代表 Claude Code 已成功透過 Gate.AI 發出請求。

    正確設定應該長什麼樣？一覽表

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

    專案 正確值 說明
    Claude Code Base URL /anthropic Claude Code 設定中使用此項
    Curl key-check URL 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 路徑。

    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。

    相關文章

    如何在 Cursor 中完成 gate.ai Cursor 的設定

    如何在 Cursor 中完成 gate.ai Cursor 的設定

    如何整合 Gate.AI：開發者快速入門

    如何整合 Gate.AI：開發者快速入門