2026 Claude Code 臨時 API 金鑰怎麼配置,避免長期憑證暴露?

Claude Code 官方文件指出,apiKeyHelper 超過 10 秒仍未回傳金鑰時,程式會顯示提示;若 helper 失敗、逾時或沒有輸出,請求也會在最多 3 次嘗試後失敗。這些數字說明憑據取用流程必須先測通。安全上,優先採用能按任務限定權限、時效並可撤銷的簽發方式,再由 apiKeyHelper 或受控閘道提供憑據;臨時金鑰不是沙箱,不能限制 Agent 讀取本機檔案或連線到其他網路服務。(Claude Code 認證與憑證管理文件)
個人開發者:避免把長期 API 金鑰寫進專案設定、指令稿或提交紀錄。
平台工程師:為團隊統一 Claude Code 的憑證簽發、輪替與撤銷流程。
安全工程師:評估短期憑證能縮小哪些暴露範圍,以及它無法取代的隔離措施。
先分清憑證用途,再決定怎麼交給 Agent
Claude Code 的模型服務憑證,不等於程式碼倉庫的存取權,也不等於雲端平台的部署權。把三者放進同一個工作環境,會讓一次模型任務意外擁有讀取程式碼、推送變更或操作雲端資源的能力。
| 憑證類型 | 典型用途 | 任務啟動前的檢查 |
|---|---|---|
| 模型服務憑證 | 透過 API 或閘道呼叫模型 | 限定可用模型或帳戶;確認誰能停用該憑證 |
| 程式碼倉庫憑證 | 讀取、提交或建立合併請求 | 僅開放必要倉庫與操作;不需要寫入就不要發寫入權限 |
| 雲端平台憑證 | 讀取部署資訊、修改雲端資源 | 優先用獨立執行身分;不要把個人管理員憑證交給 Agent |
如何避免 Claude Code 把 API 金鑰寫進專案檔案?不要把金鑰直接填入專案的 .claude/settings.json、範例環境檔或命令列參數,也不要把含有金鑰的終端輸出貼進提示。專案設定只放 helper 的位置或閘道端點等非祕密資訊;真正的憑證由任務開始時再向受控憑據系統索取。
macOS Keychain 可用來加密儲存小型祕密,並依存取控制設定管理哪些 App 可以取用項目;它不會自動替每種 API 金鑰設定到期時間,也不能替服務提供方撤銷已簽發的金鑰。Claude Code 文件說明,macOS 上的登入憑證一般存放於加密 Keychain;若 Keychain 寫入遭拒,例如 SSH 工作階段中 Keychain 鎖定,憑證可能改存於 ~/.claude/.credentials.json,檔案模式為 0600。因此,別把「有 Keychain」等同於「所有憑證都只會存在 Keychain」。可參考 Claude Code 認證與憑證管理文件及 Apple Keychain Services 說明,核對各自的儲存邊界。
任務簽發時:短效憑證要由服務端真正支援
「臨時」必須是簽發端的能力,不是使用者替長期金鑰加上名稱。只有當憑證提供方或閘道實際支援權限範圍、有效期限及撤銷操作時,任務級憑證才具備相應控制。可簽發多久、能限制到哪個資源、撤銷後何時生效,均須查該服務的官方文件,不能假設不同服務有相同規則。
受控閘道適合需要統一控管的團隊:模型供應商的上游憑證留在伺服器端,開發者取得閘道憑證,並可按使用者或團隊記錄使用情形。代價是團隊要維護閘道、監控憑證與日誌,還要跟進 Claude Code 更新造成的相容性變更。Anthropic 的閘道文件也提醒,閘道是組織要自行營運的基礎設施,第三方閘道的安全與功能不由 Anthropic 審核。
若服務無法簽發短期或可撤銷金鑰,就不要把一把長期金鑰直接提供給 Agent。改用獨立、低權限的執行身分;若連這點也做不到,應讓憑證留在 Agent 無法讀取的外部流程中,由人員或受控服務代為完成需高權限的操作。
第一階段:啟動前把權限與撤銷責任寫清楚
先列出 Agent 確實需要呼叫的服務,再逐項決定用途、權限與撤銷方式。模型 API 金鑰能呼叫模型,不代表也需要 Git 寫入權限;能讀取倉庫,也不代表應能修改雲端環境變數。
團隊至少記錄以下欄位:
- 憑證用途與對應的任務或工作單。
- 簽發主體、接收的執行身分,以及授權範圍。
- 有效期限的依據與撤銷入口。
- 撤銷責任人、審計方式,以及任務結束後的檢查人。
不確定服務支援哪些權限時,以該服務的官方文件為準。不要用一個無法核實的「通用最小權限」設定替代逐項查證。
第二階段:設定 Claude Code 憑據助手並檢查優先序
Claude Code 的 apiKeyHelper 可執行指令稿並回傳 API 金鑰,常見用途是向密鑰管理服務取得輪替或短期憑證。官方文件列有 CLAUDE_CODE_API_KEY_HELPER_TTL_MS,用來設定憑據需要重新整理的間隔;helper 的輸出會被快取,實際重新執行時機及目標版本行為,應在你的安裝版本核對。別把某個設定範例的 TTL 數字當成所有憑證提供方的有效期限。相關配置名稱、快取及認證入口可從 Claude Code 官方文件核對。
Claude Code 憑據助手如何取得及更新憑證?把 apiKeyHelper 指向團隊核准的指令稿,讓它透過受控憑據系統取得當前任務可用的憑證,並只把必要結果輸出給 Claude Code。快取期限到達後,Claude Code 才會按其機制再次呼叫 helper;helper 不會替簽發服務建立權限,也不能保證服務端已撤銷舊令牌。
設定可使用全域使用者設定,而非把祕密值寫進專案檔案:
{
"apiKeyHelper": "/使用者路徑/get-task-credential"
}
指令稿本身也要檢查:不要開啟會回顯祕密的 set -x,不要把標準輸出轉存到紀錄檔,也不要讓錯誤訊息包含完整令牌。若 helper 啟動時就失敗,Agent 可能無法認證;若指令稿一直回傳同一把未到期的長期金鑰,設定 helper 並不會自動把它變成短期憑證。
容易忽略的是認證優先序。當多種認證入口同時存在時,環境變數可能先於 helper 生效;官方列出的順序包括雲端供應商憑證、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY,其後才是 apiKeyHelper。所以即使已設定助手,殘留的環境變數仍可能令 Claude Code 使用另一個憑證來源。
可檢查「有沒有設定」而不把值印到終端:
for name in ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY CLAUDE_CODE_OAUTH_TOKEN; do
if printenv "$name" >/dev/null 2>&1; then
printf '%s is set\n' "$name"
fi
done
若發現不需要的變數,先確認來源,再從目前工作階段、Shell 設定檔或設定檔移除;不要只在互動終端執行 unset,卻漏掉 IDE 或自動化工作階段繼承的環境。完成後用 /status 核對實際使用的認證來源。
| 取用方式 | 優點 | 需要防範的限制 |
|---|---|---|
apiKeyHelper |
可按任務向外部憑據系統取用動態憑證 | helper 的權限、快取、輸出與失敗處理仍由團隊負責 |
| 環境變數 | 設定直接,適合明確控制的自動化工作 | 優先序可能壓過 helper;須查 Shell、IDE 與工作階段設定 |
| 受控閘道 | 可集中處理上游憑證、使用記錄與停用開發者憑證 | 增加閘道維運、相容性與日誌管理工作 |
| macOS Keychain | 適合保護由支援 Keychain 的登入流程儲存的本機祕密 | 不會替任意 helper 輸出自動新增期限或服務端撤銷能力 |
第三階段:Agent 執行期間,別把認證控制當成沙箱
短效憑證與最小授權能縮小憑證被濫用時的可用範圍;它們不會限制 Claude Code 或其他本機程式能讀取哪些檔案、執行哪些命令,或連線到哪些網路服務。這三項要分開配置與驗收。
| 要控制的範圍 | 應採用的控制 | 單靠臨時 API 金鑰是否足夠 |
|---|---|---|
| 模型 API 認證 | 簽發範圍、有效期限、撤銷 | 可以縮小模型憑證的可用範圍,視簽發端能力而定 |
| 本機檔案與命令 | Claude Code 權限設定及作業系統層隔離 | 不足;API 金鑰不決定檔案或命令權限 |
| 出站網路 | 防火牆、代理伺服器或執行環境網路政策 | 不足;認證期限不會封鎖其他網路連線 |
短期 API 金鑰能阻止 Claude Code 讀取本機檔案嗎?不能。金鑰限制的是向服務認證的能力,不是本機檔案系統的存取範圍。即使把模型金鑰設為短期,只要執行環境可讀取某個檔案,Agent 仍可能依其權限讀取;要限制檔案或網路,必須另設相應控制。Apple 的 Keychain 存取控制清單說明列出 App 存取 Keychain 項目的控制方式,但這不等於對 Claude Code 的全部檔案與網路活動建立隔離。
第四階段:任務結束後撤銷並搜尋殘留
任務結束不是只關閉終端機。先在憑證簽發端撤銷本次任務的令牌;若長期金鑰曾被貼入提示、寫入專案或出現在命令紀錄中,應按該服務的流程輪替長期金鑰。撤銷臨時憑證與輪替長期憑證是兩種不同處置,不要只做其中一項。
接著檢查以下位置:
- 目前終端、IDE 與啟動 Claude Code 的自動化工作階段,確認沒有殘留環境變數。
- 專案設定、範例環境檔、暫存檔、Shell 歷史與指令稿。
- 任務輸出、除錯紀錄及交接文件;搜尋時避免把找到的完整祕密再次印到共享終端或工單。
- 團隊的憑證系統或閘道記錄,確認簽發對象與撤銷結果;若服務不提供確認紀錄,就將此列為流程缺口,而不是假設已撤銷。
Claude Code 提供 claude purge 清除指定專案的本機狀態,包含對話紀錄、除錯記錄與提示歷史等項目;清除本機紀錄不等於撤銷 API 金鑰,兩件事要分開執行。可按 Claude Code 命令列工具文件核對清除範圍與操作方式。
團隊要先在低風險任務走完簽發、helper 取用、到期更新與撤銷,再擴大到共用開發環境。每次驗收留下憑證用途、授權範圍、責任人、撤銷時間與審計結果;任何具體期限則依憑證提供方文件設定,不套用未經證實的通用時長。
用條件分支選擇憑證路徑
- 若服務支援按任務限定權限、有效期限與撤銷,就由憑據系統或受控閘道簽發任務憑證,交給
apiKeyHelper取用。 - 若服務不能簽發短期令牌,但支援獨立低權限身分,改用該身分,並在任務結束時停用或輪替。
- 若既不能限制權限,也無法確認撤銷,不要把長期憑證交給 Agent;改由人員或外部受控服務完成需高權限的操作。
- 若目標是限制本機檔案、命令或網路存取,另外部署作業系統或執行環境層控制;不要期待臨時金鑰完成這項工作。
長期在本機沿用同一把金鑰,省去了簽發與撤銷流程,但會留下環境變數或紀錄檔殘留、憑證權限過大,以及 Agent 仍可接觸本機資料與網路等缺點。自建閘道可改善憑證集中管理,卻需要團隊承擔維運與相容性責任;租用遠端 Mac 執行環境則適合短期測試或需要獨立執行空間的工作,但環境隔離不代表憑證不會外洩,仍要按任務提供低權限憑證並在結束後回收。若工作必須長期穩定執行,或依賴本機實體介面,租用未必合適;若只是建立臨時測試環境,可先查看 ProxyMac 使用說明,核對登入與連線方式,再比較 ProxyMac 的方案資訊及本機執行的差異。