讓 Claude Code 走企業自管:從直連 Azure Foundry 到 API Gateway

為什麼要弄:當 AI 訂閱開始「換軌」

2026 年起,前沿模型供應商的計費邏輯正在改變:訂閱方案把「互動使用」和「自動化 / Agent 使用」拆成不同的計量池,企業帳號甚至無法直接購買訂閱、只能走 API。對個人開發者這是成本問題;但對企業,真正的痛點是另外兩個字:控管。

企業導入 AI 編碼工具時,資安與法遵部門會問的第一個問題永遠是:「我們的程式碼與機密,送去哪裡?誰能存取?怎麼稽核?成本怎麼歸戶?」 把 Claude Code 直接接公開 API,這些問題全部無解。解法是讓推論跑在公司自己的雲端租戶裡,資料留在合規邊界內,並在前面架一道統一閘道。本文就是這條路的逐步實戰,從最簡單的直連,進化到可上線的企業架構。延伸閱讀可參考我先前寫的 用 Claude Code Hooks 打造大腦反饋迴路。

全局:兩個階段

整條路分兩階段。先讓 Claude Code 直連雲端供應商上的 Claude(證明機制),再把它收斂到自家閘道後面(正式控管)。

階段一(直連):
  Claude Code  --->  https://<resource>.services.ai.azure.com/anthropic/v1/messages

階段二(閘道):
  Claude Code  --->  https://ai-gw.yourcompany.com/v1/messages  --->  雲端供應商後端
                     (自家 DNS、統一入口、依 model 路由、注入真憑證)

第一階段:Claude Code 直連雲端 Foundry

1. 在 Foundry 部署 Claude 模型

在 Foundry 入口建立資源並部署 base model。三個實務重點,踩過才知道:

• 地區限定:Claude 模型目前只開放在特定區域(本文撰寫時為 East US 2 與 Sweden Central),選錯區一定部署失敗。
• 務必接受服務條款:第一次在資源上部署 Claude,後台要建立一個對應的供應商組織(Anthropic Organization)。部署時跳出的 Terms of Service 一定要在「正確登入帳號」狀態下按接受,否則握手失敗。
• bad-state 陷阱:一旦某次部署握手失敗進入 bad state,該資源就修不好、重部任何模型都會死。正解是建立全新資源,別在壞掉的資源上重試。

2. 設定 Claude Code(settings.json)

最乾淨的做法是把環境變數寫進 Claude Code 的 settings.json 的 env 區塊(跨平台、持久,Windows 與 Linux 通用)。檔案位置:Linux 是 ~/.claude/settings.json,Windows 是 %USERPROFILE%\.claude\settings.json。

{
  "language": "繁體中文",
  "theme": "dark",
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "<your-resource-name>",
    "ANTHROPIC_FOUNDRY_API_KEY": "<your-foundry-key-or-omit-for-entra-id>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<your-sonnet-deployment-name>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL":   "<your-opus-deployment-name>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL":  "<your-haiku-deployment-name>"
  }
}

各變數的意義:

變數	作用
CLAUDE_CODE_USE_FOUNDRY	設為 1 啟用 Foundry 整合。沒設的話 Claude Code 會走預設的公開 Anthropic API。
ANTHROPIC_FOUNDRY_RESOURCE	你的資源名稱;Claude Code 會自動組成端點 https://<resource>.services.ai.azure.com/anthropic。
ANTHROPIC_DEFAULT_*_MODEL	三個層級(Sonnet/Opus/Haiku)各自的「部署名稱」,不是 model id。注意部署名可能跟 model 名不同(例如同名重建時會自動加序號)。

重要:ANTHROPIC_DEFAULT_*_MODEL 一定要填「實際部署名」。Claude Code 內部會依當下任務挑層級(主要寫 code 用 Sonnet/Opus,讀檔、摘要等雜活用 Haiku),把對應的部署名塞進請求送出。

3. 認證:Entra ID(建議)或 API 金鑰

