Documentation 2026-07-28 23:57 UTC to 2026-07-29 07:01 UTC

12 12 

13<Warning>13<Warning>

14 雖然開發容器提供了大量保護，但沒有任何系統完全免疫所有攻擊。14 雖然開發容器提供了大量保護，但沒有任何系統完全免疫所有攻擊。

15 當使用 `--dangerously-skip-permissions` 執行時，開發容器不會阻止惡意專案從容器內可存取的任何內容（包括儲存在 [`~/.claude`](/zh-TW/claude-directory) 中的 Claude Code 認證）進行資料外洩。15 當使用 `--dangerously-skip-permissions` 執行時，開發容器不會阻止惡意專案從容器內可存取的任何內容（包括儲存在 [`~/.claude`](/docs/zh-TW/claude-directory) 中的 Claude Code 認證）進行資料外洩。

16 僅在使用受信任的儲存庫進行開發時使用開發容器，並監控 Claude 的活動。16 僅在使用受信任的儲存庫進行開發時使用開發容器，並監控 Claude 的活動。

17 避免將主機祕密（例如 `~/.ssh` 或雲端認證檔案）掛載到容器中；優先使用儲存庫範圍或短期有效的令牌。17 避免將主機祕密（例如 `~/.ssh` 或雲端認證檔案）掛載到容器中；優先使用儲存庫範圍或短期有效的令牌。

18</Warning>18</Warning>

20<Accordion title="開發容器如何與您的編輯器配合使用">20<Accordion title="開發容器如何與您的編輯器配合使用">

21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="顯示主機上的編輯器連接到 Docker 開發容器的圖表。Claude Code、終端和構建工具在容器內執行。主機儲存庫被綁定掛載到容器中作為工作區。" width="640" height="300" data-path="images/devcontainer-architecture.svg" />21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="顯示主機上的編輯器連接到 Docker 開發容器的圖表。Claude Code、終端和構建工具在容器內執行。主機儲存庫被綁定掛載到容器中作為工作區。" width="640" height="300" data-path="images/devcontainer-architecture.svg" />

22 22 

23 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=ef00c8e25b1ea7a3a152895f1488831b" className="hidden dark:block" alt="顯示主機上的編輯器連接到 Docker 開發容器的圖表。Claude Code、終端和構建工具在容器內執行。主機儲存庫被綁定掛載到容器中作為工作區。" width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />23 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=a0a340b1f2afc6a590696102c8acaaca" className="hidden dark:block" alt="顯示主機上的編輯器連接到 Docker 開發容器的圖表。Claude Code、終端和構建工具在容器內執行。主機儲存庫被綁定掛載到容器中作為工作區。" width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />

24 24 

25 開發容器作為 Docker 容器執行，可以在您的機器上或雲端主機（例如 GitHub Codespaces）上執行。支援 Dev Containers 規範的編輯器（例如 VS Code、GitHub Codespaces、JetBrains IDE 或 Cursor）連接到該容器：您在編輯器中照常瀏覽和編輯檔案，但整合終端、語言伺服器和構建工具都在容器內執行，而不是在您的主機上。不支援開發容器的編輯器（例如純 Vim）不是此工作流程的一部分。25 開發容器作為 Docker 容器執行，可以在您的機器上或雲端主機（例如 GitHub Codespaces）上執行。支援 Dev Containers 規範的編輯器（例如 VS Code、GitHub Codespaces、JetBrains IDE 或 Cursor）連接到該容器：您在編輯器中照常瀏覽和編輯檔案，但整合終端、語言伺服器和構建工具都在容器內執行，而不是在您的主機上。不支援開發容器的編輯器（例如純 Vim）不是此工作流程的一部分。

26 26 

27 Claude Code 在容器內執行，因此它看到與您的專案工具鏈其餘部分相同的檔案、依賴項和工具。在 VS Code 中，您可以使用 [Claude Code 擴充功能面板](/zh-TW/vs-code) 或在整合終端中執行 `claude`；兩者都在容器內執行並共享相同的 `~/.claude` 配置。27 Claude Code 在容器內執行，因此它看到與您的專案工具鏈其餘部分相同的檔案、依賴項和工具。在 VS Code 中，您可以使用 [Claude Code 擴充功能面板](/docs/zh-TW/vs-code) 或在整合終端中執行 `claude`；兩者都在容器內執行並共享相同的 `~/.claude` 配置。

28</Accordion>28</Accordion>

29 29 

30<h2 id="add-claude-code-to-your-dev-container">30<h2 id="add-claude-code-to-your-dev-container">

75您在身份驗證提示中看到的內容取決於您的提供者：75您在身份驗證提示中看到的內容取決於您的提供者：

76 76 

77* **Anthropic**：透過瀏覽器使用您的 Claude 或 Anthropic Console 帳戶登入77* **Anthropic**：透過瀏覽器使用您的 Claude 或 Anthropic Console 帳戶登入

78* **[Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/zh-TW/third-party-integrations)**：Claude Code 使用您的雲端提供者認證，無需瀏覽器提示78* **[Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/docs/zh-TW/third-party-integrations)**：Claude Code 使用您的雲端提供者認證，無需瀏覽器提示

79 79 

80對於雲端提供者，透過 `containerEnv`、Codespaces 祕密或您的雲端的工作負載身份（而不是從主機掛載認證檔案）將認證傳遞到容器中。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 以了解 Claude Code 讀取的認證鏈。80對於雲端提供者，透過 `containerEnv`、Codespaces 祕密或您的雲端的工作負載身份（而不是從主機掛載認證檔案）將認證傳遞到容器中。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 以了解 Claude Code 讀取的認證鏈。

81 81 

82請參閱[選擇您的 API 提供者](/zh-TW/admin-setup#choose-your-api-provider)以決定哪條路徑適合您的組織。82請參閱[選擇您的 API 提供者](/docs/zh-TW/admin-setup#choose-your-api-provider)以決定哪條路徑適合您的組織。

83 83 

84<Note>84<Note>

85 如果瀏覽器登入完成但回調從未到達容器，請複製瀏覽器中顯示的代碼，並將其貼上到終端中的 `Paste code here if prompted` 提示處。當編輯器的連接埠轉發不會路由 localhost 回調時，可能會發生這種情況。85 如果瀏覽器登入完成但回調從未到達容器，請複製瀏覽器中顯示的代碼，並將其貼上到終端中的 `Paste code here if prompted` 提示處。當編輯器的連接埠轉發不會路由 localhost 回調時，可能會發生這種情況。

89 在重新構建時保持身份驗證和設定89 在重新構建時保持身份驗證和設定

90</h2>90</h2>

91 91 

92預設情況下，容器的主目錄在重新構建時會被丟棄，因此工程師必須每次都重新登入。Claude Code 將其身份驗證令牌、使用者設定和工作階段歷史記錄儲存在 [`~/.claude`](/zh-TW/claude-directory) 下。在該路徑掛載一個命名磁碟區以在重新構建時保持此狀態。92預設情況下，容器的主目錄在重新構建時會被丟棄，因此工程師必須每次都重新登入。Claude Code 將其身份驗證令牌、使用者設定和工作階段歷史記錄儲存在 [`~/.claude`](/docs/zh-TW/claude-directory) 下。在該路徑掛載一個命名磁碟區以在重新構建時保持此狀態。

93 93 

94以下示例在 `node` 使用者的主目錄掛載一個磁碟區：94以下示例在 `node` 使用者的主目錄掛載一個磁碟區：

95 95 

99]99]

