企業網路設定

為企業環境設定 Claude Code，包括代理伺服器、自訂憑證授權單位 (CA) 和相互傳輸層安全性 (mTLS) 驗證。

Claude Code 透過環境變數支援各種企業網路和安全設定。這包括透過公司代理伺服器路由流量、信任自訂憑證授權單位 (CA)，以及使用相互傳輸層安全性 (mTLS) 憑證進行驗證以增強安全性。

在啟動 Claude Code 之前，請設定這些環境變數。在您的 shell 中匯出的變數只會在啟動時讀取一次，因此執行中的工作階段不會取得您 shell 環境的後續變更。

代理設定

環境變數

Claude Code 遵守標準代理環境變數。在 Claude Desktop 工作階段中，應用程式管理提供者連線時，Claude Code 只會從受管設定和 ~/.claude/settings.json 讀取這些變數；請參閱 mTLS 驗證以了解範圍規則。

# HTTPS 代理（建議）
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP 代理（如果 HTTPS 不可用）
export HTTP_PROXY=http://proxy.example.com:8080

# 略過特定請求的代理 - 空格分隔格式
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# 略過特定請求的代理 - 逗號分隔格式
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# 略過所有請求的代理
export NO_PROXY="*"

小寫變體也可以使用，Claude Code 會按照 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的順序使用第一個已設定的變數。

Claude Code 永遠不會透過代理傳送其 WebSocket 連線到 localhost、::1 或 127.0.0.0/8，因此您不需要在 NO_PROXY 中為它們新增迴圈位址項目。

基本驗證

如果您的代理需要基本驗證，請在代理 URL 中包含認證資訊：

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

CA 憑證存放區

根據預設，Claude Code 信任其捆綁的 Mozilla CA 憑證和您作業系統的憑證存放區。讀取作業系統存放區需要具有 tls.getCACertificates 的執行時環境：原生安裝程式始終具有它，npm 安裝需要 Node 22.15 或更新版本。在較舊的 Node 版本上，只有捆綁的集合和 NODE_EXTRA_CA_CERTS 適用。企業 TLS 檢查代理在其根憑證安裝在作業系統信任存放區中且執行時可以讀取它時，無需額外設定即可運作。

CLAUDE_CODE_CERT_STORE 接受以逗號分隔的來源清單。認可的值為 bundled（Claude Code 隨附的 Mozilla CA 集合）和 system（作業系統信任存放區）。預設值為 bundled,system。

若只信任捆綁的 Mozilla CA 集合：

export CLAUDE_CODE_CERT_STORE=bundled

若只信任作業系統憑證存放區：

export CLAUDE_CODE_CERT_STORE=system

自訂 CA 憑證

如果您的企業環境使用自訂 CA，請設定 Claude Code 以直接信任它：

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

mTLS 驗證

對於需要用戶端憑證驗證的企業環境：

# 用於驗證的用戶端憑證
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# 用戶端私密金鑰
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# 選用：加密私密金鑰的密碼
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

Claude Code 在啟動時讀取憑證和金鑰檔案，並在每次套用設定時重新讀取它們，例如當您的組織在工作階段中期變更受管設定中的 env 區塊時。

若要輪換憑證和金鑰，請替換相同路徑上的檔案。Claude Code 會在執行中的工作階段中選取替換，無需重新啟動。當 API 要求因連線層級錯誤（例如連線重設或 TLS 握手錯誤）而失敗時，它會重新讀取兩個檔案，並使用新的金鑰對重試要求。在 v2.1.232 之前，Claude Code 不會在連線錯誤時重新讀取，因此它會保留已載入的金鑰對，直到下次套用設定或您重新啟動為止。

Claude Code 會根據失敗的要求重新讀取檔案，而不是透過監視檔案變更：

• 時機：當您替換檔案時，Claude Code 不會執行任何操作。它會在符合條件的失敗後的重試時或下次套用設定時呈現新的金鑰對，以先發生者為準。
• 閘道拒絕：當您的閘道重設連線或在停止接受舊金鑰對後拒絕 TLS 握手時，Claude Code 會重新讀取。當閘道完成握手並以 HTTP 錯誤回應時，它不會重新讀取。在這種情況下，Claude Code 會在下次套用設定時或重新啟動時載入新的金鑰對。
• 半寫入的輪換：當 Claude Code 在您的輪換進行中期重新讀取時（例如讀取不相符的憑證和金鑰），它會保留先前的金鑰對，並在下次失敗時重新讀取。
• OTLP 遙測匯出工具：Claude Code 會保留匯出工具在首次使用時載入的憑證，因此請重新啟動 Claude Code 以便輪換的憑證到達您的遙測收集器。
• 關閉重新載入：設定 CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 以關閉連線錯誤重新讀取。Claude Code 之後只會在下次套用設定或下次啟動時選取輪換的檔案。

