Claude Code

Claude Code 是 Anthropic 推出的終端機程式開發工具。透過設定 API 地址、API Key 和模型 ID，可以讓 Claude Code 使用 AGTCloud 的 Anthropic Messages 相容入口。

本教學只介紹 Claude Code CLI。不同模型對工具呼叫、延伸思考和實驗功能的支援範圍可能不同，請選擇目前 API Key 可見且支援 Anthropic Messages 的模型。

準備工作

開始前，請確認你已經：

準備好終端機環境和 Git；
註冊並登入 AGTCloud；
在 API Keys 頁面建立權杖；
從模型廣場找到目前權杖可用的 Anthropic 協議模型 ID。

安裝 Claude Code

選擇與你的作業系統對應的安裝方式。原生安裝腳本會自動更新；Homebrew 和 WinGet 安裝需要透過各自的套件管理工具手動更新。

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

安裝完成後，重新開啟終端機並檢查版本：

claude --version
claude doctor

claude doctor 會檢查安裝狀態和設定檔。如果終端機提示找不到 claude，請重新開啟終端機，並確認安裝目錄已經加入 PATH。

設定 AGTCloud

Claude Code 會向 ANTHROPIC_BASE_URL 指定的地址傳送請求。這裡只填寫 AGTCloud API Origin，不要在末尾追加 /v1，因為 Claude Code 會自行請求 /v1/messages。

臨時設定

以下設定只在目前終端機工作階段中生效。請將 your-api-key 和 MODEL_ID 替換為自己的權杖和模型 ID。

unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

環境變數	作用
`ANTHROPIC_BASE_URL`	將 Claude Code 請求指向本頁顯示的 AGTCloud API 地址
`ANTHROPIC_API_KEY`	透過 `X-Api-Key` Header 傳送 AGTCloud API Key
`ANTHROPIC_MODEL`	指定本次工作階段預設使用的模型 ID

清除衝突的驗證變數

如果系統中已經設定 ANTHROPIC_AUTH_TOKEN，Claude Code 會將其作為 Bearer Token 使用，可能覆蓋 ANTHROPIC_API_KEY。使用本教學設定前，請先清除該變數。

持久設定

希望每次開啟終端機都自動生效時，可以把相同設定寫入 shell 設定檔或 Windows 使用者環境變數。API Key 會以明文形式儲存在本機，請只在個人可信任裝置上使用這種方式。

編輯 ~/.zshrc 並加入：

export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

儲存後載入設定：

source ~/.zshrc

cd /path/to/your/project

啟動 Claude Code

claude

如果首次啟動提示是否使用環境變數中的 API Key，請按終端機提示確認。

檢查目前設定

在 Claude Code 中執行：

/status

確認驗證來源為 API Key，並檢查 Base URL 是否為本頁顯示的 AGTCloud API 地址。Base URL 不應包含重複的 /v1。

發起唯讀測試

在包含 README.md 的測試專案中輸入：

請讀取 README.md，並用三點概括這個專案的用途。不要修改任何檔案。

能夠正常傳回內容，且 AGTCloud 控制台中出現對應呼叫記錄，說明基本連線已經建立。

完成設定檢查後，可以傳送一個簡單問題，確認模型能夠正常回應。

常見問題

現象	優先檢查	處理方式
找不到 `claude` 命令	安裝結果和 `PATH`	重新開啟終端機，執行 `claude doctor`，必要時重新執行官方安裝命令
啟動後仍要求登入	API Key 是否在啟動 Claude Code 的同一終端機中生效	檢查 `ANTHROPIC_API_KEY`，重新開啟終端機後再次啟動
API Key 沒有生效	是否同時設定了 `ANTHROPIC_AUTH_TOKEN`	清除衝突變數，透過 `/status` 核對驗證來源
傳回 `401`	API Key、環境變數和權杖狀態	重新複製有效 API Key，並透過 `/status` 確認驗證來源
傳回 `403`	權杖權限、模型權限和帳戶狀態	在控制台檢查權杖及模型可用範圍
傳回 `404`	Base URL 和模型 ID	Base URL 只填寫 `https://api.agtcloud.cn`，不要追加 `/v1`；重新複製模型 ID
找不到或無法使用模型	目前 API Key 可見模型和協議支援	選擇支援 Anthropic Messages 的模型，並透過 `ANTHROPIC_MODEL` 指定完整 ID
部分工具或進階功能不可用	模型能力和閘道相容情況	先使用基本對話驗證；進階能力以所選模型和目前適配結果為準

遇到無法定位的問題時，請記錄請求時間、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key。

安全建議

為 Claude Code 個別建立 API Key，便於管理權限和停用憑證。
不要把真實 Key 寫入程式碼、倉庫、截圖、記錄或共享腳本。
在共享裝置或團隊環境中，優先使用作業系統憑證管理或組織統一的金鑰分發方案。
API Key 疑似洩漏時，應立即在控制台停用或刪除，並建立新的 Key。

下一步可以繼續閱讀 API Key、Base URL 與驗證和 Anthropic Messages。