兩種選擇。企業環境建議 Entra ID:不把金鑰寫進檔案,改用 Azure CLI 的身分,集中式身分管理、適合團隊與 CI/CD。只要在啟動 Claude Code 前登入即可:

# 方案 A:Entra ID(不放金鑰進檔案,建議)
az login
az account show        # 確認登入到正確訂閱
# 然後在 settings.json 拿掉 ANTHROPIC_FOUNDRY_API_KEY 那行即可

# 方案 B:API 金鑰(快速測試用)
# 直接把金鑰填進 settings.json 的 ANTHROPIC_FOUNDRY_API_KEY

4. 驗證設定

啟動 claude,在裡面打 /status,確認 API provider 顯示 Microsoft Foundry、resource 與 model 都正確。啟動橫幅若顯示類似 Sonnet 4.5 · API Usage Billing,代表它走的是 API 計量(雲端供應商),不是訂閱。最後送一句測試訊息,有正常回應就代表端到端打通。

5. 直接打 Messages API:預設協議就能用

很多人會問:不能直接用「預設的 Messages API」嗎?能,而且它就是。 Foundry 的端點本來就是標準的 Anthropic Messages API,只是換了網址與認證。跟原生 Anthropic API 只有三點差別:網址不同、model 欄位填「部署名」、認證用 Azure 的方式。以下是兩種認證的原始 curl:

# 用 API 金鑰(Header 是 x-api-key)
curl -X POST https://<resource>.services.ai.azure.com/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $AZURE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "<your-deployment-name>",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"Hello, which model are you?"}]
  }'

# 用 Entra ID(Header 是 Authorization: Bearer,scope https://ai.azure.com/.default)
curl -X POST https://<resource>.services.ai.azure.com/anthropic/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "<your-deployment-name>",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"Hello, which model are you?"}]
  }'

6. 一個必知限制:訂閱資格與配額

有個坑要先知道:Foundry 上的 Claude 通常限定企業等級訂閱(Enterprise / MCA-E),而且非企業訂閱的預設配額可能是 0 RPM / 0 TPM,免費 / 試用 / 純 credit 帳號不支援。意思是——你用個人帳號可以「部署成功」,但真正送推論時可能撞到 0 配額或資格錯誤。這正是企業要在正式的公司訂閱下跑、而不是個人帳號的硬理由。

第二階段:進化成 API Gateway

為什麼要 Gateway

直連能動,但每台機器各自拿著後端憑證、各自直接打雲端——這在企業是不可維護也不安全的。把一道閘道架在中間,你得到一個單一控制點:

• 統一認證與 RBAC:誰能用、能用哪些模型,集中管理;client 只拿你發的 token,永遠看不到後端真憑證。
• 稽核與成本歸戶:每一筆請求記 log,依使用者 / 專案歸戶成本。
• 限流與配額:在閘道做,而不是寄望每個 client 自律。
• 供應商解耦:哪天要把某個模型從 A 雲換成 B 雲,改閘道就好,幾百台 client 一行都不用動。

關鍵架構原則:一個入口,依 model 路由

最容易設計錯的地方:不要做成「Sonnet 一個網址、Opus 另一個網址」。 Claude Code 整個 session 只認一個 base URL,它靠請求 body 裡的 model 欄位區分模型,所有請求都送到同一個入口。所以正確設計是:閘道對外只露一個 DNS 入口,內部再依 model 名稱路由到對應的後端部署。你想像中的「API1 / API2 分流」應該活在閘道後面,對 client 只露一扇門。

Claude Code 改成 Gateway 模式

不再用 Foundry 那組變數,改用通用閘道模式。注意 model 這裡填「乾淨的標準名」,讓部署名的映射藏在閘道裡:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai-gw.yourcompany.com",
    "ANTHROPIC_AUTH_TOKEN": "<gateway-issued-token>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL":   "claude-opus-4-1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL":  "claude-haiku-4-5",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