100```100```

101 101 

102將 `/home/node` 替換為您的容器的 `remoteUser` 的主目錄。如果您在 `~/.claude` 以外的位置掛載磁碟區，請設定 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 為掛載路徑，以便 Claude Code 在那裡讀取和寫入。102將 `/home/node` 替換為您的容器的 `remoteUser` 的主目錄。如果您在 `~/.claude` 以外的位置掛載磁碟區，請設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 為掛載路徑，以便 Claude Code 在那裡讀取和寫入。

103 103 

104若要隔離每個專案的狀態，而不是在所有儲存庫中共享一個磁碟區，請在來源名稱中包含 `${devcontainerId}` 變數。[參考配置](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json)為此目的使用 `source=claude-code-config-${devcontainerId}`。104若要隔離每個專案的狀態，而不是在所有儲存庫中共享一個磁碟區，請在來源名稱中包含 `${devcontainerId}` 變數。[參考配置](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json)為此目的使用 `source=claude-code-config-${devcontainerId}`。

105 105 

106在 GitHub Codespaces 中，`~/.claude` 在停止和啟動 codespace 時會保持，但在重新構建容器時仍會被清除，因此上面的磁碟區掛載也適用於此。若要在 codespace 之間進行身份驗證，請將 `ANTHROPIC_API_KEY` 或來自 [`claude setup-token`](/zh-TW/authentication#generate-a-long-lived-token) 的 `CLAUDE_CODE_OAUTH_TOKEN` 儲存為 [Codespaces 祕密](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)；Codespaces 會自動將祕密作為環境變數提供給容器內。106在 GitHub Codespaces 中，`~/.claude` 在停止和啟動 codespace 時會保持，但在重新構建容器時仍會被清除，因此上面的磁碟區掛載也適用於此。若要在 codespace 之間進行身份驗證，請將 `ANTHROPIC_API_KEY` 或來自 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 的 `CLAUDE_CODE_OAUTH_TOKEN` 儲存為 [Codespaces 祕密](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)；Codespaces 會自動將祕密作為環境變數提供給容器內。

107 107 

108<h2 id="enforce-organization-policy">108<h2 id="enforce-organization-policy">

109 強制執行組織政策109 強制執行組織政策

111 111 

112開發容器是應用組織政策的便利場所，因為相同的映像和配置在每位工程師的機器上執行。112開發容器是應用組織政策的便利場所，因為相同的映像和配置在每位工程師的機器上執行。

113 113 

114Claude Code 在 Linux 上讀取 `/etc/claude-code/managed-settings.json` 並在[設定層級結構](/zh-TW/settings#how-scopes-interact)中以最高優先級應用它，因此那裡的值會覆蓋工程師在 `~/.claude` 或專案的 `.claude/` 目錄中設定的任何內容。從您的 Dockerfile 複製檔案到位置：114Claude Code 在 Linux 上讀取 `/etc/claude-code/managed-settings.json` 並在[設定層級結構](/docs/zh-TW/settings#how-scopes-interact)中以最高優先級應用它，因此那裡的值會覆蓋工程師在 `~/.claude` 或專案的 `.claude/` 目錄中設定的任何內容。從您的 Dockerfile 複製檔案到位置：

115 115 

116```dockerfile Dockerfile theme={null}116```dockerfile Dockerfile theme={null}

117RUN mkdir -p /etc/claude-code117RUN mkdir -p /etc/claude-code

118COPY managed-settings.json /etc/claude-code/managed-settings.json118COPY managed-settings.json /etc/claude-code/managed-settings.json

119```119```

120 120 

121因為 Dockerfile 存在於儲存庫中，任何具有寫入存取權限的人都可以更改或移除此步驟。對於工程師無法透過編輯儲存庫檔案來繞過的政策，請透過[伺服器管理的設定](/zh-TW/server-managed-settings)或您的 MDM 提供託管設定。請參閱[託管設定檔案](/zh-TW/settings#settings-files)以了解可用的鍵和其他傳遞路徑。121因為 Dockerfile 存在於儲存庫中，任何具有寫入存取權限的人都可以更改或移除此步驟。對於工程師無法透過編輯儲存庫檔案來繞過的政策，請透過[伺服器管理的設定](/docs/zh-TW/server-managed-settings)或您的 MDM 提供託管設定。請參閱[託管設定檔案](/docs/zh-TW/settings#settings-files)以了解可用的鍵和其他傳遞路徑。

122 122 

123若要設定適用於容器中每個 Claude Code 工作階段的[環境變數](/zh-TW/env-vars)，請將它們新增到您的 `devcontainer.json` 中的 `containerEnv`。以下示例選擇退出遙測和錯誤報告，並防止 Claude Code 在安裝後自動更新：123若要設定適用於容器中每個 Claude Code 工作階段的[環境變數](/docs/zh-TW/env-vars)，請將它們新增到您的 `devcontainer.json` 中的 `containerEnv`。以下示例選擇退出遙測和錯誤報告，並防止 Claude Code 在安裝後自動更新：

124 124 

125```json devcontainer.json theme={null}125```json devcontainer.json theme={null}

126"containerEnv": {126"containerEnv": {

131 131 

132Dev Container Feature 始終安裝最新的 Claude Code 版本。若要為可重現的構建固定特定的 Claude Code 版本，請從您的 Dockerfile 使用 `npm install -g @anthropic-ai/claude-code@X.Y.Z` 安裝它，而不是使用該功能，並設定 `DISABLE_AUTOUPDATER`，如上所示。132Dev Container Feature 始終安裝最新的 Claude Code 版本。若要為可重現的構建固定特定的 Claude Code 版本，請從您的 Dockerfile 使用 `npm install -g @anthropic-ai/claude-code@X.Y.Z` 安裝它，而不是使用該功能，並設定 `DISABLE_AUTOUPDATER`，如上所示。

133 133 

134如需完整的政策控制清單（包括權限規則、工具限制和 MCP 伺服器允許清單），請參閱[為您的組織設定 Claude Code](/zh-TW/admin-setup)。134如需完整的政策控制清單（包括權限規則、工具限制和 MCP 伺服器允許清單），請參閱[為您的組織設定 Claude Code](/docs/zh-TW/admin-setup)。

135 135 

136若要在容器內提供 [MCP 伺服器](/zh-TW/mcp)，請在儲存庫根目錄的 `.mcp.json` 檔案中以[專案範圍](/zh-TW/mcp#mcp-installation-scopes)定義它們，以便它們與您的開發容器配置一起簽入。在您的 Dockerfile 中安裝本地 stdio 伺服器所依賴的任何二進位檔案，並將遠端伺服器網域新增到您的網路允許清單。136若要在容器內提供 [MCP 伺服器](/docs/zh-TW/mcp)，請在儲存庫根目錄的 `.mcp.json` 檔案中以[專案範圍](/docs/zh-TW/mcp#mcp-installation-scopes)定義它們，以便它們與您的開發容器配置一起簽入。在您的 Dockerfile 中安裝本地 stdio 伺服器所依賴的任何二進位檔案，並將遠端伺服器網域新增到您的網路允許清單。

137 137 

138<h2 id="restrict-network-egress">138<h2 id="restrict-network-egress">

139 限制網路出站流量139 限制網路出站流量

140</h2>140</h2>

141 141 

142您可以將容器的出站流量限制為僅 Claude Code 需要的網域。請參閱[網路存取要求](/zh-TW/network-config#network-access-requirements)以了解推理和身份驗證網域，以及[遙測服務](/zh-TW/data-usage#telemetry-services)以了解可選的遙測和錯誤報告連接以及如何停用它們。142您可以將容器的出站流量限制為僅 Claude Code 需要的網域。請參閱[網路存取要求](/docs/zh-TW/network-config#network-access-requirements)以了解推理和身份驗證網域，以及[遙測服務](/docs/zh-TW/data-usage#telemetry-services)以了解可選的遙測和錯誤報告連接以及如何停用它們。

143 143 

144參考容器包含一個 [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) 指令碼，該指令碼會阻止除 Claude Code 和您的開發工具需要的網域之外的所有出站流量。在容器內執行防火牆需要額外的權限，因此參考透過 `runArgs` 新增 `NET_ADMIN` 和 `NET_RAW` 功能。防火牆指令碼和這些功能對 Claude Code 本身不是必需的：您可以將它們省略並改為依賴您自己的網路控制。144參考容器包含一個 [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) 指令碼，該指令碼會阻止除 Claude Code 和您的開發工具需要的網域之外的所有出站流量。在容器內執行防火牆需要額外的權限，因此參考透過 `runArgs` 新增 `NET_ADMIN` 和 `NET_RAW` 功能。防火牆指令碼和這些功能對 Claude Code 本身不是必需的：您可以將它們省略並改為依賴您自己的網路控制。

145 145 

151 151 

152跳過權限提示會移除您在工具呼叫執行前進行審查的機會。Claude 仍然可以修改綁定掛載工作區中的任何檔案（該檔案直接出現在您的主機上），並到達容器的網路政策允許的任何內容。將此標誌與上面的[網路出站流量限制](#restrict-network-egress)配對，以限制繞過的工作階段可以到達的內容。152跳過權限提示會移除您在工具呼叫執行前進行審查的機會。Claude 仍然可以修改綁定掛載工作區中的任何檔案（該檔案直接出現在您的主機上），並到達容器的網路政策允許的任何內容。將此標誌與上面的[網路出站流量限制](#restrict-network-egress)配對，以限制繞過的工作階段可以到達的內容。

153 153 

154如果您想要更少的提示而不停用安全檢查，請考慮改為[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，該模式具有在執行前審查操作的分類器。若要完全防止工程師使用 `--dangerously-skip-permissions`，請在[託管設定](/zh-TW/settings#permission-settings)中將 `permissions.disableBypassPermissionsMode` 設定為 `"disable"`。154如果您想要更少的提示而不停用安全檢查，請考慮改為[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，該模式具有在執行前審查操作的分類器。若要完全防止工程師使用 `--dangerously-skip-permissions`，請在[託管設定](/docs/zh-TW/settings#permission-settings)中將 `permissions.disableBypassPermissionsMode` 設定為 `"disable"`。

155 155 

156<h2 id="try-the-reference-container">156<h2 id="try-the-reference-container">

157 試用參考容器157 試用參考容器

193 193 

194Claude Code 在您的開發容器中執行後，下面的頁面涵蓋組織推出的其餘部分：選擇身份驗證路徑、在儲存庫外提供託管政策、監控使用情況以及了解 Claude Code 儲存和傳送的內容。194Claude Code 在您的開發容器中執行後，下面的頁面涵蓋組織推出的其餘部分：選擇身份驗證路徑、在儲存庫外提供託管政策、監控使用情況以及了解 Claude Code 儲存和傳送的內容。

195 195 

196* [為您的組織設定 Claude Code](/zh-TW/admin-setup)：選擇身份驗證提供者、決定政策如何到達裝置以及規劃推出196* [為您的組織設定 Claude Code](/docs/zh-TW/admin-setup)：選擇身份驗證提供者、決定政策如何到達裝置以及規劃推出

197* [伺服器管理的設定](/zh-TW/server-managed-settings)：從 Claude.ai 管理員控制台提供託管政策，以便工程師無法透過編輯儲存庫檔案來繞過它197* [伺服器管理的設定](/docs/zh-TW/server-managed-settings)：從 Claude.ai 管理員控制台提供託管政策，以便工程師無法透過編輯儲存庫檔案來繞過它

198* [監控使用情況和審計活動](/zh-TW/monitoring-usage)：匯出 OpenTelemetry 指標並審查您的團隊正在執行的內容198* [監控使用情況和審計活動](/docs/zh-TW/monitoring-usage)：匯出 OpenTelemetry 指標並審查您的團隊正在執行的內容

199* [網路存取要求](/zh-TW/network-config#network-access-requirements)：代理和防火牆的完整網域允許清單199* [網路存取要求](/docs/zh-TW/network-config#network-access-requirements)：代理和防火牆的完整網域允許清單

200* [遙測服務和選擇退出](/zh-TW/data-usage#telemetry-services)：Claude Code 預設傳送的內容以及停用它的環境變數200* [遙測服務和選擇退出](/docs/zh-TW/data-usage#telemetry-services)：Claude Code 預設傳送的內容以及停用它的環境變數

201* [探索 `.claude` 目錄](/zh-TW/claude-directory)：磁碟區掛載包含的內容，包括認證、設定和工作階段歷史記錄201* [探索 `.claude` 目錄](/docs/zh-TW/claude-directory)：磁碟區掛載包含的內容，包括認證、設定和工作階段歷史記錄

202* [沙箱環境](/zh-TW/sandbox-environments)：比較開發容器與內建 Bash 沙箱、自訂容器和虛擬機器202* [沙箱環境](/docs/zh-TW/sandbox-environments)：比較開發容器與內建 Bash 沙箱、自訂容器和虛擬機器

203* [安全模型](/zh-TW/security)：Claude Code 的權限系統、沙箱和提示注入保護如何組合在一起203* [安全模型](/docs/zh-TW/security)：Claude Code 的權限系統、沙箱和提示注入保護如何組合在一起

204* [Permission modes](/zh-TW/permission-modes)：從 Plan Mode 到 auto mode 到 bypass 的完整範圍，以及何時使用每種模式204* [Permission modes](/docs/zh-TW/permission-modes)：從 Plan Mode 到 auto mode 到 bypass 的完整範圍，以及何時使用每種模式

20 20 

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四個轉換顯示為不斷增長的水平條。每個轉換的請求包含前一個轉換的所有內容加上附加在末尾的最新交換。在第二和第三個轉換中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個轉換中，系統提示已變更，因此前綴不再匹配，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四個轉換顯示為不斷增長的水平條。每個轉換的請求包含前一個轉換的所有內容加上附加在末尾的最新交換。在第二和第三個轉換中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個轉換中，系統提示已變更，因此前綴不再匹配，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22 

23<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=7434a04e08187edd26ec6c3dd332f624" className="hidden dark:block" alt="四個轉換顯示為不斷增長的水平條。每個轉換的請求包含前一個轉換的所有內容加上附加在末尾的最新交換。在第二和第三個轉換中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個轉換中，系統提示已變更，因此前綴不再匹配，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="四個轉換顯示為不斷增長的水平條。每個轉換的請求包含前一個轉換的所有內容加上附加在末尾的最新交換。在第二和第三個轉換中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個轉換中，系統提示已變更，因此前綴不再匹配，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24 

25為了充分利用前綴匹配，Claude Code 會組織每個請求，使轉換之間很少變更的內容首先出現：25為了充分利用前綴匹配，Claude Code 會組織每個請求，使轉換之間很少變更的內容首先出現：

26 26 

32 32 

33對對話層的變更會保留系統提示和專案上下文的快取。對系統提示的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三列提供常見觸發器而不是詳盡列表，下面的部分涵蓋完整集合，包括在會話開始時固定的輸出風格等內容。33對對話層的變更會保留系統提示和專案上下文的快取。對系統提示的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三列提供常見觸發器而不是詳盡列表，下面的部分涵蓋完整集合，包括在會話開始時固定的輸出風格等內容。

34 34 

35前綴匹配規則解釋了本頁上的大多數行為。例如，[Plan Mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 和[技能加載](/zh-TW/skills)將其指令附加為對話訊息，因此快取的前綴保持完整。35前綴匹配規則解釋了本頁上的大多數行為。例如，[Plan Mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 和[技能加載](/docs/zh-TW/skills)將其指令附加為對話訊息，因此快取的前綴保持完整。

36 36 

37兩個設定根本不是提示文本的一部分，因此它們不會出現在層表中，但兩者都是快取金鑰的一部分：37兩個設定根本不是提示文本的一部分，因此它們不會出現在層表中，但兩者都是快取金鑰的一部分：

38 38 

49 49 

50快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您如何進行身份驗證：50快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您如何進行身份驗證：

51 51 

52* **API 金鑰、Claude 訂閱或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)**：快取位於 Anthropic 的基礎設施中，通過 [Claude API](https://platform.claude.com/docs) 訪問52* **API 金鑰、Claude 訂閱或 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)**：快取位於 Anthropic 的基礎設施中，通過 [Claude API](https://platform.claude.com/docs) 訪問

53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：快取位於您的雲端提供商的服務基礎設施中53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：快取位於您的雲端提供商的服務基礎設施中

54* **Microsoft Foundry**：請求路由到 Anthropic 的基礎設施54* **Microsoft Foundry**：請求路由到 Anthropic 的基礎設施

55* **自訂 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/zh-TW/llm-gateway)**：快取位於您的請求轉發到的位置，快取是否工作取決於閘道55* **自訂 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/docs/zh-TW/llm-gateway)**：快取位於您的請求轉發到的位置，快取是否工作取決於閘道

56 56 

57有關每個提供商存儲和處理的內容，請參閱[資料使用](/zh-TW/data-usage)。無論快取位於何處，條目在一段時間不活動後過期，[下面的快取生命週期](#cache-lifetime)涵蓋 TTL 以及如何延長它。57有關每個提供商存儲和處理的內容，請參閱[資料使用](/docs/zh-TW/data-usage)。無論快取位於何處，條目在一段時間不活動後過期，[下面的快取生命週期](#cache-lifetime)涵蓋 TTL 以及如何延長它。

58 58 

59<h2 id="actions-that-invalidate-the-cache">59<h2 id="actions-that-invalidate-the-cache">

60 使快取失效的操作60 使快取失效的操作

75 切換模型75 切換模型

76</h3>76</h3>

77 77 

78每個模型都有自己的快取。使用 [`/model`](/zh-TW/model-config#setting-your-model) 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中，即使內容相同。78每個模型都有自己的快取。使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中，即使內容相同。

79 79 

80[`opusplan` 模型設定](/zh-TW/model-config#opusplan-model-setting)在 Plan Mode 期間解析為 Opus，在執行期間解析為 Sonnet，因此每個 Plan Mode 切換都是模型切換並啟動新的快取。80[`opusplan` 模型設定](/docs/zh-TW/model-config#opusplan-model-setting)在 Plan Mode 期間解析為 Opus，在執行期間解析為 Sonnet，因此每個 Plan Mode 切換都是模型切換並啟動新的快取。

81 81 

82[Fable 5 上的自動模型回退](/zh-TW/model-config#automatic-model-fallback)也是模型切換。當安全分類器標記請求時，Claude Code 會在預設 Opus 模型上重新執行它，會話會在那裡繼續。82[Fable 5 上的自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)也是模型切換。當安全分類器標記請求時，Claude Code 會在預設 Opus 模型上重新執行它，會話會在那裡繼續。

83 83 

84<h3 id="changing-effort-level">84<h3 id="changing-effort-level">

85 變更努力程度85 變更努力程度

86</h3>86</h3>

87 87 

88快取由[努力程度](/zh-TW/model-config#adjust-effort-level)以及模型作為鍵，因此使用 `/effort` 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中。一旦對話開始，Claude Code 會在應用會使快取失效的努力程度變更之前顯示確認對話框。解析為已生效的相同程度的變更（例如明確設定模型的預設值）會跳過對話框並保持快取。88快取由[努力程度](/docs/zh-TW/model-config#adjust-effort-level)以及模型作為鍵，因此使用 `/effort` 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中。一旦對話開始，Claude Code 會在應用會使快取失效的努力程度變更之前顯示確認對話框。解析為已生效的相同程度的變更（例如明確設定模型的預設值）會跳過對話框並保持快取。

89 89 

90<h3 id="turning-on-fast-mode">90<h3 id="turning-on-fast-mode">

91 開啟快速模式91 開啟快速模式

92</h3>92</h3>

93 93 

94啟用[快速模式](/zh-TW/fast-mode)會新增一個請求標頭，該標頭是快取鍵的一部分，因此下一個請求讀取整個對話歷史記錄而沒有快取命中。這些未快取的輸入令牌按[快速模式費率](/zh-TW/fast-mode#understand-the-cost-tradeoff)計費，這就是為什麼在會話開始時開啟它的成本比在長會話深處開啟它的成本要低。從非 Opus 模型啟用快速模式也會[切換您的模型](#switching-models)，這本身會啟動新的快取。94啟用[快速模式](/docs/zh-TW/fast-mode)會新增一個請求標頭，該標頭是快取鍵的一部分，因此下一個請求讀取整個對話歷史記錄而沒有快取命中。這些未快取的輸入令牌按[快速模式費率](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)計費，這就是為什麼在會話開始時開啟它的成本比在長會話深處開啟它的成本要低。從非 Opus 模型啟用快速模式也會[切換您的模型](#switching-models)，這本身會啟動新的快取。

95 95 

96成本每個對話應用一次。在第一個快速模式轉換之後，Claude Code 會繼續發送標頭，並且只改變請求的速度設定，這不是快取鍵的一部分。關閉快速模式、[在速率限制後自動回退到標準速度](/zh-TW/fast-mode#handle-rate-limits)，以及稍後重新開啟它都會保持快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重新建立快取。96成本每個對話應用一次。在第一個快速模式轉換之後，Claude Code 會繼續發送標頭，並且只改變請求的速度設定，這不是快取鍵的一部分。關閉快速模式、[在速率限制後自動回退到標準速度](/docs/zh-TW/fast-mode#handle-rate-limits)，以及稍後重新開啟它都會保持快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重新建立快取。

97 97 

98<h3 id="connecting-or-disconnecting-an-mcp-server">98<h3 id="connecting-or-disconnecting-an-mcp-server">

99 連接或斷開 MCP 伺服器99 連接或斷開 MCP 伺服器

100</h3>100</h3>

101 101 

102工具定義位於系統提示層中，因此當請求之間的工具定義集合變更時，快取會失效。切換[顧問工具](/zh-TW/advisor)是例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保持快取的前綴完整。[MCP 伺服器](/zh-TW/mcp)變更是否執行此操作取決於其工具是否由[工具搜尋](/zh-TW/mcp#scale-with-mcp-tool-search)延遲或載入到前綴中：102工具定義位於系統提示層中，因此當請求之間的工具定義集合變更時，快取會失效。切換[顧問工具](/docs/zh-TW/advisor)是例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保持快取的前綴完整。[MCP 伺服器](/docs/zh-TW/mcp)變更是否執行此操作取決於其工具是否由[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)延遲或載入到前綴中：

103 103 

104* **延遲工具**，在支援的模型上為預設值：伺服器連接、斷開連接或變更其工具列表只會附加新內容，不會擾亂已快取的任何內容。104* **延遲工具**，在支援的模型上為預設值：伺服器連接、斷開連接或變更其工具列表只會附加新內容，不會擾亂已快取的任何內容。

105* **載入到前綴中的工具**：對它們的任何變更都會使快取失效。這發生在[工具搜尋不可用或已停用](/zh-TW/mcp#configure-tool-search)時，例如在 Google Cloud 的 Agent Platform 上或使用自訂 `ANTHROPIC_BASE_URL` 閘道時。它也發生在標記為 [`alwaysLoad`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器或工具上，以及由[基於閾值的載入](/zh-TW/mcp#configure-tool-search)保持在前面的定義上。105* **載入到前綴中的工具**：對它們的任何變更都會使快取失效。這發生在[工具搜尋不可用或已停用](/docs/zh-TW/mcp#configure-tool-search)時，例如在 Google Cloud 的 Agent Platform 上或使用自訂 `ANTHROPIC_BASE_URL` 閘道時。它也發生在標記為 [`alwaysLoad`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器或工具上，以及由[基於閾值的載入](/docs/zh-TW/mcp#configure-tool-search)保持在前面的定義上。

106 106 

107當工具載入到前綴中時，失效的最常見原因是伺服器在會話中期連接或斷開連接，這可能在沒有您採取任何操作的情況下發生：stdio 伺服器的進程退出、HTTP 會話過期，或伺服器[在暫時性故障後自動重新連接](/zh-TW/mcp#automatic-reconnection)。連接的伺服器也可以推送[動態工具更新](/zh-TW/mcp#dynamic-tool-updates)來變更其工具列表。107當工具載入到前綴中時，失效的最常見原因是伺服器在會話中期連接或斷開連接，這可能在沒有您採取任何操作的情況下發生：stdio 伺服器的進程退出、HTTP 會話過期，或伺服器[在暫時性故障後自動重新連接](/docs/zh-TW/mcp#automatic-reconnection)。連接的伺服器也可以推送[動態工具更新](/docs/zh-TW/mcp#dynamic-tool-updates)來變更其工具列表。

108 108 

109編輯您的 MCP 配置本身不會變更快取。新配置只有在重新啟動後才會生效，這是伺服器連接或斷開連接的時候。109編輯您的 MCP 配置本身不會變更快取。新配置只有在重新啟動後才會生效，這是伺服器連接或斷開連接的時候。

110 110 

112 啟用或停用外掛程式112 啟用或停用外掛程式

113</h3>113</h3>

114 114 

115[外掛程式](/zh-TW/plugins)捆綁多個元件類型，變更的成本取決於外掛程式提供的元件。Skills、commands、agents、hooks、LSP 伺服器、monitors 和 themes 永遠不會使快取失效：它們添加到請求的任何內容都會附加在現有對話之後，因此下一個請求為新內容付費，但仍然從快取中讀取它之前的所有內容。115[外掛程式](/docs/zh-TW/plugins)捆綁多個元件類型，變更的成本取決於外掛程式提供的元件。Skills、commands、agents、hooks、LSP 伺服器、monitors 和 themes 永遠不會使快取失效：它們添加到請求的任何內容都會附加在現有對話之後，因此下一個請求為新內容付費，但仍然從快取中讀取它之前的所有內容。

116 116 

117例外是提供 [MCP 伺服器](/zh-TW/plugins-reference#mcp-servers)的外掛程式。啟用或停用一個遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：當伺服器的工具被延遲時快取會保留，當它們載入到前綴中時下一個請求會重新讀取整個對話。117例外是提供 [MCP 伺服器](/docs/zh-TW/plugins-reference#mcp-servers)的外掛程式。啟用或停用一個遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：當伺服器的工具被延遲時快取會保留，當它們載入到前綴中時下一個請求會重新讀取整個對話。

118 118 

119外掛程式變更在您運行 [`/reload-plugins`](/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 或啟動新會話時應用。成本（無論是附加公告還是完整重新讀取）會在重新載入後的第一個轉換時顯示，而不是在您運行 `/plugin install`、`/plugin enable` 或 `/plugin disable` 時。{/* min-version: 2.1.163 */}自 v2.1.163 起，當重新載入會觸發完整重新讀取時，`/reload-plugins` 會顯示警告並不應用重新載入。傳遞 `--force` 以強制應用。119外掛程式變更在您運行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 或啟動新會話時應用。成本（無論是附加公告還是完整重新讀取）會在重新載入後的第一個轉換時顯示，而不是在您運行 `/plugin install`、`/plugin enable` 或 `/plugin disable` 時。{/* min-version: 2.1.163 */}自 v2.1.163 起，當重新載入會觸發完整重新讀取時，`/reload-plugins` 會顯示警告並不應用重新載入。傳遞 `--force` 以強制應用。

120 120 

121停用您在會話中較早啟用的外掛程式會恢復先前的請求形狀。如果該前綴仍在其[快取生命週期](#cache-lifetime)內，下一個請求會讀取較舊的快取項目，而不是重新建立。121停用您在會話中較早啟用的外掛程式會恢復先前的請求形狀。如果該前綴仍在其[快取生命週期](#cache-lifetime)內，下一個請求會讀取較舊的快取項目，而不是重新建立。

122 122 

124 拒絕整個工具124 拒絕整個工具

125</h3>125</h3>

126 126 

127添加裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/zh-TW/permissions#manage-permissions)會將該工具從 Claude 的上下文中完全移除。內建工具定義載入到系統提示層中，因此在會話中期添加或移除其中一個規則會使快取失效。無論您通過 `/permissions` 添加它還是通過[直接編輯設定檔](/zh-TW/settings#when-edits-take-effect)，變更都會在下一個轉換時生效。127添加裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)會將該工具從 Claude 的上下文中完全移除。內建工具定義載入到系統提示層中，因此在會話中期添加或移除其中一個規則會使快取失效。無論您通過 `/permissions` 添加它還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)，變更都會在下一個轉換時生效。

128 128 

129只有裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）才有此效果。匹配只有 MCP 工具的 glob（例如 `"mcp__*"`）會以相同方式移除這些工具，但當匹配的工具被[延遲](#connecting-or-disconnecting-an-mcp-server)時（預設值）會保持快取完整，因為延遲定義從未在快取的前綴中。作用域拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會改變 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保持前綴完整。129只有裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）才有此效果。匹配只有 MCP 工具的 glob（例如 `"mcp__*"`）會以相同方式移除這些工具，但當匹配的工具被[延遲](#connecting-or-disconnecting-an-mcp-server)時（預設值）會保持快取完整，因為延遲定義從未在快取的前綴中。作用域拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會改變 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保持前綴完整。

130 130 

131<h3 id="compacting-the-conversation">131<h3 id="compacting-the-conversation">

132 壓縮對話132 壓縮對話

133</h3>133</h3>

134 134 

135[壓縮](/zh-TW/context-window#what-survives-compaction)用摘要替換您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求有一個新的、更短的歷史記錄，不與舊的共享前綴。Claude Code 重複使用系統提示層並從磁碟重新載入專案上下文，只有在 CLAUDE.md 和記憶自會話開始以來未變更時才快取命中。135[壓縮](/docs/zh-TW/context-window#what-survives-compaction)用摘要替換您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求有一個新的、更短的歷史記錄，不與舊的共享前綴。Claude Code 重複使用系統提示層並從磁碟重新載入專案上下文，只有在 CLAUDE.md 和記憶自會話開始以來未變更時才快取命中。

136 136 

137為了生成摘要，Claude Code 發送一個一次性請求，其系統提示、工具和歷史記錄與您的對話相同，加上作為最終使用者訊息附加的摘要指令。因為它共享您的前綴，該請求讀取現有快取而不是重新處理完整歷史記錄。壓縮的大部分時間用於生成摘要，而不是快取未命中。隨後的轉換只為更短的摘要重新建立對話快取，因此壓縮後的轉換不是緩慢的部分。137為了生成摘要，Claude Code 發送一個一次性請求，其系統提示、工具和歷史記錄與您的對話相同，加上作為最終使用者訊息附加的摘要指令。因為它共享您的前綴，該請求讀取現有快取而不是重新處理完整歷史記錄。壓縮的大部分時間用於生成摘要，而不是快取未命中。隨後的轉換只為更短的摘要重新建立對話快取，因此壓縮後的轉換不是緩慢的部分。

138 138 

144 升級 Claude Code144 升級 Claude Code

145</h3>145</h3>

146 146 

147新的 Claude Code 版本通常會更新系統提示或工具定義，因此升級後的第一個請求會從頂部重新建立快取。[自動更新](/zh-TW/setup#auto-updates)在後台下載新版本，但在下次啟動時應用它們，從不在會話中期，因此您會看到這是重新啟動後的未快取第一個轉換，而不是會話期間的驚喜。設定 `DISABLE_AUTOUPDATER=1` 以控制何時應用升級。147新的 Claude Code 版本通常會更新系統提示或工具定義，因此升級後的第一個請求會從頂部重新建立快取。[自動更新](/docs/zh-TW/setup#auto-updates)在後台下載新版本，但在下次啟動時應用它們，從不在會話中期，因此您會看到這是重新啟動後的未快取第一個轉換，而不是會話期間的驚喜。設定 `DISABLE_AUTOUPDATER=1` 以控制何時應用升級。

148 148 

149<Note>149<Note>

150 在升級後[恢復會話](/zh-TW/sessions#resume-a-session)會重新處理整個對話歷史記錄而沒有快取命中，因為歷史記錄現在位於不同的系統提示後面。成本隨著恢復的對話有多長而擴展，因此回到長會話的第一個轉換可能是您發送的最昂貴的請求。150 在升級後[恢復會話](/docs/zh-TW/sessions#resume-a-session)會重新處理整個對話歷史記錄而沒有快取命中，因為歷史記錄現在位於不同的系統提示後面。成本隨著恢復的對話有多長而擴展，因此回到長會話的第一個轉換可能是您發送的最昂貴的請求。

151</Note>151</Note>

152 152 

153<h2 id="actions-that-keep-the-cache">153<h2 id="actions-that-keep-the-cache">

177 177 

178您的專案根目錄和使用者級別 CLAUDE.md 檔案在會話開始時讀取一次並保存在記憶中。在會話中期編輯它們不會使快取失效，但編輯也不會應用。Claude 繼續使用在會話開始時加載的版本。新內容在下一個 `/clear`、`/compact` 或重新啟動時加載。178您的專案根目錄和使用者級別 CLAUDE.md 檔案在會話開始時讀取一次並保存在記憶中。在會話中期編輯它們不會使快取失效，但編輯也不會應用。Claude 繼續使用在會話開始時加載的版本。新內容在下一個 `/clear`、`/compact` 或重新啟動時加載。

179 179 

180[子目錄中的嵌套 CLAUDE.md 檔案](/zh-TW/memory)和[帶有 `paths:` frontmatter 的規則](/zh-TW/memory#path-specific-rules)稍後加載，當 Claude 首次讀取匹配檔案時。在它加載之前編輯一個確實會生效。加載後，內容是對話歷史記錄的一部分，因此會話中期的編輯不會追溯變更它。180[子目錄中的嵌套 CLAUDE.md 檔案](/docs/zh-TW/memory)和[帶有 `paths:` frontmatter 的規則](/docs/zh-TW/memory#path-specific-rules)稍後加載，當 Claude 首次讀取匹配檔案時。在它加載之前編輯一個確實會生效。加載後，內容是對話歷史記錄的一部分，因此會話中期的編輯不會追溯變更它。

181 181 

182<h3 id="changing-output-style">182<h3 id="changing-output-style">

183 變更輸出風格183 變更輸出風格

184</h3>184</h3>

185 185 

186[輸出風格](/zh-TW/output-styles)是系統提示的一部分，Claude Code 在會話開始時讀取一次。通過 `/config` 或 `outputStyle` 設定在會話中期變更它不會使快取失效，但變更也不會應用。Claude 繼續使用在會話開始時加載的風格。新風格在下一個 `/clear` 或重新啟動時加載。186[輸出風格](/docs/zh-TW/output-styles)是系統提示的一部分，Claude Code 在會話開始時讀取一次。通過 `/config` 或 `outputStyle` 設定在會話中期變更它不會使快取失效，但變更也不會應用。Claude 繼續使用在會話開始時加載的風格。新風格在下一個 `/clear` 或重新啟動時加載。

187 187 

188<h3 id="changing-permission-mode">188<h3 id="changing-permission-mode">

189 變更權限模式189 變更權限模式

190</h3>190</h3>

191 191 

192在[權限模式](/zh-TW/permission-modes)之間切換，例如從預設切換到接受編輯，不會變更系統提示或工具定義，因此模式變更是快取安全的。例外是使用 [`opusplan`](/zh-TW/model-config#opusplan-model-setting) 模型設定的 Plan Mode，它在進入或離開 Plan Mode 時在 Opus 和 Sonnet 之間切換模型。這使模式切換成為[模型切換](#switching-models)。192在[權限模式](/docs/zh-TW/permission-modes)之間切換，例如從預設切換到接受編輯，不會變更系統提示或工具定義，因此模式變更是快取安全的。例外是使用 [`opusplan`](/docs/zh-TW/model-config#opusplan-model-setting) 模型設定的 Plan Mode，它在進入或離開 Plan Mode 時在 Opus 和 Sonnet 之間切換模型。這使模式切換成為[模型切換](#switching-models)。

193 193 

194<h3 id="invoking-skills-and-commands">194<h3 id="invoking-skills-and-commands">

195 調用技能和命令195 調用技能和命令

196</h3>196</h3>

197 197 

198[技能](/zh-TW/skills)和[命令](/zh-TW/commands)在調用點將其指令注入為使用者訊息。對話中較早的任何內容都不會變更。198[技能](/docs/zh-TW/skills)和[命令](/docs/zh-TW/commands)在調用點將其指令注入為使用者訊息。對話中較早的任何內容都不會變更。

199 199 

200<h3 id="running-/recap">200<h3 id="running-/recap">

201 運行 `/recap`201 運行 `/recap`

202</h3>202</h3>

203 203 

204[`/recap`](/zh-TW/interactive-mode#session-recap) 生成一個摘要以在您的終端中顯示。與 `/compact` 不同，它將摘要附加為命令輸出而不是替換您的訊息歷史記錄，因此快取的前綴保持完整。204[`/recap`](/docs/zh-TW/interactive-mode#session-recap) 生成一個摘要以在您的終端中顯示。與 `/compact` 不同，它將摘要附加為命令輸出而不是替換您的訊息歷史記錄，因此快取的前綴保持完整。

205 205 

206<h3 id="rewinding-the-conversation">206<h3 id="rewinding-the-conversation">

207 重新開始對話207 重新開始對話

208</h3>208</h3>

209 209 

210[`/rewind`](/zh-TW/checkpointing) 將您的對話截斷回到較早的轉換。剩餘的歷史記錄是快取在該點建立時的相同內容，系統提示和專案上下文層未變更，因此下一個請求命中較早的快取條目。自那時以來的每個轉換都通過該前綴讀取，即使原始轉換比 TTL 更久遠，也保持條目溫暖。210[`/rewind`](/docs/zh-TW/checkpointing) 將您的對話截斷回到較早的轉換。剩餘的歷史記錄是快取在該點建立時的相同內容，系統提示和專案上下文層未變更，因此下一個請求命中較早的快取條目。自那時以來的每個轉換都通過該前綴讀取，即使原始轉換比 TTL 更久遠，也保持條目溫暖。

211 211 

212恢復檔案檢查點與對話一起對快取沒有單獨的影響。檔案內容只有在 Claude 讀取它們時才進入上下文，與[編輯您的儲存庫中的檔案](#editing-files-in-your-repository)相同。212恢復檔案檢查點與對話一起對快取沒有單獨的影響。檔案內容只有在 Claude 讀取它們時才進入上下文，與[編輯您的儲存庫中的檔案](#editing-files-in-your-repository)相同。

213 213 

239 覆蓋 TTL239 覆蓋 TTL

240</h3>240</h3>

241 241 

242設定 `FORCE_PROMPT_CACHING_5M=1` 以強制五分鐘 TTL，無論身份驗證如何。當您調試快取行為、比較兩個 TTL 或覆蓋在[受管設定](/zh-TW/settings#settings-files)中設定的 `ENABLE_PROMPT_CACHING_1H` 時，這很有用。242設定 `FORCE_PROMPT_CACHING_5M=1` 以強制五分鐘 TTL，無論身份驗證如何。當您調試快取行為、比較兩個 TTL 或覆蓋在[受管設定](/docs/zh-TW/settings#settings-files)中設定的 `ENABLE_PROMPT_CACHING_1H` 時，這很有用。

243 243 

244<h2 id="cache-scope">244<h2 id="cache-scope">

245 快取範圍245 快取範圍

249 249 

250您在同一目錄中並行運行的會話建立匹配的前綴並讀取彼此的快取。順序會話只有在啟動時的 git 狀態快照匹配時才共享前綴，因為系統提示也捕獲分支和最近的提交。250您在同一目錄中並行運行的會話建立匹配的前綴並讀取彼此的快取。順序會話只有在啟動時的 git 狀態快照匹配時才共享前綴，因為系統提示也捕獲分支和最近的提交。

251 251 

252基礎 API 快取更廣泛。快取在組織之間隔離，在某些提供商上，[在組織內的工作區之間隔離](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#cache-storage-and-sharing)。在這些邊界內，任何兩個具有相同模型和前綴的請求讀取相同的快取。對於運行自動化流程艦隊的 Agent SDK 呼叫者，請參閱[改進跨使用者和機器的 prompt caching](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)以抑制系統提示的按機器部分並跨機器共享快取。252基礎 API 快取更廣泛。快取在組織之間隔離，在某些提供商上，[在組織內的工作區之間隔離](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#cache-storage-and-sharing)。在這些邊界內，任何兩個具有相同模型和前綴的請求讀取相同的快取。對於運行自動化流程艦隊的 Agent SDK 呼叫者，請參閱[改進跨使用者和機器的 prompt caching](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)以抑制系統提示的按機器部分並跨機器共享快取。

253 253 

254<h2 id="check-cache-performance">254<h2 id="check-cache-performance">

255 檢查快取效能255 檢查快取效能

256</h2>256</h2>

257 257 

258快取效能顯示為 API 在每個回應上報告的兩個令牌計數。最直接的方式是觀看它們實時是[狀態行指令碼](/zh-TW/statusline)，它讀取 `current_usage` 物件：258快取效能顯示為 API 在每個回應上報告的兩個令牌計數。最直接的方式是觀看它們實時是[狀態行指令碼](/docs/zh-TW/statusline)，它讀取 `current_usage` 物件：

259 259 

260| 欄位 | 含義 |260| 欄位 | 含義 |

261| ----------------------------- | ------------------------------- |261| ----------------------------- | ------------------------------- |

264 264 

265高讀取與建立比率意味著快取工作良好。如果建立在轉換之間保持高位，您的前綴中有些東西在變更。[使快取失效的操作](#actions-that-invalidate-the-cache)部分列出了常見原因。265高讀取與建立比率意味著快取工作良好。如果建立在轉換之間保持高位，您的前綴中有些東西在變更。[使快取失效的操作](#actions-that-invalidate-the-cache)部分列出了常見原因。

266 266 

267為了在整個組織中獲得可見性，OpenTelemetry 匯出器報告每個使用者和會話的快取讀取和建立令牌。請參閱[監控使用](/zh-TW/monitoring-usage)以了解指標和事件屬性參考。267為了在整個組織中獲得可見性，OpenTelemetry 匯出器報告每個使用者和會話的快取讀取和建立令牌。請參閱[監控使用](/docs/zh-TW/monitoring-usage)以了解指標和事件屬性參考。

268 268 

269<h2 id="subagents-and-the-cache">269<h2 id="subagents-and-the-cache">

270 子代理和快取270 子代理和快取

271</h2>271</h2>

272 272 

273[子代理](/zh-TW/sub-agents)開始自己的對話，具有自己的系統提示和工具集，與父代分開。它建立自己的快取，在第一次呼叫時沒有快取命中，並在自己的轉換中預熱。子代理使用五分鐘 TTL，即使在訂閱上，因為自動一小時 TTL 適用於主對話。273[子代理](/docs/zh-TW/sub-agents)開始自己的對話，具有自己的系統提示和工具集，與父代分開。它建立自己的快取，在第一次呼叫時沒有快取命中，並在自己的轉換中預熱。子代理使用五分鐘 TTL，即使在訂閱上，因為自動一小時 TTL 適用於主對話。

274 274 

275父代的快取不受影響。從父代的角度來看，子代理的呼叫和結果附加到對話，保留父代的前綴完整。275父代的快取不受影響。從父代的角度來看，子代理的呼叫和結果附加到對話，保留父代的前綴完整。

276 276 

277[分支](/zh-TW/sub-agents#fork-the-current-conversation)相比之下，完全繼承父代的系統提示、工具和對話歷史記錄，因此其第一個請求讀取父代的快取。[壓縮對話](#compacting-the-conversation)中描述的壓縮摘要呼叫使用相同的前綴共享方法。277[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)相比之下，完全繼承父代的系統提示、工具和對話歷史記錄，因此其第一個請求讀取父代的快取。[壓縮對話](#compacting-the-conversation)中描述的壓縮摘要呼叫使用相同的前綴共享方法。

278 278 

279<h2 id="disable-prompt-caching">279<h2 id="disable-prompt-caching">

280 禁用 prompt caching280 禁用 prompt caching

290| `DISABLE_PROMPT_CACHING_OPUS` | 僅為 Opus 禁用 |290| `DISABLE_PROMPT_CACHING_OPUS` | 僅為 Opus 禁用 |

291| `DISABLE_PROMPT_CACHING_FABLE` | 僅為 Fable 禁用 |291| `DISABLE_PROMPT_CACHING_FABLE` | 僅為 Fable 禁用 |

292 292 

293要在整個組織中設定快取策略，請將這些或[TTL 變數](#cache-lifetime)中的任何一個放在[受管設定](/zh-TW/settings#settings-files)的 `env` 區塊中。為了正常使用，請保持快取啟用。293要在整個組織中設定快取策略，請將這些或[TTL 變數](#cache-lifetime)中的任何一個放在[受管設定](/docs/zh-TW/settings#settings-files)的 `env` 區塊中。為了正常使用，請保持快取啟用。

294 294 

295<h2 id="related-resources">295<h2 id="related-resources">

296 相關資源296 相關資源

297</h2>297</h2>

298 298 

299* [從建立 Claude Code 中學到的課程：Prompt caching 就是一切](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything)：Plan Mode、延遲工具加載和壓縮的設計基本原理299* [從建立 Claude Code 中學到的課程：Prompt caching 就是一切](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything)：Plan Mode、延遲工具加載和壓縮的設計基本原理

300* [探索上下文視窗](/zh-TW/context-window)：什麼加載到上下文以及何時加載300* [探索上下文視窗](/docs/zh-TW/context-window)：什麼加載到上下文以及何時加載

301* [減少令牌使用](/zh-TW/costs#reduce-token-usage)：超越快取的策略，用於管理上下文大小301* [減少令牌使用](/docs/zh-TW/costs#reduce-token-usage)：超越快取的策略，用於管理上下文大小

302* [追蹤和減少成本](/zh-TW/agent-sdk/cost-tracking)：Agent SDK 呼叫者的快取令牌追蹤和 TTL 配置302* [追蹤和減少成本](/docs/zh-TW/agent-sdk/cost-tracking)：Agent SDK 呼叫者的快取令牌追蹤和 TTL 配置

303* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)：基礎 API 機制、中斷點和定價303* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)：基礎 API 機制、中斷點和定價