若要確認 Claude Code 已選取輪換，請使用偵錯記錄啟動工作階段，並在記錄中尋找 Stale connection — reloaded rotated mTLS client material。當 Claude Code 在套用設定時選取輪換時，它不會記錄此行，因此單獨缺少此行並不表示輪換失敗。

在目前金鑰對過期之前替換檔案，以便 Claude Code 不會在下次啟動時載入已過期的金鑰對。

在雲端工作階段中，託管環境會管理與 API 的連線，因此當這些變數來自設定檔 env 區塊時，Claude Code 會忽略它們：

• CLAUDE_CODE_CLIENT_CERT
• CLAUDE_CODE_CLIENT_KEY
• CLAUDE_CODE_CLIENT_KEY_PASSPHRASE
• NODE_EXTRA_CA_CERTS
• NODE_TLS_REJECT_UNAUTHORIZED
• CLAUDE_CODE_OAUTH_SCOPES

Claude Code 會在工作階段的偵錯記錄中記錄每個被忽略的金鑰。

在Claude Desktop 工作階段中，應用程式管理提供者連線（例如第三方提供者上的 Code 標籤和 Cowork 工作階段），Claude Code 只會從受管設定和 ~/.claude/settings.json 讀取這些變數和 Proxy 變數 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY：它會忽略儲存庫自己的設定檔中的這些變數，因此簽出的儲存庫無法重新導向其認證來自應用程式的工作階段的 TLS 或 Proxy 路徑。在透過 claude.ai 登入的本機、SSH 或 WSL Code 標籤工作階段中，應用程式不會管理連線，Claude Code 會從每個設定範圍讀取這些變數，就像任何終端工作階段一樣；雲端工作階段無論您在何處啟動它們，都遵循上述雲端工作階段規則。在 v2.1.217 之前，當應用程式管理連線時，Claude Code 會忽略每個設定檔中的這些變數。

驗證您的設定

您通常會從稍後請求時的連線或憑證錯誤中發現代理位址錯誤或憑證路徑不正確的問題，因為 Claude Code 在讀取這些設定時不會驗證大多數設定。它在啟動時檢查的唯一設定是代理 URL：當它無法解析該值（例如缺少 http:// 配置）時，Claude Code 會停止啟動並顯示錯誤，指出要修正的變數。

若要在傳送請求前確認您的設定已載入，請使用偵錯記錄啟動 Claude Code：

claude --debug

偵錯輸出會進入 ~/.claude/debug/<session-id>.txt 而不是終端機，或進入您使用 --debug-file <path> 設定的路徑。在日誌中，尋找確認每個檔案已載入的行：

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

如果 Claude Code 無法讀取其中一個檔案，日誌會改為顯示 Failed to read 或 Failed to load 行及其原因。

您也可以在互動式工作階段中執行 /status 並檢查這些列：

• Proxy：顯示作用中的代理 URL，並將無法解析的值標記為無效且被忽略。
• mTLS client cert 和 mTLS client key：僅在檔案載入時出現，因此缺少列表示載入失敗，偵錯日誌中有原因。
• Additional CA cert(s)：顯示 NODE_EXTRA_CA_CERTS 路徑而不檢查檔案是否已載入，因此請在偵錯日誌中確認此項。

將網路設定套用至背景代理程式

背景代理程式不會在分派它們的終端機內執行。每個使用者的監督程序會依需求啟動、超越您的 shell，並裝載每個 claude agents、--bg 和 /background 工作階段。請參閱背景工作階段如何被裝載。這改變了此頁面上的設定如何到達這些工作階段的方式。

在設定中設定網路變數，而不是在 shell 中

監督程序是由每個終端機共享的單一程序。它繼承啟動它的第一個 shell 的環境，而作業系統安裝的監督程序根本不接收任何 shell 環境。如果您只在 shell 中匯出代理程式、CA 路徑或 mTLS 變數，當該 shell 碰巧冷啟動監督程序時，它會到達背景代理程式，而當不同的 shell 執行時，則會無聲地失敗。

改為將相同的變數放在 ~/.claude/settings.json 的 env 區塊中或受管設定中。此頁面上的每個變數都可以在那裡設定，而設定是唯一到達每台機器上每個背景工作階段的設定。

將公司啟動程式設定為設定