• ANTHROPIC_BASE_URL(通用)取代 CLAUDE_CODE_USE_FOUNDRY;Claude Code 會打 {BASE_URL}/v1/messages。
• ANTHROPIC_AUTH_TOKEN 會以 Authorization: Bearer 送出(若閘道收 x-api-key,改用 ANTHROPIC_API_KEY)。
• model 填標準名,閘道內部再對應到實際部署名——client 從此不必知道後端命名怪癖。

閘道必須遵守的契約

你的閘道本質是一個 Anthropic Messages API 相容的透傳反向代理。違反任一條,Claude Code 與所有官方 SDK 就打不進去:

要求	說明
對外端點 POST /v1/messages	選配 /v1/messages/count_tokens、/v1/models(供模型發現)。
body 原樣透傳	收到什麼 Anthropic Messages JSON,就照樣轉發,絕不改 schema。
支援 SSE streaming	stream:true 必須逐塊串回,這是最常翻車的點。
依 model 欄位路由	把標準名映射成對應後端部署名並轉發。
後端注入真憑證	閘道持有後端金鑰 / service principal,client 永遠看不到。
錯誤碼原樣回	429 / 401 / 400 照轉,client 才能正確重試。

一條封包的端到端追蹤

把上面串起來,一通 Sonnet 請求與一通 Haiku 請求,打的是同一個網址,只有 body 的 model 不同:

# Claude Code 做主要工作(Sonnet 層)
POST https://ai-gw.yourcompany.com/v1/messages
Authorization: Bearer <gateway-token>
anthropic-version: 2023-06-01
{"model":"claude-sonnet-4-5","messages":[...],"stream":true}

# Claude Code 做雜活(Haiku 層)-- 網址與 token 一模一樣,只有 model 變
POST https://ai-gw.yourcompany.com/v1/messages
Authorization: Bearer <gateway-token>
{"model":"claude-haiku-4-5","messages":[...]}

# 你的 Gateway 收到後:
#   1) 驗 token + RBAC(這個人 / 這隊能用哪些 model)
#   2) 讀 model 欄位,查路由表:
#        claude-sonnet-4-5 -> 後端部署 "claude-sonnet-4-5-xx"
#        claude-haiku-4-5  -> 後端部署 "claude-haiku-4-5"
#   3) 改寫 model 成真部署名、換上後端真憑證、轉發到雲端
#   4) 後端回標準 Anthropic 回應 -> Gateway 原樣串回 -> Claude Code 收到

用現成的,別手刻 schema

別自己發明一套 JSON 格式包起來——那會讓 Claude Code 和所有官方 SDK 全部失效,很多公司「封裝 API」就死在這。直接用支援 Anthropic 相容 + model-based routing 的成熟方案:雲端原生的 API 管理服務(如 Azure API Management)、或開源的 LLM 閘道(如 LiteLLM proxy、Portkey)。它們原生就能做認證、限流、路由與 log。

常見錯誤與排查

症狀	原因 / 解法
Claude Code 一直要你登入 Anthropic	沒設 CLAUDE_CODE_USE_FOUNDRY=1,它走了預設公開 API。
model is not available	ANTHROPIC_DEFAULT_*_MODEL 沒對到實際部署名(注意同名重建的序號後綴)。
401 / 403	金鑰錯,或 Entra scope 不是 https://ai.azure.com/.default,或缺 RBAC 角色。
429 / 0 配額	非企業訂閱預設配額為 0;改用企業訂閱或申請配額。
部署一直 Failed 又刪不掉	資源進入 bad state;建新資源,別在壞掉的上面重試。
經閘道後 streaming 不會動	閘道沒正確透傳 SSE;確認 stream:true 的逐塊轉發。

結語

這條路的核心其實只有一句話:Foundry 的端點就是標準 Messages API,所以閘道只要當一個透傳代理。 先用直連證明機制能通,再用閘道把它收斂成「單一入口、依 model 路由、注入真憑證」的企業架構——資料留在合規邊界、計費可歸戶、供應商可替換。當前沿模型的使用門檻越來越高,能把它穩穩接進公司治理框架的能力,本身就是一種競爭力。