某些組織要求每個 Claude Code 程序都透過套用沙箱化、網路控制或認證注入的公司啟動程式啟動。監督程序及其工作程序從固定路徑啟動 Claude Code，而不是在 PATH 上查詢 claude，因此每個背景代理程式都會略過您在 PATH 上較早放置的包裝程式。

設定 processWrapper 設定以在監督程序、其工作程序和啟動程式涵蓋的內容下列出的其他背景程序前加上您的啟動程式。當兩者都設定時，等效的 CLAUDE_CODE_PROCESS_WRAPPER 環境變數優先，它受相同規則約束：透過受管設定或 ~/.claude/settings.json 傳遞它，而不是 shell 匯出。在公司啟動程式後面執行 Claude Code 涵蓋啟動程式必須滿足的合約、它執行和不執行的內容，以及如何推出它。

串流閒置監視狗

Claude Code 執行四個獨立的計時器，當串流模型回應變得安靜時會中止該回應，因此死連線會失敗並重試，而不是掛起。首位元組期限涵蓋等待回應標頭的時間，在任何回應到達之前。其他三個監視器各自監視即時回應的不同信號。

使用這些變數設定計時器，每個都在 環境變數參考 中詳細說明：

• CLAUDE_ENABLE_STREAM_WATCHDOG 和 CLAUDE_ENABLE_BYTE_WATCHDOG 在表格列出的連線內使用 1 強制對應的監視狗開啟或使用 0 關閉；兩個變數都不會將監視狗擴展到它不涵蓋的連線類型。CLAUDE_ENABLE_BYTE_WATCHDOG 設定為 0 也會關閉首位元組期限。
• CLAUDE_STREAM_IDLE_TIMEOUT_MS 設定兩個監視狗的逾時。Claude Code 將低於 5 分鐘的值提高到 5 分鐘，並將位元組層級監視狗的值上限設為 30 分鐘。
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS 設定位元組層級監視狗的逾時，而不改變事件層級監視狗的逾時，限制在 10 秒到 30 分鐘之間，並優先於 CLAUDE_STREAM_IDLE_TIMEOUT_MS 用於該監視狗。
• CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS 直接設定首位元組期限。保持未設定，Claude Code 會使用位元組層級監視狗的逾時，因此 CLAUDE_STREAM_IDLE_TIMEOUT_MS 和 CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS 也會改變期限。關於限制、上傳額度、API_TIMEOUT_MS 上限，以及重試在無回應中止後等待多長時間，請參閱 API 無回應。
• API_FORCE_IDLE_TIMEOUT 設定為 0 會關閉本體閒置逾時，設定為 1 會為每個提供者開啟。監視狗獨立於它執行，因此要讓串流暫停超過其閾值，也要提高或停用它們。

當監視狗中止停滯的串流時，Claude Code 將中止視為中流失敗，您看到的內容取決於回應進行的距離。Claude Code 重試請求或以錯誤結束回合，保留已完成的輸出並顯示 不完整回應通知，或正常結束回合。自動重試 說明每個結果適用的位置。

在 非互動式工作階段 中，以及任何工作階段中子代理的回應，Claude Code 可能首先提示 Claude 繼續被截斷的回應；該通知的項目 說明何時執行以及何時您仍然看到通知。

當首位元組期限觸發時，沒有回應已開始，因此沒有部分輸出要保留。關於 Claude Code 如何重新傳送請求以及何時回合改為結束，請參閱 API 無回應。

網路存取需求

Claude Code 需要存取下列 URL。在您的代理設定和防火牆規則中將這些 URL 加入允許清單，特別是在容器化或受限網路環境中。當無法連線到 api.anthropic.com 或 platform.claude.com 時，首次執行設定連線檢查會指向這裡；請參閱無法連線到 Anthropic 服務以了解檢查的訊息和復原步驟。

如果您透過 npm 安裝 Claude Code 或管理自己的二進位分佈，終端使用者不需要原生安裝程式和 downloads.claude.ai 的自動更新程式用途，但 npm 和 bun 安裝需要其套件登錄 registry.npmjs.org，除非您的組織鏡像它。表中的其他用途無論安裝方法為何都適用。

兩個 Datadog 進入主機僅攜帶選用的操作遙測，設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 會停用兩者。第三方提供者上的工作階段永遠不會傳送到這些主機，即使平台設定 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 且遙測指標預設為開啟。請參閱遙測服務以了解 Claude Code 傳送的所有內容以及如何在完成允許清單之前停用它。

使用 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或已登入的 Claude 應用程式閘道工作階段時，模型流量和驗證會連線到您的提供者或閘道，而不是 api.anthropic.com、claude.ai 或 platform.claude.com。WebFetch 工具仍會呼叫 api.anthropic.com 進行其網域安全檢查，除非您在設定中設定 skipWebFetchPreflight: true。

透過 LLM 閘道使用 ANTHROPIC_BASE_URL 進行路由時，快速模式可用性檢查仍會呼叫 api.anthropic.com 而不是閘道基底 URL。檢查會遵守已設定的 HTTP 代理，因此在網路區塊是原因的情況下，代理中 api.anthropic.com 的允許清單項目是修正方式。網路區塊只有在主機即使透過代理也無法連線時才會使檢查失敗，快速模式隨後會報告連線錯誤。當檢查呈現 Anthropic 拒絕的閘道簽發認證時，也會出現相同的連線錯誤；允許清單在那裡沒有幫助，因為沒有任何東西被阻止。請參閱在代理和 LLM 閘道後面使用快速模式以了解恢復它的變數。

組織 IP 允許清單和代理出口

如果您的組織已啟用 IP 允許清單用於 Claude，請透過與 claude.ai 和 api.anthropic.com 相同的代理出口路由 bridge.claudeusercontent.com，例如將其放在相同的 Zscaler 應用程式區段或 Netskope 轉向原則中。如果您無法以這種方式路由它，請將您的代理用於該主機的出口位址新增到您的組織 IP 允許清單，但僅當該位址專用於您的組織時：共用代理出口範圍也允許代理廠商的其他客戶。

Anthropic 使用它們到達的位址檢查與 bridge.claudeusercontent.com 的連線，針對您的組織 IP 允許清單。如果您的代理透過不在該允許清單上的位址傳送該主機的流量，Claude Code 無法連線到 Chrome 中的 Claude 擴充功能，即使 Claude Code 的其餘部分有效。

GitHub 允許清單和防火牆

Anthropic 託管環境中的網路上的 Claude Code 和程式碼審查從 Anthropic 管理的基礎設施連線到您的儲存庫；自託管環境中的工作階段從您的網路內部連線，除非執行器選擇加入 Anthropic git 代理，該代理從 Anthropic 的一側擷取。

如果您的 GitHub Enterprise Cloud 組織按 IP 位址限制存取，請啟用已安裝 GitHub Apps 的 IP 允許清單繼承，並且也新增允許清單項目用於 Anthropic 的出站 IP 位址。繼承僅涵蓋 Claude GitHub App 作為安裝進行的請求，不涵蓋它代表您的使用者進行的請求。對於其他防火牆，請參閱 Anthropic API IP 位址。

對於防火牆後面的自託管 GitHub Enterprise Server 執行個體，允許清單 Anthropic 的出站 IP 位址，以便 Anthropic 基礎設施可以連線到您的 GHES 主機以複製儲存庫和發佈審查評論。自託管環境中的工作階段改為從您的網路內部連線到您的 GHES 主機，因此該曝露僅適用於 Anthropic 託管工作階段、託管前工作階段流程（例如儲存庫選擇器）以及選擇加入 Anthropic git 代理的自託管執行器，該代理從 Anthropic 的一側擷取。對於僅在您的網路內部可路由的 GHES 主機，SCM 連接器會透過出站連線改為攜帶託管前工作階段流程，因此不需要允許清單。

桌面和 claude.ai

前面的表格涵蓋獨立 CLI。Claude Desktop 應用程式和瀏覽器中的 claude.ai 從其他 Anthropic CDN 主機載入其應用程式程式碼和使用者內容，包括 assets-proxy.anthropic.com 和其他在這些應用程式中提供 Artifact 的 *.claudeusercontent.com 來源。允許 claude.ai 同時阻止這些主機會產生空白頁面而不是錯誤。請參閱 Desktop 頁面上的網路存取需求。

從 Google Fonts 載入字型的 Artifact 也會要求 fonts.googleapis.com 和 fonts.gstatic.com。兩個主機都是選用的。如果您阻止它們，Artifact 會以備用字型呈現。使用快速拒絕而不是無聲丟棄進行阻止，以便字型要求立即失敗，而不是延遲頁面的首次呈現。

Artifact 也可以從 cdnjs.cloudflare.com、cdn.jsdelivr.net、cdn.tailwindcss.com、code.jquery.com 和 unpkg.com 載入 JavaScript 程式庫（例如 React 或圖表套件），而不是從任何其他外部主機。如果您阻止這些主機，Artifact 中依賴程式庫的部分將無法運作，與阻止的字型不同，阻止的程式庫沒有備用方案。此處也使用快速拒絕進行阻止，以便阻止的程式庫要求立即失敗，而不是掛起直到逾時。

其他資源

• 設定檔和優先順序
• 環境變數參考
• 疑難排解指南