8 8
9本页列出 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 `command not found` 或设置期间的 TLS 失败），请参阅[排查安装和登录问题](/docs/zh-CN/troubleshoot-install)。9本页列出 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 `command not found` 或设置期间的 TLS 失败），请参阅[排查安装和登录问题](/docs/zh-CN/troubleshoot-install)。
10 10
11除了[包装器和 IDE 错误](#wrapper-and-ide-errors)（由启动程序打印而不是 Claude Code 本身打印）外，这些错误和恢复命令适用于 CLI、[桌面应用](/docs/zh-CN/desktop)和[云会话](/docs/zh-CN/claude-code-on-the-web)，因为这三个都包装相同的 Claude Code CLI。对于其他表面特定的问题，请参阅该表面页面上的故障排除部分。11除了[包装器和 IDE 错误](#wrapper-and-ide-errors)（由启动程序打印而不是 Claude Code 本身打印）外，这些错误和恢复命令适用于 CLI、[桌面应用](/docs/zh-CN/desktop)和[云端会话](/docs/zh-CN/claude-code-on-the-web)，因为这三个都包装相同的 Claude Code CLI。对于其他特定于使用入口的问题，请参阅该使用入口页面上的故障排除部分。
12 12
13<Note>13<Note>
14 Claude Code 调用 Claude API 来获取模型响应，因此大多数运行时错误映射到底层 API 错误代码。本页介绍每个错误在 Claude Code 中的含义以及如何恢复。有关原始 HTTP 状态代码定义，请参阅 [Claude Platform 错误参考](https://platform.claude.com/docs/en/api/errors)。14 Claude Code 调用 Claude API 来获取模型响应，因此大多数运行时错误映射到底层 API 错误代码。本页介绍每个错误在 Claude Code 中的含义以及如何恢复。有关原始 HTTP 状态代码定义，请参阅 [Claude Platform 错误参考](https://platform.claude.com/docs/en/api/errors)。
75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |
76| `Remote Control stopped — the app running this session is signed out of Claude` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |76| `Remote Control stopped — the app running this session is signed out of Claude` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |
77| `Couldn't verify your organization's policy for remote control` | [Troubleshoot Remote Control](/docs/zh-CN/remote-control#couldnt-verify-your-organizations-policy-for-remote-control) |77| `Couldn't verify your organization's policy for remote control` | [Troubleshoot Remote Control](/docs/zh-CN/remote-control#couldnt-verify-your-organizations-policy-for-remote-control) |
78| `Remote Control is disabled by your organization's policy` | [Troubleshoot Remote Control](/docs/zh-CN/remote-control#remote-control-is-disabled-by-your-organizations-policy) |
79| `Remote Control was turned off by your organization's policy` | [Troubleshoot Remote Control](/docs/zh-CN/remote-control#remote-control-was-turned-off-by-your-organizations-policy) |
78| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |80| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |
81| `Failed to authenticate: OAuth token revoked` | [身份验证](#oauth-token-revoked-or-expired) |
82| `Your account does not have access to Claude. Please login again or contact your administrator.` | [身份验证](#oauth-token-revoked-or-expired) |
79| `API Error: 401 Invalid authentication credentials` | [身份验证](#api-error-401-invalid-authentication-credentials) |83| `API Error: 401 Invalid authentication credentials` | [身份验证](#api-error-401-invalid-authentication-credentials) |
80| `Login expired · Please run /login` | [身份验证](#login-expired) |84| `Login expired · Please run /login` | [身份验证](#login-expired) |
81| `Failed to start OAuth callback server` | [身份验证](#failed-to-start-oauth-callback-server) |85| `Failed to start OAuth callback server` | [身份验证](#failed-to-start-oauth-callback-server) |
164| `Can't switch to the default model` | [请求错误](#cant-switch-to-the-default-model) |168| `Can't switch to the default model` | [请求错误](#cant-switch-to-the-default-model) |
165| `Model switch ... blocked by a PreModelSwitch hook` | [请求错误](#model-switch-was-blocked-by-a-premodelswitch-hook) |169| `Model switch ... blocked by a PreModelSwitch hook` | [请求错误](#model-switch-was-blocked-by-a-premodelswitch-hook) |
166| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [请求错误](#couldnt-save-it-as-your-default) |170| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [请求错误](#couldnt-save-it-as-your-default) |
171| `is less capable than the current main model` / `Advisor will not activate on the main model` / `cannot advise` | [请求错误](#advisor-is-less-capable-than-the-current-main-model) |
167| `thinking.type.enabled is not supported for this model` | [请求错误](#thinking-type-enabled-is-not-supported-for-this-model) |172| `thinking.type.enabled is not supported for this model` | [请求错误](#thinking-type-enabled-is-not-supported-for-this-model) |
168| `Effort '<level>' isn't available with thinking turned off on this model` | [请求错误](#effort-isnt-available-with-thinking-turned-off) |173| `Effort '<level>' isn't available with thinking turned off on this model` | [请求错误](#effort-isnt-available-with-thinking-turned-off) |
169| `effort '<level>' is not supported when thinking is disabled` | [请求错误](#effort-isnt-available-with-thinking-turned-off) |174| `effort '<level>' is not supported when thinking is disabled` | [请求错误](#effort-isnt-available-with-thinking-turned-off) |
186| `The connection dropped while downloading the update` | [安装错误](#the-connection-dropped-while-downloading-the-update) |191| `The connection dropped while downloading the update` | [安装错误](#the-connection-dropped-while-downloading-the-update) |
187| `Download timed out: exceeded the total deadline` | [安装错误](#the-connection-dropped-while-downloading-the-update) |192| `Download timed out: exceeded the total deadline` | [安装错误](#the-connection-dropped-while-downloading-the-update) |
188| `--bg and --print conflict` | [命令行错误](#conflict-between-bg-and-print) |193| `--bg and --print conflict` | [命令行错误](#conflict-between-bg-and-print) |
194| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [命令行错误](#conflict-between-a-system-prompt-flag-and-its-file-form) |
189| `Cloud sessions cannot be created from a --restricted session` | [命令行错误](#cloud-sessions-cannot-be-created-from-a-restricted-session) |195| `Cloud sessions cannot be created from a --restricted session` | [命令行错误](#cloud-sessions-cannot-be-created-from-a-restricted-session) |
190| `Cloud sessions are disabled by your organization's policy` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |196| `Cloud sessions are disabled by your organization's policy` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |
191| `Couldn't verify your organization's policy for cloud sessions` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |197| `Couldn't verify your organization's policy for cloud sessions` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |
203| `Could not read Claude Code config` | [命令行错误](#could-not-read-claude-code-config) |209| `Could not read Claude Code config` | [命令行错误](#could-not-read-claude-code-config) |
204| `Could not import <server>: <reason>` | [命令行错误](#could-not-import-a-server-from-claude-desktop) |210| `Could not import <server>: <reason>` | [命令行错误](#could-not-import-a-server-from-claude-desktop) |
205| `Cannot add MCP server to scope: managed` | [命令行错误](#cannot-add-mcp-server-to-the-managed-scope) |211| `Cannot add MCP server to scope: managed` | [命令行错误](#cannot-add-mcp-server-to-the-managed-scope) |
212| `Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide` | [命令行错误](#cannot-add-mcp-server-when-managed-settings-allow-only-plugin-servers) |
206| `is Anthropic-hosted and doesn't support local OAuth` | [命令行错误](#anthropic-hosted-and-doesnt-support-local-oauth) |213| `is Anthropic-hosted and doesn't support local OAuth` | [命令行错误](#anthropic-hosted-and-doesnt-support-local-oauth) |
207| `Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes` | [命令行错误](#cant-read-mcp-json) |214| `Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes` | [命令行错误](#cant-read-mcp-json) |
208| `MCP server "<name>" was not saved to` / `was not removed from` | [命令行错误](#mcp-server-was-not-saved-or-removed) |215| `MCP server "<name>" was not saved to` / `was not removed from` | [命令行错误](#mcp-server-was-not-saved-or-removed) |
215| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [命令行错误](#security-review-fails-without-origin-head) |222| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [命令行错误](#security-review-fails-without-origin-head) |
216| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [命令行错误](#security-review-fails-without-origin-head) |223| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [命令行错误](#security-review-fails-without-origin-head) |
217| `Input must be provided either through stdin or as a prompt argument when using --print` | [命令行错误](#input-must-be-provided-when-using-print) |224| `Input must be provided either through stdin or as a prompt argument when using --print` | [命令行错误](#input-must-be-provided-when-using-print) |
225| `Claude Code can't read the keyboard here: stdin is not a terminal` | [命令行错误](#claude-code-cant-read-the-keyboard-here) |
218| `Error: Input contained only whitespace` | [命令行错误](#input-contained-only-whitespace) |226| `Error: Input contained only whitespace` | [命令行错误](#input-contained-only-whitespace) |
219| `Blank prompt — the message was only whitespace, so nothing was sent to the model.` | [命令行错误](#input-contained-only-whitespace) |227| `Blank prompt — the message was only whitespace, so nothing was sent to the model.` | [命令行错误](#input-contained-only-whitespace) |
220| `Error: stream-json input carried over 256M characters with no newline` | [命令行错误](#stream-json-input-carried-over-256m-characters-with-no-newline) |228| `Error: stream-json input carried over 256M characters with no newline` | [命令行错误](#stream-json-input-carried-over-256m-characters-with-no-newline) |
227| `The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead` | [命令行错误](#the-github-app-preflight-failed-transiently) |235| `The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead` | [命令行错误](#the-github-app-preflight-failed-transiently) |
228| `Not uploading this working tree` with `the upload cannot follow that setting` | [命令行错误](#the-repository-upload-cant-follow-a-git-setting) |236| `Not uploading this working tree` with `the upload cannot follow that setting` | [命令行错误](#the-repository-upload-cant-follow-a-git-setting) |
229| `GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud` | [命令行错误](#github-isnt-connected-to-your-claude-account) |237| `GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud` | [命令行错误](#github-isnt-connected-to-your-claude-account) |
238| `Your GitHub organization has an IP allowlist that is blocking Claude` | [命令行错误](#a-github-organization-policy-is-blocking-claude) |
239| `Your GitHub organization requires single sign-on` | [命令行错误](#a-github-organization-policy-is-blocking-claude) |
240| `Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude` | [命令行错误](#a-github-organization-policy-is-blocking-claude) |
230| `Single sign-on authorization needed` | [命令行错误](#single-sign-on-authorization-needed) |241| `Single sign-on authorization needed` | [命令行错误](#single-sign-on-authorization-needed) |
231| `Failed to resume the conversation` | [命令行错误](#failed-to-resume-the-conversation) |242| `Failed to resume the conversation` | [命令行错误](#failed-to-resume-the-conversation) |
232| `No conversation found with session ID: <session-id>` | [命令行错误](#no-conversation-found-with-the-session-id) |243| `No conversation found with session ID: <session-id>` | [命令行错误](#no-conversation-found-with-the-session-id) |
240| `Skill usage reports are not available on this connection.` | [命令行错误](#skill-usage-reports-are-not-available-on-this-connection) |251| `Skill usage reports are not available on this connection.` | [命令行错误](#skill-usage-reports-are-not-available-on-this-connection) |
241| `Custom output styles can't be selected over Remote Control or from a relayed message` | [命令行错误](#custom-output-styles-cant-be-selected-over-remote-control) |252| `Custom output styles can't be selected over Remote Control or from a relayed message` | [命令行错误](#custom-output-styles-cant-be-selected-over-remote-control) |
242| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [命令行错误](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |253| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [命令行错误](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |
254| `/recap only runs when you ask for it yourself in this session` | [命令行错误](#recap-only-runs-when-you-ask-for-it-yourself) |
243| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 错误](#plugin-eval-is-currently-in-early-access) |255| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 错误](#plugin-eval-is-currently-in-early-access) |
244| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 错误](#marketplace-is-registered-from-an-untrusted-source) |256| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 错误](#marketplace-is-registered-from-an-untrusted-source) |
245| `Claude Code refuses the marketplace name "<name>"` | [Plugin 错误](#claude-code-refuses-the-marketplace-name) |257| `Claude Code refuses the marketplace name "<name>"` | [Plugin 错误](#claude-code-refuses-the-marketplace-name) |
246| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [Plugin 错误](#claude-code-refuses-the-marketplace-name) |258| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [Plugin 错误](#claude-code-refuses-the-marketplace-name) |
247| `Marketplace "<name>" is already added from a different source` | [Plugin 错误](#marketplace-is-already-added-from-a-different-source) |259| `Marketplace "<name>" is already added from a different source` | [Plugin 错误](#marketplace-is-already-added-from-a-different-source) |
248| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin 错误](#marketplace-name-is-another-spelling-of-a-reserved-name) |260| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin 错误](#marketplace-name-is-another-spelling-of-a-reserved-name) |
261| `Marketplace "<name>" is added but ignored` | [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting#marketplace-is-added-but-ignored) |
262| `Marketplace "<name>" is registered but was refused (see the debug log)` | [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting#marketplace-is-added-but-ignored) |
249| `references ${user_config.*} in a shell-form command` | [Plugin 错误](#plugin-command-references-user-config) |263| `references ${user_config.*} in a shell-form command` | [Plugin 错误](#plugin-command-references-user-config) |
250| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Plugin 错误](#plugin-command-references-user-config) |264| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Plugin 错误](#plugin-command-references-user-config) |
251| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin 错误](#plugin-command-references-user-config) |265| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin 错误](#plugin-command-references-user-config) |
252| `Plugin archive integrity check failed` | [Plugin 错误](#plugin-archive-integrity-check-failed) |266| `Plugin archive integrity check failed` | [Plugin 错误](#plugin-archive-integrity-check-failed) |
267| `An npm plugin source must name a registry package` | [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting#an-npm-plugin-source-must-name-a-registry-package) |
268| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |
253| `path escapes plugin directory` | [Plugin 错误](#path-escapes-plugin-directory) |269| `path escapes plugin directory` | [Plugin 错误](#path-escapes-plugin-directory) |
254| `path could not be checked` | [Plugin 错误](#path-could-not-be-checked) |270| `path could not be checked` | [Plugin 错误](#path-could-not-be-checked) |
255| `its marketplace entry path does not stay inside the marketplace directory` | [Plugin 错误](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |271| `its marketplace entry path does not stay inside the marketplace directory` | [Plugin 错误](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |
260| `"<plugin>" was not uninstalled: it is still switched on in <file>` | [Plugin 错误](#plugin-was-not-uninstalled) |276| `"<plugin>" was not uninstalled: it is still switched on in <file>` | [Plugin 错误](#plugin-was-not-uninstalled) |
261| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [Plugin 错误](#plugin-was-not-uninstalled) |277| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [Plugin 错误](#plugin-was-not-uninstalled) |
262| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read) |278| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read) |
279| `Error: No such tool available: <tool name>` | [工具错误](#no-such-tool-available) |
263| `would be spawned with zero tools — refusing` | [工具错误](#agent-would-be-spawned-with-zero-tools) |280| `would be spawned with zero tools — refusing` | [工具错误](#agent-would-be-spawned-with-zero-tools) |
264| `File is covered by a Read deny rule in your permission settings` | [工具错误](#file-is-covered-by-a-read-deny-rule) |281| `File is covered by a Read deny rule in your permission settings` | [工具错误](#file-is-covered-by-a-read-deny-rule) |
265| `cannot contain null bytes (\0)` | [工具错误](#path-cannot-contain-null-bytes) |282| `cannot contain null bytes (\0)` | [工具错误](#path-cannot-contain-null-bytes) |
287| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [工具错误](#disk-quota-or-temp-filesystem-is-full) |304| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [工具错误](#disk-quota-or-temp-filesystem-is-full) |
288| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [工具错误](#the-source-file-is-not-valid-utf-8-text) |305| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [工具错误](#the-source-file-is-not-valid-utf-8-text) |
289| `the source file has the replacement character U+FFFD` | [工具错误](#the-source-file-is-not-valid-utf-8-text) |306| `the source file has the replacement character U+FFFD` | [工具错误](#the-source-file-is-not-valid-utf-8-text) |
307| `Not published: that file is on a network share` | [工具错误](#not-published-that-file-is-on-a-network-share) |
290| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [工具错误](#reading-a-local-file-from-outside-the-connected-folders) |308| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [工具错误](#reading-a-local-file-from-outside-the-connected-folders) |
291| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [工具错误](#reading-a-local-file-from-outside-the-connected-folders) |309| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [工具错误](#reading-a-local-file-from-outside-the-connected-folders) |
292| `WebFetch cannot fetch localhost or other hostnames without a dot` | [工具错误](#webfetch-cannot-fetch-localhost) |310| `WebFetch cannot fetch localhost or other hostnames without a dot` | [工具错误](#webfetch-cannot-fetch-localhost) |
342| `Unable to read managed policy settings` | [配置警告](#unable-to-read-managed-policy-settings) |360| `Unable to read managed policy settings` | [配置警告](#unable-to-read-managed-policy-settings) |
343| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [配置警告](#otelheadershelper-failed) |361| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [配置警告](#otelheadershelper-failed) |
344| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [配置警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |362| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [配置警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |
363| `API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name` | [配置警告](#anthropic-foundry-resource-must-be-a-foundry-resource-name) |
345| `headersHelper not run — this workspace has no persisted trust` | [配置警告](#headershelper-not-run) |364| `headersHelper not run — this workspace has no persisted trust` | [配置警告](#headershelper-not-run) |
346| `Invalid permission rule "..." was skipped: Malformed Tool(content) rule` | [配置警告](#malformed-tool-content-rule) |365| `Invalid permission rule "..." was skipped: Malformed Tool(content) rule` | [配置警告](#malformed-tool-content-rule) |
347| `... is not matched by file permission checks` | [配置警告](#is-not-matched-by-file-permission-checks) |366| `... is not matched by file permission checks` | [配置警告](#is-not-matched-by-file-permission-checks) |
360Claude Code 重试这些故障：379Claude Code 重试这些故障：
361 380
362* 在 Claude 响应开始流式传输之前到达的服务器错误、过载响应和请求超时。381* 在 Claude 响应开始流式传输之前到达的服务器错误、过载响应和请求超时。
363* 连接断开。当连接在请求过程中途断开，且 Claude 尚未完成其响应的任何部分（包括其思考过程）时，Claude Code 会使用相同的退避重新发送请求，转换继续进行，即使某些文本已经开始流式传输。当连接在 Claude 完成思考之后但在开始任何文本或工具调用之前断开时，Claude Code 改为快速连续重新发送请求最多两次，如果连接在该点继续断开，则以 `Connection lost before a response was produced` 结束转换。382* 在 Claude 完成思考之后、但在开始任何文本或工具调用之前到达的服务器错误或过载响应。Claude Code 会在该点重试服务器错误最多两次。在 v2.1.284 之前，Claude Code 会在该点以该错误结束轮次。
364* Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 `Connection lost while your computer was asleep`，如果转换在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 `Your computer went to sleep before a response was produced`。383* 连接断开。当连接在请求过程中途断开，且 Claude 尚未完成其响应的任何部分（包括其思考过程）时，Claude Code 会使用相同的退避重新发送请求，轮次继续进行，即使某些文本已经开始流式传输。当连接在 Claude 完成思考之后但在开始任何文本或工具调用之前断开时，Claude Code 改为快速连续重新发送请求最多两次，如果连接在该点继续断开，则以 `Connection lost before a response was produced` 结束轮次。
365* 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接并最多重新发送一次请求，不在上述 10 次尝试预算之外。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 `The response stalled before a response was produced` 结束转换。384* Claude Code 检测到的连接在您的计算机进入睡眠状态时在请求过程中途被破坏。Claude Code 将其计为上述规则下的断开连接；一旦重试标签命名了具体原因，它会读作 `Connection lost while your computer was asleep`，如果轮次在 Claude 完成思考之后但在任何文本或工具调用之前结束，消息会读作 `Your computer went to sleep before a response was produced`。
366* 流式请求 API 从未用响应头回答，在 [first-byte deadline runs](/docs/zh-CN/network-config#streaming-idle-watchdogs) 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 [No response from API](#no-response-from-api) 结束转换。在其他连接上，请求等待 `API_TIMEOUT_MS`。当您设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，一次重试上限不适用。385* 停滞的响应流，当响应头已到达但 Claude 响应的任何部分都未到达，或当 Claude 完成思考但尚未开始任何文本或工具调用时：Claude Code 中止停滞连接并最多重新发送一次请求，不计入上述 10 次尝试预算。如果响应在 Claude 完成思考之后但在任何文本或工具调用之前第二次停滞，Claude Code 以 `The response stalled before a response was produced` 结束轮次。
386* 流式请求 API 从未用响应头回答，在 [first-byte deadline runs](/docs/zh-CN/network-config#streaming-idle-watchdogs) 的连接上：Claude Code 在截止时间中止它，并在重试预算内每个模型请求最多重新发送一次，然后如果该尝试也未得到回答，则以 [No response from API](#no-response-from-api) 结束轮次。在其他连接上，请求等待 `API_TIMEOUT_MS`。当您设置 `CLAUDE_CODE_RETRY_WATCHDOG` 时，一次重试上限不适用。
367* 临时 429 节流，但不是网关的支出限制 `429`，这不是节流；请参阅 [Spend limit reached](#spend-limit-reached)。387* 临时 429 节流，但不是网关的支出限制 `429`，这不是节流；请参阅 [Spend limit reached](#spend-limit-reached)。
368 * 当您使用 claude.ai 订阅登录时，这包括不携带您计划配额头的 429 节流。在 v2.1.199 之前，Claude Code 仅对 API 密钥和企业登录重试这些节流。388 * 当您使用 claude.ai 订阅登录时，这包括不携带您套餐配额头的 429 节流。在 v2.1.199 之前，Claude Code 仅对 API 密钥和企业登录重试这些节流。
369* 因为输入加上 `max_tokens` 超过上下文限制而被拒绝的请求。以相同方式重新发送它会以相同方式失败，所以 Claude Code 使用减少的 `max_tokens` 重试，并在两种情况下停止重试并改为压缩：389* 因为输入加上 `max_tokens` 超过上下文限制而被拒绝的请求。以相同方式重新发送它会以相同方式失败，所以 Claude Code 使用减少的 `max_tokens` 重试，并在两种情况下停止重试并改为压缩：
370 * 当没有减少可以适应时，例如当对话本身几乎填满上下文窗口时。390 * 当没有减少可以适应时，例如当对话本身几乎填满上下文窗口时。
371 * 当重试无法进一步缩小 `max_tokens` 时。在 v2.1.218 之前，Claude Code 可以重新发送仍然不适应的减少请求，例如当扩展思考预算超过剩余上下文时，直到重试预算用尽。391 * 当重试无法进一步缩小 `max_tokens` 时。在 v2.1.218 之前，Claude Code 可以重新发送仍然不适应的减少请求，例如当扩展思考预算超过剩余上下文时，直到重试预算用尽。
372* [Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 上过期或缺失的 Google Cloud 凭证，或在您的机器上加载失败的 AWS 凭证。Claude Code 丢弃其缓存的凭证并重试最多两次，然后报告错误以便您可以立即重新身份验证，如 [Could not load AWS or Google Cloud credentials](#could-not-load-aws-or-google-cloud-credentials) 下所述。在 v2.1.228 之前，Claude Code 通过完整重试预算重试失败的 Google Cloud 凭证，然后显示错误。392* [Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 上过期或缺失的 Google Cloud 凭据，或在您的机器上加载失败的 AWS 凭据。Claude Code 丢弃其缓存的凭据并重试最多两次，然后报告错误以便您可以立即重新身份验证，如 [Could not load AWS or Google Cloud credentials](#could-not-load-aws-or-google-cloud-credentials) 下所述。在 v2.1.228 之前，Claude Code 通过完整重试预算重试失败的 Google Cloud 凭据，然后显示错误。
373* 来自 Anthropic API 的 `401` 或 `403`，直接或通过 [LLM gateway](/docs/zh-CN/llm-gateway)，而 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本提供凭证。Claude Code 重新运行脚本并使用其新输出重试，在完整重试预算内。当脚本本身在重新运行时失败时，Claude Code 改为显示 [Your apiKeyHelper script is failing](#your-apikeyhelper-script-is-failing)。393* 来自 Anthropic API 的 `401` 或 `403`，直接或通过 [LLM gateway](/docs/zh-CN/llm-gateway)，而 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本提供凭据。Claude Code 重新运行脚本并使用其新输出重试，在完整重试预算内。当脚本本身在重新运行时失败时，Claude Code 改为显示 [Your apiKeyHelper script is failing](#your-apikeyhelper-script-is-failing)。
374 394
375在 v2.1.227 之前，`Connection lost before a response was produced` 读作 `Connection closed while thinking, before producing a response`，`The response stalled before a response was produced` 读作 `Response stalled while thinking, before producing a response`。395在 v2.1.227 之前，`Connection lost before a response was produced` 读作 `Connection closed while thinking, before producing a response`，`The response stalled before a response was produced` 读作 `Response stalled while thinking, before producing a response`。
376 396
377Claude Code 不重试这些故障：397Claude Code 不重试这些故障：
378 398
379* TLS 证书验证失败，例如 TLS 检查代理、缺失的 `NODE_EXTRA_CA_CERTS` 包或过期的证书。Claude Code 在第一次尝试时报告错误，以便您可以立即修复证书设置；请参阅 [SSL certificate errors](#ssl-certificate-errors)。Claude Code 仍然重试瞬时 TLS 条件，例如握手超时。在 v2.1.199 之前，Claude Code 通过完整重试预算重试证书失败，然后显示错误。399* TLS 证书验证失败，例如 TLS 检查代理、缺失的 `NODE_EXTRA_CA_CERTS` 包或过期的证书。Claude Code 在第一次尝试时报告错误，以便您可以立即修复证书设置；请参阅 [SSL certificate errors](#ssl-certificate-errors)。Claude Code 仍然重试瞬时 TLS 条件，例如握手超时。在 v2.1.199 之前，Claude Code 通过完整重试预算重试证书失败，然后显示错误。
380* 服务器错误、断开连接或停滞流在 Claude 完成文本块或工具调用之后到达，或在完成思考之后开始一个但在完成响应之前。Claude Code 不重新运行请求，因为这可能会执行相同的工具调用两次。它保留 Claude 完成的内容，运行 Claude 完成的任何工具调用，并从其结果继续转换。对于您在交互式会话和非交互式会话中看到的内容，请阅读 [The response above may be incomplete](#the-response-above-may-be-incomplete)。在 v2.1.199 之前，当服务器错误在流中途到达时，Claude Code 丢弃部分输出并将整个转换报告为错误。400* 服务器错误、断开连接或停滞流在 Claude 完成文本块或工具调用之后到达，或在完成思考之后开始一个但在完成响应之前。Claude Code 不重新运行请求，因为这可能会执行相同的工具调用两次。它保留 Claude 完成的内容，运行 Claude 完成的任何工具调用，并从其结果继续轮次。对于您在交互式会话和非交互式会话中看到的内容，请阅读 [The response above may be incomplete](#the-response-above-may-be-incomplete)。在 v2.1.199 之前，当服务器错误在流中途到达时，Claude Code 丢弃部分输出并将整个轮次报告为错误。
381* 在 Claude 完成响应之后到达的故障：无需重试任何内容，所以 Claude Code 保留完整响应并正常结束转换。401* 在 Claude 完成响应之后到达的故障：无需重试任何内容，所以 Claude Code 保留完整响应并正常结束轮次。
382* [Amazon Bedrock 流式响应具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因为重写响应的网关或代理会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。402* [Amazon Bedrock 流式响应具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因为重写响应的网关或代理会以相同方式重写重试。需要 Claude Code v2.1.208 或更高版本。
383* 失败的流式请求的非流式重试获得成功状态但 [body 中没有 Claude API 消息](#api-returned-an-empty-or-malformed-response)。Claude Code 以该错误结束转换。403* 失败的流式请求的非流式重试获得成功状态但 [body 中没有 Claude API 消息](#api-returned-an-empty-or-malformed-response)。Claude Code 以该错误结束轮次。
384* 您的组织的策略检查拒绝的请求，其表现为携带拒绝消息的 `API Error:` 行。您的组织管理员使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude Enterprise 功能）设置检查，消息以他们配置的说明结尾，或默认告诉您联系他们。Claude Code 不会将拒绝的请求重新发送到相同模型或 [fallback model](/docs/zh-CN/model-config#fallback-model-chains)，因为拒绝涉及请求的内容而不是模型。在 v2.1.239 之前，Claude Code 可以重新发送拒绝的请求，不流式传输或在配置的备用模型上，然后向您显示拒绝。404* 您的组织的策略检查拒绝的请求，其表现为携带拒绝消息的 `API Error:` 行。您的组织管理员使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude Enterprise 功能）设置检查，消息以他们配置的说明结尾，或默认告诉您联系他们。Claude Code 不会将拒绝的请求重新发送到相同模型或 [备用模型](/docs/zh-CN/model-config#fallback-model-chains)，因为拒绝涉及请求的内容而不是模型。在 v2.1.239 之前，Claude Code 可以重新发送拒绝的请求，不流式传输或在配置的备用模型上，然后向您显示拒绝。
385 405
386<h3 id="what-you-see-while-claude-code-retries-or-waits">406<h3 id="what-you-see-while-claude-code-retries-or-waits">
387 Claude Code 重试或等待时您看到的内容407 Claude Code 重试或等待时您看到的内容
393 413
394如果在请求仍然待处理时响应流上 20 秒内没有数据到达，微调器显示 `Waiting for API response · will retry in … · check your network`，然后任何重试都尚未开始。请求尚未失败：倒计时运行到 Claude Code 中止停滞连接的点。中止后，您看到的内容取决于响应已进行的距离：414如果在请求仍然待处理时响应流上 20 秒内没有数据到达，微调器显示 `Waiting for API response · will retry in … · check your network`，然后任何重试都尚未开始。请求尚未失败：倒计时运行到 Claude Code 中止停滞连接的点。中止后，您看到的内容取决于响应已进行的距离：
395 415
396* 在 Claude 完成文本块或工具调用之前，或在完成思考之后开始一个，Claude Code 重试请求或以错误结束转换。[Automatic retries](#automatic-retries) 说明它重试哪些停滞以及多少次。416* 在 Claude 完成文本块或工具调用之前，或在完成思考之后开始一个，Claude Code 重试请求或以错误结束轮次。[Automatic retries](#automatic-retries) 说明它重试哪些停滞以及多少次。
397* 在 Claude 完成文本块或工具调用之后，或在完成思考之后开始一个，但在 Claude 完成响应之前，Claude Code 保留 Claude 完成的内容，从 Claude 完成的任何工具调用继续转换，并显示 [The response above may be incomplete](#the-response-above-may-be-incomplete)。在非交互式会话中，以及对于任何会话中的子代理响应，Claude Code 可能首先提示 Claude 继续响应；该条目说明何时执行以及何时您仍然在那里看到通知。417* 在 Claude 完成文本块或工具调用之后，或在完成思考之后开始一个，但在 Claude 完成响应之前，Claude Code 保留 Claude 完成的内容，从 Claude 完成的任何工具调用继续轮次，并显示 [The response above may be incomplete](#the-response-above-may-be-incomplete)。在非交互式会话中，以及对于任何会话中的子代理响应，Claude Code 可能首先提示 Claude 继续响应；该条目说明何时执行以及何时您仍然在那里看到通知。
398* 在 Claude 完成响应之后，Claude Code 正常结束转换。418* 在 Claude 完成响应之后，Claude Code 正常结束轮次。
399 419
400一旦数据恢复或重试成功，横幅会自动清除。如果它在每次尝试时重新出现，将其视为 [network issue](#unable-to-connect-to-api)。在 v2.1.185 之前，横幅在 10 秒后出现，措辞不同。420一旦数据恢复或重试成功，横幅会自动清除。如果它在每次尝试时重新出现，将其视为 [network issue](#unable-to-connect-to-api)。在 v2.1.185 之前，横幅在 10 秒后出现，措辞不同。
401 421
402当 Claude 咨询 [advisor](/docs/zh-CN/advisor) 时，横幅在 90 秒无数据后出现，而不是 20 秒，因为长时间的顾问审查可以发送超过 20 秒的任何内容。在 v2.1.214 之前，20 秒阈值也适用于顾问调用，所以横幅在顾问审查期间出现，即使没有任何问题。422当 Claude 咨询 [advisor](/docs/zh-CN/advisor) 时，横幅在 90 秒无数据后出现，而不是 20 秒，因为长时间的顾问审查可能在远超 20 秒的时间内不发送任何数据。在 v2.1.214 之前，20 秒阈值也适用于顾问调用，所以横幅在顾问审查期间出现，即使没有任何问题。
403 423
404<h3 id="tune-retry-behavior">424<h3 id="tune-retry-behavior">
405 调整重试行为425 调整重试行为
418 服务器错误438 服务器错误
419</h2>439</h2>
420 440
421这些错误中的大多数来自推理提供商：Anthropic API 上的 Anthropic 服务，以及 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自定义网关上该提供商端点后面的服务。[Auto mode 无法确定操作的安全性](#auto-mode-cannot-determine-the-safety-of-an-action)和[Agent 因 API 错误而提前终止](#agent-terminated-early-due-to-an-api-error)也涵盖了您这一方的原因，例如无法调用分类器模型的 Amazon Bedrock 账户或达到使用限制的子代理。441这些错误中的大多数来自推理提供商：Anthropic API 上的 Anthropic 服务，以及 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自定义网关上该提供商端点后面的服务。[自动模式无法确定操作的安全性](#auto-mode-cannot-determine-the-safety-of-an-action)和[Agent 因 API 错误而提前终止](#agent-terminated-early-due-to-an-api-error)也涵盖了您这一方的原因，例如无法调用分类器模型的 Amazon Bedrock 账户或达到用量限制的子代理。
422 442
423<h3 id="api-error-500-internal-server-error">443<h3 id="api-error-500-internal-server-error">
424 API Error: 500 Internal server error444 API Error: 500 Internal server error
432 452
433尾部句子指出了检查服务健康状况的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会指出该提供商的服务状态。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。453尾部句子指出了检查服务健康状况的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会指出该提供商的服务状态。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。
434 454
435API 本身的 5xx 表示 API 内部出现了意外故障。它不是由您的提示、设置或账户引起的。455API 本身的 5xx 表示 API 内部出现了意外故障。它不是由您的提示词、设置或账户引起的。
436 456
437当代理、负载均衡器或网关用 HTML 错误页面回复时，消息显示状态代码和页面的标题，例如 `API Error: 502 Bad Gateway`。对于没有标题的页面，消息显示状态代码及其标准名称。在 v2.1.281 之前，当页面有标题时状态代码被丢弃，当页面没有标题时打印页面的原始标记。457当代理、负载均衡器或网关用 HTML 错误页面回复时，消息显示状态代码和页面的标题，例如 `API Error: 502 Bad Gateway`。对于没有标题的页面，消息显示状态代码及其标准名称。在 v2.1.281 之前，当页面有标题时状态代码被丢弃，当页面没有标题时打印页面的原始标记。
438 458
439**应该做什么：**459**应该做什么：**
440 460
441* 检查 [status.claude.com](https://status.claude.com) 或消息中指出的提供商状态页面，查看是否有活跃事件461* 检查 [status.claude.com](https://status.claude.com) 或消息中指出的提供商状态页面，查看是否有活跃事件
442* 等待一分钟，然后再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示，您可以输入 `try again` 而不是粘贴整个内容。462* 等待一分钟，然后再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示词，您可以输入 `try again` 而不是粘贴整个内容。
443* 如果错误持续存在且没有发布事件，请运行 `/feedback` 以便 Anthropic 可以使用您的请求详情进行调查。如果您的环境中 `/feedback` 不可用，请参阅[报告错误](#report-an-error)。463* 如果错误持续存在且没有发布事件，请运行 `/feedback` 以便 Anthropic 可以使用您的请求详情进行调查。如果您的环境中 `/feedback` 不可用，请参阅[报告错误](#report-an-error)。
444 464
445<h3 id="api-error-repeated-529-overloaded-errors">465<h3 id="api-error-repeated-529-overloaded-errors">
454 474
455尾部句子因提供商而异，方式与上面的 500 错误相同。475尾部句子因提供商而异，方式与上面的 500 错误相同。
456 476
457529 不是您的使用限制，也不会计入您的配额。477529 不是您的用量限制，也不会计入您的配额。
458 478
459**应该做什么：**479**应该做什么：**
460 480
474Request timed out494Request timed out
475```495```
476 496
477这可能在高负载期间或模型生成非常大的响应时发生。默认请求超时为 10 分钟。497这可能在高负载期间或模型生成非常大的响应时发生。默认请求超时时间为 10 分钟。
478 498
479**应该做什么：**499**应该做什么：**
480 500
486 No response from API506 No response from API
487</h3>507</h3>
488 508
489Claude Code 发送了流式请求，API 在第一个字节的截止时间内没有返回响应头，因此 Claude Code 中止了请求，而不是等待完整的 `API_TIMEOUT_MS` 请求超时（默认为 10 分钟）。Claude Code 最多再发送一次请求，如果[重试预算](#tune-retry-behavior)允许的话。当重试也没有得到回复时，该轮次以此消息结束，该消息显示每次尝试等待了多长时间。当您设置 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) 时，一次重试的上限不适用，Claude Code 在[调整重试行为](#tune-retry-behavior)中描述的预算下重试。509Claude Code 发送了流式请求，API 在第一个字节的截止时间内没有返回响应头，因此 Claude Code 中止了请求，而不是等待完整的 `API_TIMEOUT_MS` 请求超时时间（默认为 10 分钟）。Claude Code 最多再发送一次请求，如果[重试预算](#tune-retry-behavior)允许的话。当重试也没有得到回复时，该轮次以此消息结束，该消息显示每次尝试等待了多长时间。当您设置 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) 时，一次重试的上限不适用，Claude Code 在[调整重试行为](#tune-retry-behavior)中描述的预算下重试。
490 510
491```text theme={null}511```text theme={null}
492API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.512API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.
494 514
495Claude Code 分别为第一次尝试的等待响应头和重试的等待设置：515Claude Code 分别为第一次尝试的等待响应头和重试的等待设置：
496 516
497* **第一次尝试**：当您将其设置为 1 或更多时使用 [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/zh-CN/env-vars)，限制在 10 秒到 30 分钟之间。否则 Claude Code 使用[流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs)中列出的字节级监视程序超时，因此改变该超时的变量也会改变此等待。无论哪种方式，Claude Code 为请求体的每 32KB 添加一秒。517* **第一次尝试**：当您将其设置为 1 或更多时使用 [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/zh-CN/env-vars)，限制在 10 秒到 30 分钟之间。否则 Claude Code 使用[流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs)中列出的字节级监视程序超时时间，因此改变该超时时间的变量也会改变此等待。无论哪种方式，Claude Code 为请求体的每 32KB 添加一秒。
498* **重试**：比 `API_TIMEOUT_MS` 少一秒，默认略低于 10 分钟，以便重试可以超过保持响应直到生成完成的代理或网关。在 Amazon Bedrock 上，重试使用与第一次尝试相同的截止时间，消息显示一个持续时间而不是两个。518* **重试**：比 `API_TIMEOUT_MS` 少一秒，默认略低于 10 分钟，以便重试可以超过保持响应直到生成完成的代理或网关。在 Amazon Bedrock 上，重试使用与第一次尝试相同的截止时间，消息显示一个持续时间而不是两个。
499 519
500两个等待都不超过正 `API_TIMEOUT_MS` 少一秒，正 `API_TIMEOUT_MS` 低于 11 秒会关闭截止时间。字节级监视程序仅在响应头到达后才开始，因此在此之后停止发送字节的响应遵循[停滞流规则](#automatic-retries)而不是此截止时间。520两个等待都不超过正 `API_TIMEOUT_MS` 少一秒，正 `API_TIMEOUT_MS` 低于 11 秒会关闭截止时间。字节级监视程序仅在响应头到达后才开始，因此在此之后停止发送字节的响应遵循[停滞流规则](#automatic-retries)而不是此截止时间。
501 521
502**应该做什么：**522**应该做什么：**
503 523
504* 再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示，您可以输入 `try again` 而不是粘贴整个内容。524* 再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示词，您可以输入 `try again` 而不是粘贴整个内容。
505* 如果重复出现，将其视为[网络或代理问题](#unable-to-connect-to-api)。525* 如果重复出现，将其视为[网络或代理问题](#unable-to-connect-to-api)。
506* 如果您网络上的代理或网关保持响应直到完成，请提高 `API_TIMEOUT_MS` 以便重试等待更长时间。在 Amazon Bedrock 上，也提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`。526* 如果您网络上的代理或网关保持响应直到完成，请提高 `API_TIMEOUT_MS` 以便重试等待更长时间。在 Amazon Bedrock 上，也提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`。
507* 如果第一次尝试持续超时，然后重试成功，请提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` 以便第一次尝试也等待足够长的时间。527* 如果第一次尝试持续超时，然后重试成功，请提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` 以便第一次尝试也等待足够长的时间。
508 528
509在 v2.1.242 之前，Claude Code 在未回复的流式请求失败之前等待完整的 `API_TIMEOUT_MS` 请求超时（默认为 10 分钟）。在 v2.1.261 之前，重试等待与第一次尝试相同的截止时间，消息没有显示持续时间。529在 v2.1.242 之前，Claude Code 在未回复的流式请求失败之前等待完整的 `API_TIMEOUT_MS` 请求超时时间（默认为 10 分钟）。在 v2.1.261 之前，重试等待与第一次尝试相同的截止时间，消息没有显示持续时间。
510 530
511<h3 id="the-response-above-may-be-incomplete">531<h3 id="the-response-above-may-be-incomplete">
512 The response above may be incomplete532 The response above may be incomplete
528* `Your computer went to sleep mid-response`：Claude Code 检测到您的计算机在响应流式传输时进入睡眠状态。一旦您的计算机唤醒，Claude Code 会将连接视为断开并停止从中读取。548* `Your computer went to sleep mid-response`：Claude Code 检测到您的计算机在响应流式传输时进入睡眠状态。一旦您的计算机唤醒，Claude Code 会将连接视为断开并停止从中读取。
529* `Part of the response never arrived`：流事件在 API 和 Claude Code 之间被丢弃，因此后来的事件引用了从未到达的内容。在 v2.1.281 之前，此情况以 `API Error: Content block not found` 结束轮次。549* `Part of the response never arrived`：流事件在 API 和 Claude Code 之间被丢弃，因此后来的事件引用了从未到达的内容。在 v2.1.281 之前，此情况以 `API Error: Content block not found` 结束轮次。
530* `The response stream was malformed`：为已完成的内容块到达了事件，或事件到达时已损坏。损坏的事件是指其数据不是有效 JSON、其内容缺失或其内容与事件类型不匹配的事件。在 v2.1.284 之前，当具有无效 JSON 的事件在 Claude 完成其思考、文本块或工具调用后到达时，解析器的原始错误（例如以 `API Error: JSON Parse error` 开头的错误）出现。550* `The response stream was malformed`：为已完成的内容块到达了事件，或事件到达时已损坏。损坏的事件是指其数据不是有效 JSON、其内容缺失或其内容与事件类型不匹配的事件。在 v2.1.284 之前，当具有无效 JSON 的事件在 Claude 完成其思考、文本块或工具调用后到达时，解析器的原始错误（例如以 `API Error: JSON Parse error` 开头的错误）出现。
531* `The response stopped arriving`：连接保持打开但停止传递数据，因此流式空闲监视程序中止了它。在 v2.1.222 之前，Claude Code 也可能在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到达的[网关](/docs/zh-CN/gateways)连接上报告此故障，同时服务器的保活 ping 仍在到达，因为它只在那里计算已解析的响应事件；升级会停止这些虚假超时。通过提供商基础 URL（如 `ANTHROPIC_BEDROCK_BASE_URL`）到达的网关不被字节监视程序包装；请参阅[流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs)。551* `The response stopped arriving`：连接保持打开但停止传递数据，因此流式空闲监视程序中止了它。在 v2.1.222 之前，Claude Code 也可能在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到达的[网关](/docs/zh-CN/gateways)连接上报告此故障，同时服务器的保活 ping 仍在到达，因为它只在那里计算已解析的响应事件；升级会在这些路由上停止这些虚假超时。通过提供商基础 URL（如 `ANTHROPIC_BEDROCK_BASE_URL`）到达的网关不被字节监视程序包装；请参阅[流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs)。
532 552
533在 v2.1.227 之前，`Connection lost mid-response` 读作 `Connection closed mid-response`，`The response stopped arriving` 读作 `Response stalled mid-stream`。553在 v2.1.227 之前，`Connection lost mid-response` 读作 `Connection closed mid-response`，`The response stopped arriving` 读作 `Response stalled mid-stream`。
534 554
541 561
542* 在响应的早期，Claude Code 要么重试故障，要么以不同的错误结束轮次。请参阅[自动重试](#automatic-retries)。562* 在响应的早期，Claude Code 要么重试故障，要么以不同的错误结束轮次。请参阅[自动重试](#automatic-retries)。
543* 当这些故障之一在 Claude 完成响应后到达时，Claude Code 保留完整响应并正常结束轮次，没有此通知。在 v2.1.222 之前，当连接在响应完成后断开或停滞时，Claude Code 显示此通知，并将轮次报告为错误，即使响应是完整的。563* 当这些故障之一在 Claude 完成响应后到达时，Claude Code 保留完整响应并正常结束轮次，没有此通知。在 v2.1.222 之前，当连接在响应完成后断开或停滞时，Claude Code 显示此通知，并将轮次报告为错误，即使响应是完整的。
544* 在[非交互式会话](/docs/zh-CN/headless)中，例如 `-p` 运行、[Agent SDK](/docs/zh-CN/agent-sdk/overview) 运行或[云会话](/docs/zh-CN/claude-code-on-the-web)，当截断响应在主对话中且包含文本但没有工具调用时，您不必自己发送 `continue`：Claude Code 保留部分输出并提示 Claude 从停止的地方继续，最多连续三次。您只有在 Claude Code 用完这些继续后才会看到此通知。在 v2.1.246 之前，Claude Code 在第一次截断时以此通知结束非交互式轮次。564* 在[非交互式会话](/docs/zh-CN/headless)中，例如 `-p` 运行、[Agent SDK](/docs/zh-CN/agent-sdk/overview) 运行或[云端会话](/docs/zh-CN/claude-code-on-the-web)，当截断响应在主对话中且包含文本但没有工具调用时，您不必自己发送 `continue`：Claude Code 保留部分输出并提示 Claude 从停止的地方继续，最多连续三次。您只有在 Claude Code 用完这些继续后才会看到此通知。在 v2.1.246 之前，Claude Code 在第一次截断时以此通知结束非交互式轮次。
545* 在[子代理](/docs/zh-CN/sub-agents#api-errors-in-subagents)中，无论会话是否交互式：当其截断响应包含文本但没有工具调用时，Claude Code 提示子代理继续。通知仅在这些继续用完后才成为子代理的最后一条消息。在 v2.1.257 之前，子代理在第一次截断时显示此通知。565* 在[子代理](/docs/zh-CN/sub-agents#api-errors-in-subagents)中，无论会话是否交互式：当其截断响应包含文本但没有工具调用时，Claude Code 提示子代理继续。通知仅在这些继续用完后才成为子代理的最后一条消息。在 v2.1.257 之前，子代理在第一次截断时显示此通知。
546 566
547**应该做什么：**567**应该做什么：**
548 568
549* 在交互式会话中，阅读屏幕上剩余的响应：Claude Code 保留 Claude 在错误前完成的每个块，但当轮次结束时丢弃中断的最后块，因此最后的句子或工具调用可能会丢失。回复 `continue` 以让 Claude 从其最后完成的块继续。569* 在交互式会话中，阅读屏幕上剩余的响应：Claude Code 保留 Claude 在错误前完成的每个块，但当轮次结束时丢弃中断的最后块，因此最后的句子或工具调用可能会丢失。回复 `continue` 以让 Claude 从其最后完成的块继续。
550* 在[非交互式模式](/docs/zh-CN/headless)（`-p`）中：570* 在[非交互模式](/docs/zh-CN/headless)（`-p`）中：
551 * 使用默认文本输出，Claude Code 打印它仍然从轮次早期保留的最后完成的文本块，然后是此消息。当它不保留任何内容时，Claude Code 仅打印此消息，例如因为 Claude Code 在轮次中间压缩了对话并清除了该文本。在 v2.1.219 之前，Claude Code 仅在 `-p` 文本输出中打印此消息并丢弃它已经生成的响应。571 * 使用默认文本输出，Claude Code 打印它仍然从轮次早期保留的最后完成的文本块，然后是此消息。当它不保留任何内容时，Claude Code 仅打印此消息，例如因为 Claude Code 在轮次中间压缩了对话并清除了该文本。在 v2.1.219 之前，Claude Code 仅在 `-p` 文本输出中打印此消息并丢弃它已经生成的响应。
552 * 使用 `--output-format json` 或 `stream-json`，Claude Code 在 `result` 字段中报告此消息。572 * 使用 `--output-format json` 或 `stream-json`，Claude Code 在 `result` 字段中报告此消息。
553 * 一旦连接稳定，要继续该轮次，请恢复会话并按照[继续对话](/docs/zh-CN/headless#continue-conversations)中的说明发送 `continue`。573 * 一旦连接稳定，要继续该轮次，请恢复会话并按照[继续对话](/docs/zh-CN/headless#continue-conversations)中的说明发送 `continue`。
556 Auto mode cannot determine the safety of an action576 Auto mode cannot determine the safety of an action
557</h3>577</h3>
558 578
559[auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 使用的模型无法对操作进行分类，因此 auto mode 没有自动批准该操作。您看到的消息取决于分类器如何失败。579[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)使用的模型无法对操作进行分类，因此自动模式没有自动批准该操作。您看到的消息取决于分类器如何失败。
560 580
561对工作目录内的读取、搜索和编辑会跳过分类器，因此它们在所有这些情况下都继续工作。581对工作目录内的读取、搜索和编辑会跳过分类器，因此它们在所有这些情况下都继续工作。
562 582
572 592
573**应该做什么：**593**应该做什么：**
574 594
575* 几秒后重试；Claude 看到相同的消息，通常会自动重试。暂时故障与 [auto mode 资格](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)无关；您不需要更改设置595* 几秒后重试；Claude 看到相同的消息，通常会自动重试。暂时故障与[自动模式资格](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)无关；您不需要更改设置
576* 如果重试持续失败，继续进行只读任务，稍后回到被阻止的操作596* 如果重试持续失败，继续进行只读任务，稍后回到被阻止的操作
577* 在 Amazon Bedrock 上，如果消息在每次重试时返回，请检查您的账户是否可以调用它指出的模型：对于标准 Amazon Bedrock 模型，确认您的 [IAM 策略](/docs/zh-CN/amazon-bedrock#iam-configuration)允许调用它；对于 Mantle 模型 ID，[联系您的 AWS 账户团队](/docs/zh-CN/amazon-bedrock#mantle-endpoint-errors)597* 在 Amazon Bedrock 上，如果消息在每次重试时返回，请检查您的账户是否可以调用它指出的模型：对于标准 Amazon Bedrock 模型，确认您的 [IAM 策略](/docs/zh-CN/amazon-bedrock#iam-configuration)允许调用它；对于 Mantle 模型 ID，[联系您的 AWS 账户团队](/docs/zh-CN/amazon-bedrock#mantle-endpoint-errors)
578 598
579当分类器请求失败是因为您的 OAuth 令牌过期或被另一个会话轮换时，Claude Code 刷新令牌并重试请求一次，因此例行令牌过期不会显示为此消息。在 v2.1.216 之前，过期或轮换的令牌会导致每个分类器请求失败，auto mode 会拒绝每个检查的操作，直到令牌被刷新。599当分类器请求失败是因为您的 OAuth 令牌过期或被另一个会话轮换时，Claude Code 刷新令牌并重试请求一次，因此常规的令牌过期不会显示为此消息。在 v2.1.216 之前，过期或轮换的令牌会导致每个分类器请求失败，自动模式会以此消息拒绝每个检查的操作，直到令牌被刷新。
580 600
581当分类器返回无法解析的响应时：601当分类器返回无法解析的响应时：
582 602
595Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details615Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details
596```616```
597 617
598Claude Code 拒绝该操作，但告诉 Claude 这不是对该操作不安全的判断，并继续进行其他任务而不是重试。这些拒绝不计入 [auto mode 的暂停阈值](/docs/zh-CN/permission-modes#when-auto-mode-falls-back)。在[非交互式](/docs/zh-CN/headless) `-p` 运行中，Claude Code 不会停止运行。Claude 接收的内容取决于它请求操作的位置：618Claude Code 拒绝该操作，但告诉 Claude 这不是对该操作不安全的判断，并继续进行其他任务而不是重试。这些拒绝不计入[自动模式的暂停阈值](/docs/zh-CN/permission-modes#when-auto-mode-falls-back)。在[非交互式](/docs/zh-CN/headless) `-p` 运行中，Claude Code 不会停止运行。Claude 接收的内容取决于它请求操作的位置：
599 619
600* 对于 `-p` 运行中没有 `--input-format stream-json` 的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)，Claude Code 返回包含 `Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode` 的错误结果620* 对于 `-p` 运行中没有 `--input-format stream-json` 的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)，Claude Code 返回包含 `Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode` 的错误结果
601* 在其他地方，包括交互式会话和 `-p` 运行的主对话，Claude Code 将该拒绝返回给 Claude621* 在其他地方，包括交互式会话和 `-p` 运行的主对话，Claude Code 将该拒绝返回给 Claude
602 622
603在 v2.1.225 之前，Claude Code 将这些拒绝计入暂停阈值，并返回与真正分类器块相同的拒绝消息。623在 v2.1.225 之前，Claude Code 将这些拒绝计入暂停阈值，并返回与真正分类器阻止相同的拒绝消息。
604 624
605**应该做什么：**625**应该做什么：**
606 626
607* 这不是对您的操作的决定。您对话中已有的内容在 auto mode 将对话发送给分类器时触发了 API 上的安全过滤器627* 这不是对您的操作的决定。您对话中已有的内容在自动模式将对话发送给分类器时触发了 API 上的安全过滤器
608* 重试无法帮助；相同的对话内容将再次触发过滤器628* 重试无法帮助；相同的对话内容将再次触发过滤器
609* 在交互式会话中，切换到不同的[权限模式](/docs/zh-CN/permission-modes)，以便您可以在提示时批准该操作629* 在交互式会话中，切换到不同的[权限模式](/docs/zh-CN/permission-modes)，以便您可以在提示时批准该操作
610* 开始一个新对话，不包含触发内容630* 开始一个新对话，不包含触发内容
617 637
618操作发生的情况取决于 Claude 请求它的位置：638操作发生的情况取决于 Claude 请求它的位置：
619 639
620* 在交互式会话中，auto mode 回退到该操作的正常权限提示，以便您可以手动批准或拒绝它640* 在交互式会话中，自动模式回退到该操作的正常权限提示，以便您可以手动批准或拒绝它
621* 对于[非交互式](/docs/zh-CN/headless) `-p` 运行中没有 `--input-format stream-json` 的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)，Claude Code 返回包含 `Agent aborted: auto mode classifier transcript exceeded context window in headless mode` 的错误结果，运行继续641* 对于[非交互式](/docs/zh-CN/headless) `-p` 运行中没有 `--input-format stream-json` 的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)，Claude Code 返回包含 `Agent aborted: auto mode classifier transcript exceeded context window in headless mode` 的错误结果，运行继续
622* 在 `-p` 运行中的其他地方，没有 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，没有提示可以回退到，因此操作不运行，运行继续642* 在 `-p` 运行中的其他地方，没有 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，没有提示可以回退到，因此操作不运行，运行继续
623 643
630 The server returned no safety verdict650 The server returned no safety verdict
631</h3>651</h3>
632 652
633在[服务器端分类器审查](/docs/zh-CN/permission-modes#server-side-classifier-review)下，当服务器对操作没有给出判决时，auto mode 拒绝该操作。当 Claude Code 可以确定一个类别时，拒绝会在括号中指出一个类别，例如 `(timed out)`：653在[服务器端分类器审查](/docs/zh-CN/permission-modes#server-side-classifier-review)下，当服务器对操作没有给出判决时，自动模式拒绝该操作。当 Claude Code 可以确定一个类别时，拒绝会在括号中指出一个类别，例如 `(timed out)`：
634 654
635```text theme={null}655```text theme={null}
636The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.656The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.
638 658
639消息的其余部分告诉 Claude 一次重试是否可以帮助。在某些这些拒绝之前，Claude Code 会等待，以便 Claude 的下一次尝试不会立即跟随。在交互式会话中等待期间，微调器显示 `Auto mode check unavailable` 和倒计时，按 `Esc` 会中断轮次。659消息的其余部分告诉 Claude 一次重试是否可以帮助。在某些这些拒绝之前，Claude Code 会等待，以便 Claude 的下一次尝试不会立即跟随。在交互式会话中等待期间，微调器显示 `Auto mode check unavailable` 和倒计时，按 `Esc` 会中断轮次。
640 660
641在连续十个响应都没有判决后，auto mode 停止轮次：661在连续十个响应都没有判决后，自动模式停止轮次：
642 662
643```text theme={null}663```text theme={null}
644Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.664Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.
646 666
647停止消息在每种会话中出现在不同的位置：667停止消息在每种会话中出现在不同的位置：
648 668
649* 在交互式会话中，消息作为警告出现在记录中，轮次结束669* 在交互式会话中，消息作为警告出现在会话记录中，轮次结束
650* 在[非交互式](/docs/zh-CN/headless) `-p` 运行中，运行结束并报告执行错误。使用默认文本输出，消息在 stderr 上打印。670* 在[非交互式](/docs/zh-CN/headless) `-p` 运行中，运行结束并报告执行错误。使用默认文本输出，消息在 stderr 上打印。
651* 当[子代理](/docs/zh-CN/sub-agents)达到限制时，子代理在完成之前停止，Claude 接收它生成的任何内容，并附带 auto mode 停止它的说明671* 当[子代理](/docs/zh-CN/sub-agents)达到限制时，子代理在完成之前停止，Claude 接收它生成的任何内容，并附带自动模式停止它的说明
652 672
653**应该做什么：**673**应该做什么：**
654 674
655* 发送另一条消息以让 Claude 重试。响应计数重新开始。675* 发送另一条消息以让 Claude 重试。响应计数重新开始。
656* 如果停止重复且您的请求通过[LLM 网关或代理](/docs/zh-CN/llm-gateway)，检查它是否截断流式响应或重写它们。[服务器端分类器审查](/docs/zh-CN/permission-modes#server-side-classifier-review)说明哪种网关行为会导致拒绝，[网关兼容性指南](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)列出了要保持不变的内容。676* 如果停止重复且您的请求通过[LLM 网关或代理](/docs/zh-CN/llm-gateway)，检查它是否截断流式响应或重写它们。[服务器端分类器审查](/docs/zh-CN/permission-modes#server-side-classifier-review)说明哪种网关行为会导致拒绝，[网关兼容性指南](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)列出了要保持不变的内容。
657* 在启动 Claude Code 之前设置 `CLAUDE_CODE_AUTO_MODE_SERVER=0` 以改用其自己的分类器请求。在 v2.1.281 之前，Claude Code 在直接连接到 Anthropic API 时不读取该变量。677* 在启动 Claude Code 之前设置 `CLAUDE_CODE_AUTO_MODE_SERVER=0` 以改用其自己的分类器请求。在 v2.1.281 之前，Claude Code 在直接连接到 Anthropic API 时不读取该变量。
658* 要自己批准操作，请改为[切换出 auto mode](/docs/zh-CN/permission-modes#switch-permission-modes)678* 要自己批准操作，请改为[切换出自动模式](/docs/zh-CN/permission-modes#switch-permission-modes)
659 679
660在 v2.1.280 之前，Claude Code 立即拒绝来自没有判决的响应的每个操作，从不停止轮次。680在 v2.1.280 之前，Claude Code 立即拒绝来自没有判决的响应的每个操作，从不停止轮次。
661 681
663 Agent terminated early due to an API error683 Agent terminated early due to an API error
664</h3>684</h3>
665 685
666[子代理](/docs/zh-CN/sub-agents)的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，因此子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。686[子代理](/docs/zh-CN/sub-agents)的 API 请求终止失败，例如因为达到了用量限制或服务器错误的重试用尽，因此子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。
667 687
668```text theme={null}688```text theme={null}
669Agent terminated early due to an API error: <error detail>689Agent terminated early due to an API error: <error detail>
671 691
672**应该做什么：**692**应该做什么：**
673 693
674* 将冒号后的错误详情与此页面上的其自己的部分匹配，例如[使用限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作694* 将冒号后的错误详情与此页面上的其自己的部分匹配，例如[用量限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作
675* 一旦底层错误清除，请要求 Claude 重试任务或[恢复子代理](/docs/zh-CN/sub-agents#resume-subagents)695* 一旦底层错误清除，请要求 Claude 重试任务或[恢复子代理](/docs/zh-CN/sub-agents#resume-subagents)
676 696
677当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。697当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。
697 717
698Claude Code 会阻止进一步的请求，直到消息中显示的重置时间。会话和周限制在所有模型中共享，因此切换模型不会恢复访问权限。Opus 和 Sonnet 限制各自仅适用于对该模型系列的请求，因此使用 `/model` 切换到该系列之外的模型可以继续工作。718Claude Code 会阻止进一步的请求，直到消息中显示的重置时间。会话和周限制在所有模型中共享，因此切换模型不会恢复访问权限。Opus 和 Sonnet 限制各自仅适用于对该模型系列的请求，因此使用 `/model` 切换到该系列之外的模型可以继续工作。
699 719
700在使用 claude.ai 订阅登录的交互式会话中，Claude Code 也可以在打开的会话中等待，并在重置后不久继续中断的任务。等待时，会话底部的一行显示 `Usage limit reached · continuing automatically at 3:45pm · esc to cancel`。在空提示处按 `Esc` 可取消等待。有关您看到的内容、如何开始或取消等待以及如何关闭自动继续的信息，请参阅 [Wait for a usage limit to reset](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)。在 v2.1.234 之前，Claude Code 不提供此等待功能。720在使用 claude.ai 订阅登录的交互式会话中，Claude Code 也可以在打开的会话中等待，并在重置后不久继续中断的任务。有关您看到的内容、如何开始或取消等待以及如何关闭自动继续的信息，请参阅 [Wait for a usage limit to reset](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)。在 v2.1.234 之前，Claude Code 不提供此等待功能。
701 721
702使用量同时计入会话和周额度。单次大量活动突发（例如大型工作流扇出）可能会在会话窗口重置之前耗尽周额度。722使用量同时计入会话和周额度。单次大量活动突发（例如大型工作流扇出）可能会在会话窗口重置之前耗尽周额度。
703 723
885 身份验证错误905 身份验证错误
886</h2>906</h2>
887 907
888这些错误意味着 Claude Code 无法向 API 证明您的身份。随时运行 `/status` 查看当前活跃的凭证。908这些错误表示 Claude Code 无法向 API 证明您的身份。您可以随时运行 `/status` 查看当前生效的凭据。
889 909
890<h3 id="not-logged-in">910<h3 id="not-logged-in">
891 未登录911 未登录
892</h3>912</h3>
893 913
894此会话没有可用的有效凭证。914此会话没有可用的有效凭据。
895 915
896```text theme={null}916```text theme={null}
897Not logged in · Please run /login917Not logged in · Please run /login
898```918```
899 919
900在 Claude Desktop 应用运行的会话中，例如 Code 标签页或 Cowork，消息读作 `Authentication required · Sign in again to continue`，您从应用中再次登录。920在由 Claude Desktop 应用运行的会话中（例如 Code 标签页或 Cowork），消息显示为 `Authentication required · Sign in again to continue`，您需要在应用中重新登录。
901 921
902**应该做什么：**922如果您在另一个使用相同[配置目录](/docs/zh-CN/claude-directory)的 Claude Code 窗口中使用 claude.ai 账户登录，显示此消息的交互式会话会自动开始使用该登录。您无需重启会话。
923
924在 macOS 上的 v2.1.286 之前版本中，您在另一个窗口登录后，该会话可能仍会继续显示此消息。在这些版本中，请重启显示此消息的会话。
903 925
904* 运行 `/login` 以使用您的 Claude 订阅或 Console 账户进行身份验证926**解决方法：**
905* 如果您期望使用环境变量进行身份验证，请确认 `ANTHROPIC_API_KEY` 已在启动 `claude` 的 shell 中设置并导出
906* 对于无法进行交互式登录的 CI 或自动化，配置一个 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本，在启动时获取密钥
907* 查看 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) 以了解当存在多个凭证时 Claude Code 使用哪个凭证
908 927
909如果您被重复提示登录，请参阅 [未登录或令牌过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 了解系统时钟检查和 macOS 凭证存储恢复步骤。928* 运行 `/login`，使用您的 Claude 订阅或 Console 账户进行身份验证
929* 如果您原本希望通过环境变量进行身份验证，请确认在启动 `claude` 的 shell 中已设置并导出 `ANTHROPIC_API_KEY`
930* 对于无法进行交互式登录的 CI 或自动化场景，请配置一个在启动时获取密钥的 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本
931* 请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)，了解存在多个凭据时 Claude Code 使用哪一个
932
933如果系统反复提示您登录，请参阅[未登录或令牌已过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired)，了解系统时钟检查以及 macOS 凭据存储的恢复步骤。
910 934
911<h3 id="could-not-resolve-authentication-method">935<h3 id="could-not-resolve-authentication-method">
912 无法解析身份验证方法936 无法确定身份验证方法
913</h3>937</h3>
914 938
915会话到达 API 客户端时没有任何凭证。[后台会话](/docs/zh-CN/agent-view) 和云会话在 worker 启动时没有凭证时显示此消息。交互式、`-p` 和 Agent SDK 运行报告与 [未登录](#not-logged-in) 相同的条件，并仅将此字符串写入其调试日志，因此如果您在那里找到它，请改为遵循该条目。939会话在没有任何凭据的情况下到达了 API 客户端。当工作进程在没有凭据的情况下启动时，[后台会话](/docs/zh-CN/agent-view)和云端会话会显示此消息。交互式运行、`-p` 运行和 Agent SDK 运行会将同样的情况报告为[未登录](#not-logged-in)，并且只将此字符串写入调试日志，因此如果您是在调试日志中发现的，请改为按照该条目操作。
916 940
917```text theme={null}941```text theme={null}
918Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted942Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted
919```943```
920 944
921在当前版本上，该错误意味着 worker 进程没有可用的凭证。在 v2.1.174 之前，分配给空闲预初始化 worker 的后台会话即使配置了有效凭证也可能以这种方式失败。在 v2.1.176 之前，在被声明之前处于空闲状态的云会话也可能失败。升级以恢复。945在当前版本中，此错误表示工作进程没有可用的凭据。在 v2.1.174 之前，分配给空闲的预初始化工作进程的后台会话即使已配置有效凭据，也可能以这种方式失败。在 v2.1.176 之前，在被认领前处于空闲状态的云端会话也可能出现这种情况。升级即可恢复。
922 946
923**应该做什么：**947**解决方法：**
924 948
925* 如果这出现在后台或云会话中且您的凭证已配置，请升级到 v2.1.176 或更高版本949* 如果此错误出现在后台会话或云端会话中，且您的凭据已经配置好，请升级到 v2.1.176 或更高版本
926* 确认 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的云提供商凭证已在启动 worker 的环境中设置，而不仅仅在您的交互式 shell 中950* 确认 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的云服务提供商凭据已在启动工作进程的环境中设置，而不仅仅是在您的交互式 shell 中设置
927* 对于 Agent SDK，请参阅 [快速入门中的身份验证设置](/docs/zh-CN/agent-sdk/quickstart#setup)951* 对于 Agent SDK，请参阅[快速入门中的身份验证设置](/docs/zh-CN/agent-sdk/quickstart#setup)
928* 在同一环境中的交互式会话中运行 `/status` 以确认哪个凭证源可解析952* 在同一环境中的交互式会话里运行 `/status`，确认解析到的是哪个凭据来源
929 953
930<h3 id="invalid-api-key">954<h3 id="invalid-api-key">
931 无效的 API 密钥955 API 密钥无效
932</h3>956</h3>
933 957
934`ANTHROPIC_API_KEY` 环境变量或 `apiKeyHelper` 脚本返回了 API 拒绝的密钥，或 Claude Code 在发送前阻止了来自 `ANTHROPIC_API_KEY` 的密钥。958`ANTHROPIC_API_KEY` 环境变量或 `apiKeyHelper` 脚本返回了一个被 API 拒绝的密钥，或者 Claude Code 在发送前拦截了来自 `ANTHROPIC_API_KEY` 的密钥。
935 959
936```text theme={null}960```text theme={null}
937Invalid API key · Fix external API key961Invalid API key · Fix external API key
938```962```
939 963
940当消息在 `Fix external API key` 之后继续，并带有描述如 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).` 时，API 从未看到该密钥。Claude Code 发现了 HTTP 标头无法传输的字符，并在发送前停止了请求。请参阅 [无效的请求标头值](#invalid-request-header-value) 了解如何读取描述并修复该值。964如果消息在 `Fix external API key` 之后还附有一段描述，例如 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`，则说明 API 从未收到该密钥。Claude Code 发现了一个 HTTP 标头无法承载的字符，并在发送前停止了请求。请参阅[请求标头值无效](#invalid-request-header-value)，了解如何解读该描述并修正该值。
941 965
942**应该做什么：**966**解决方法：**
943 967
944* 检查拼写错误并确认密钥未在 [Console](https://platform.claude.com/settings/keys) 中被撤销968* 检查是否有拼写错误，并在 [Console](https://platform.claude.com/settings/keys) 中确认该密钥未被撤销
945* 在同一 shell 中，运行 `env | grep ANTHROPIC`，或在 PowerShell 中运行 `Get-ChildItem Env:ANTHROPIC*`。direnv、dotenv shell 插件和 IDE 终端等工具可以从项目中的 `.env` 文件加载过时的密钥，而无需您显式设置它969* 在同一个 shell 中运行 `env | grep ANTHROPIC`，或在 PowerShell 中运行 `Get-ChildItem Env:ANTHROPIC*`。direnv、dotenv shell 插件以及 IDE 终端等工具可能会从项目中的 `.env` 文件加载过时的密钥，而您并未显式设置它。
946* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login` 以改用订阅身份验证970* 取消设置 `ANTHROPIC_API_KEY` 并运行 `/login`，改用订阅身份验证
947* 如果密钥来自 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本，请直接运行该脚本以确认它在 stdout 上打印有效密钥971* 如果密钥来自 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本，请直接运行该脚本，确认它在 stdout 上输出了有效的密钥
948* 运行 `/status` 以确认 Claude Code 实际使用的凭证源972* 运行 `/status`，确认 Claude Code 实际使用的是哪个凭据来源
949 973
950<h3 id="your-apikeyhelper-script-is-failing">974<h3 id="your-apikeyhelper-script-is-failing">
951 您的 apiKeyHelper 脚本失败975 您的 apiKeyHelper 脚本运行失败
952</h3>976</h3>
953 977
954Claude Code 运行了您的 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置中的命令，但没有获得密钥。没有密钥，请求会到达 API，并带有占位符凭证，API 会以 `401` 拒绝它。终端中的 `Authentication` 面板显示发生了以下哪种情况：978Claude Code 运行了您的 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置中的命令，但没有得到密钥。没有密钥时，请求会携带一个占位凭据到达 API，API 会以 `401` 拒绝它。终端中的 `Authentication` 面板会显示发生了以下哪种情况：
955 979
956* 命令以错误退出或超时980* 命令以错误退出或超时
957* 命令未向 stdout 打印任何内容981* 命令没有向 stdout 输出任何内容
958* 命令打印了除密钥之外的内容，例如登录横幅或日志行。该面板显示 `returned output that cannot be used as an API key` 并说明了问题所在，而不重复输出。在 v2.1.227 之前，Claude Code 发送命令打印的任何内容，在修剪周围空格后。982* 命令输出了密钥以外的内容，例如登录横幅或日志行。面板会显示 `returned output that cannot be used as an API key` 并说明问题所在，但不会重复输出内容。在 v2.1.227 之前，Claude Code 会在去除首尾空白后发送命令输出的任何内容。
959 983
960```text theme={null}984```text theme={null}
961Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output985Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output
962```986```
963 987
964在 [非交互式模式](/docs/zh-CN/headless) 中，stderr 也带有具体原因，前缀为 `apiKeyHelper failed:`。988在[非交互模式](/docs/zh-CN/headless)下，stderr 也会带有具体原因，前缀为 `apiKeyHelper failed:`。
965 989
966Claude Code 重新运行脚本并在显示此消息之前最多重试请求两次，因此故障在三次尝试内出现。在 v2.1.208 之前，Claude Code 花费完整的 [重试预算](#automatic-retries) 使用占位符凭证重新发送请求，然后报告通用 `401` 身份验证错误而不是脚本故障。990在显示此消息之前，Claude Code 会重新运行脚本并最多再重试请求两次，因此失败会在三次尝试内显现。在 v2.1.208 之前，Claude Code 会用完全部[重试预算](#automatic-retries)，用占位凭据反复重新发送请求，然后报告一个通用的 `401` 身份验证错误，而不是脚本失败。
967 991
968运行 `/login` 在这里没有帮助：只要设置存在，helper 的输出 [优先于](/docs/zh-CN/authentication#authentication-precedence) 保存的登录。992此时运行 `/login` 没有帮助：只要该设置存在，helper 的输出就[优先于](/docs/zh-CN/authentication#authentication-precedence)已保存的登录。
969 993
970**应该做什么：**994**解决方法：**
971 995
972* 直接在您的 shell 中运行在 `apiKeyHelper` 中配置的命令以重现故障996* 在您的 shell 中直接运行 `apiKeyHelper` 中配置的命令，以复现该失败
973* 如果命令报告会话过期，请使用您的凭证提供商重新身份验证，例如再次登录您的 SSO 或密钥保管库997* 如果命令报告会话已过期，请向您的凭据提供方重新进行身份验证，例如重新登录您的 SSO 或密钥保管库
974* 修复命令，使其仅将密钥打印到 stdout，作为单个可打印 ASCII 令牌，最多 16,384 个字符，并以代码 0 退出。请参阅 [使用 apiKeyHelper 轮换凭证](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 了解工作设置。998* 修正命令，使其只向 stdout 输出密钥（一个由可打印 ASCII 字符组成、最多 16,384 个字符的单一令牌），并以退出码 0 退出。请参阅[使用 apiKeyHelper 轮换凭据](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper)了解可用的设置方式。
975* 运行 `/status` 查看故障并确认 `apiKeyHelper` 是活跃凭证源。`apiKeyHelper` 行显示 `Failing` 以及最后一次故障的详细信息，例如退出代码和命令的错误输出，并在下一次成功运行后消失。在 v2.1.274 之前，`/status` 仅显示凭证源，而不是故障。999* 运行 `/status` 查看失败情况，并确认 `apiKeyHelper` 是当前生效的凭据来源。`apiKeyHelper` 行会显示 `Failing` 以及上一次失败的详细信息，例如退出码和命令的错误输出，并会在下一次成功运行后消失。在 v2.1.274 之前，`/status` 只显示凭据来源，不显示失败情况。
976* 每次命令失败时，其退出代码和错误输出也会出现在终端中的 `Authentication` 面板中。在 v2.1.212 之前，该面板的标题为 `Cloud authentication`。1000* 每次命令失败时，其退出码和错误输出也会显示在终端的 `Authentication` 面板中。在 v2.1.212 之前，该面板的标题为 `Cloud authentication`。
977 1001
978<h3 id="invalid-request-header-value">1002<h3 id="invalid-request-header-value">
979 无效的请求标头值1003 请求标头值无效
980</h3>1004</h3>
981 1005
982Claude Code 即将作为请求标头发送的值包含 HTTP 标头无法传输的字符：换行符、NUL 字节或 `U+00FF` 以上的字符，例如弯引号或零宽空格。Claude Code 在发送任何内容之前停止请求，并命名要修复的变量或设置。通常的原因是从文档或聊天粘贴的凭证，其中包含不可见字符或杂散换行符。1006Claude Code 即将作为请求标头发送的某个值包含 HTTP 标头无法承载的字符：换行符、NUL 字节，或 `U+00FF` 以上的字符（例如弯引号或零宽空格）。Claude Code 会在发送任何内容之前停止请求，并指出需要修正的变量或设置。常见原因是从文档或聊天中粘贴的凭据带有不可见字符或多余的换行符。
983 1007
984Claude Code 在直接向 Claude API 或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 发送请求时运行此检查。在第三方云提供商（如 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)）上，Claude Code 在发送前不运行它。1008当 Claude Code 直接或通过 [LLM 网关](/docs/zh-CN/llm-gateway)向 Claude API 发送请求时，会执行此检查。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 等第三方云服务提供商上，Claude Code 不会在发送前执行此检查。
985 1009
986```text theme={null}1010```text theme={null}
987Invalid auth token · Fix external auth token1011Invalid auth token · Fix external auth token
989Invalid request header from the environment · Fix the environment variable1013Invalid request header from the environment · Fix the environment variable
990```1014```
991 1015
992消息的第一部分取决于坏值来自何处：1016消息的第一部分取决于错误值的来源：
993 1017
994* `Invalid auth token`：来自 [`ANTHROPIC_AUTH_TOKEN`](/docs/zh-CN/env-vars) 或 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 的持有者令牌1018* `Invalid auth token`：来自 [`ANTHROPIC_AUTH_TOKEN`](/docs/zh-CN/env-vars) 或 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 的 bearer 令牌
995* `Invalid ANTHROPIC_CUSTOM_HEADERS`：您在 [`ANTHROPIC_CUSTOM_HEADERS`](/docs/zh-CN/env-vars) 中设置的标头名称或值。描述计算哪个 `Name: Value` 对有问题，例如 `distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS`，而不重复名称或值，因为您选择了两者。1019* `Invalid ANTHROPIC_CUSTOM_HEADERS`：您在 [`ANTHROPIC_CUSTOM_HEADERS`](/docs/zh-CN/env-vars) 中设置的标头名称或值。描述会指出出错的是第几个 `Name: Value` 对，例如 `distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS`，但不会重复名称或值，因为两者都是您自己设定的。
996* `Invalid request header from the environment`：Claude Code 从另一个环境变量（如 `CLAUDE_AGENT_SDK_CLIENT_APP`）复制到请求标头中的值。描述命名要修复的变量。1020* `Invalid request header from the environment`：Claude Code 从另一个环境变量（例如 `CLAUDE_AGENT_SDK_CLIENT_APP`）复制到请求标头中的值。描述会指出需要修正的变量。
997 1021
998Claude Code 将此检查捕获的坏 `ANTHROPIC_API_KEY` 报告为 [无效的 API 密钥](#invalid-api-key)，具有相同的尾部描述。它将坏的保存 `/login` 凭证报告为 [未登录](#not-logged-in)；运行 `/login` 以保存新凭证。[`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本的输出永远不会到达此检查：Claude Code 在脚本运行时验证它，并且输出 HTTP 标头无法传输的失败会导致 [您的 apiKeyHelper 脚本失败](#your-apikeyhelper-script-is-failing)。1022此检查捕获到的错误 `ANTHROPIC_API_KEY` 会被 Claude Code 报告为 [API 密钥无效](#invalid-api-key)，并附带同样的尾部描述。错误的已保存 `/login` 凭据则会被报告为[未登录](#not-logged-in)；运行 `/login` 保存一个新的凭据即可。[`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本的输出永远不会进入此检查：Claude Code 在脚本运行时就会对其进行验证，HTTP 标头无法承载的输出会以[您的 apiKeyHelper 脚本运行失败](#your-apikeyhelper-script-is-failing)的形式失败。
999 1023
1000在第二个 `·` 之后，消息描述问题，如以下完整示例：1024在第二个 `·` 之后，消息会描述问题，完整示例如下：
1001 1025
1002```text theme={null}1026```text theme={null}
1003Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).1027Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).
1004```1028```
1005 1029
1006位置从 1 开始计算字符。描述由固定短语和字符计数构建，因此它永远不包括值本身。它仅在字符是众所周知的不可见或排版字符（如字节顺序标记、零宽空格或弯引号）时命名该字符，并将其他任何内容报告为 `a non-ASCII character`。1030位置按字符计数，从 1 开始。描述由固定短语和字符计数组成，因此永远不会包含值本身。只有当问题字符是众所周知的不可见字符或排版字符（例如字节顺序标记、零宽空格或弯引号）时，描述才会指出该字符，其他字符一律报告为 `a non-ASCII character`。
1007 1031
1008**应该做什么：**1032**解决方法：**
1009 1033
1010* 重新设置消息命名的变量或设置，重新输入报告位置周围的字符，而不是从同一来源再次粘贴1034* 重新设置消息中指出的变量或设置，手动重新输入所报告位置附近的字符，而不是再次从同一来源粘贴
1011* 对于 `ANTHROPIC_CUSTOM_HEADERS`，每行保留一个 `Name: Value` 对，并重写消息计数的对1035* 对于 `ANTHROPIC_CUSTOM_HEADERS`，每行保留一个 `Name: Value` 对，并重写消息所指出的那一对
1012* 运行 `/status` 以确认哪个凭证源处于活跃状态1036* 运行 `/status`，确认当前生效的凭据来源
1013 1037
1014<h3 id="this-organization-has-been-disabled">1038<h3 id="this-organization-has-been-disabled">
1015 此组织已被禁用1039 此组织已被停用
1016</h3>1040</h3>
1017 1041
1018Claude Code 正在使用来自已禁用 Console 组织的过时 `ANTHROPIC_API_KEY`。当您有保存的订阅登录时，密钥会覆盖它。1042Claude Code 正在使用来自已停用 Console 组织的过时 `ANTHROPIC_API_KEY`。当您有已保存的订阅登录时，该密钥会覆盖它。
1019 1043
1020```text theme={null}1044```text theme={null}
1021Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead1045Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
1023API Error: 400 ... This organization has been disabled.1047API Error: 400 ... This organization has been disabled.
1024```1048```
1025 1049
1026`·` 之后的提示取决于您保存的凭证：当存储的 `/login` 可以在您取消设置密钥后接管时出现第一种形式，当密钥是您唯一的凭证时出现第二种形式。1050`·` 之后的提示取决于您已保存的凭据：当您取消设置该密钥后有已存储的 `/login` 可以接替时，显示第一种形式；当该密钥是您唯一的凭据时，显示第二种形式。
1027 1051
1028环境变量优先于 `/login`，因此在您的 shell 配置文件中导出或从 `.env` 文件加载的密钥即使您有有效的 Pro 或 Max 订阅也会被使用。在非交互式模式 (`-p`) 中，当存在密钥时始终使用该密钥。1052环境变量优先于 `/login`，因此即使您拥有可用的 Pro 或 Max 订阅，在 shell 配置文件中导出或从 `.env` 文件加载的密钥仍会被使用。在非交互模式（`-p`）下，只要存在该密钥，就总会使用它。
1029 1053
1030**应该做什么：**1054**解决方法：**
1031 1055
1032* 在当前 shell 中取消设置 `ANTHROPIC_API_KEY` 并从您的 shell 配置文件中删除它，然后重新启动 `claude`1056* 在当前 shell 中取消设置 `ANTHROPIC_API_KEY`，并将其从 shell 配置文件中删除，然后重新启动 `claude`
1033* 如果消息说 `Update or unset`，您没有保存的登录可以回退。取消设置密钥并运行 `/login`，或将密钥替换为来自活跃 Console 组织的密钥。1057* 如果消息显示 `Update or unset`，说明您没有可回退的已保存登录。请取消设置该密钥并运行 `/login`，或将其替换为来自活跃 Console 组织的密钥。
1034* 之后运行 `/status` 以确认活跃凭证是您的订阅1058* 之后运行 `/status`，确认当前生效的凭据是您的订阅
1035* 如果未设置环境变量且错误仍然存在，请联系支持或使用不同账户登录。1059* 如果没有设置任何环境变量但错误仍然存在，请联系支持团队或使用其他账户登录。
1036 1060
1037<h3 id="your-organization-has-disabled-api-key-authentication">1061<h3 id="your-organization-has-disabled-api-key-authentication">
1038 您的组织已禁用 API 密钥身份验证1062 您的组织已禁用 API 密钥身份验证
1039</h3>1063</h3>
1040 1064
1041此消息需要 Claude Code v2.1.169 或更高版本。您的 Console 组织的管理员已关闭 API 密钥身份验证，因此 API 拒绝 Claude Code 正在发送的密钥。`·` 之后的恢复提示因密钥来自何处而异：1065此消息需要 Claude Code v2.1.169 或更高版本。您的 Console 组织管理员已关闭 API 密钥身份验证，因此 API 会拒绝 Claude Code 发送的密钥。`·` 之后的恢复提示因密钥来源而异：
1042 1066
1043```text theme={null}1067```text theme={null}
1044Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account1068Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
1048Your organization has disabled API key authentication · Sign in again with your claude.ai account1072Your organization has disabled API key authentication · Sign in again with your claude.ai account
1049```1073```
1050 1074
1051最后一种形式出现在 Claude Desktop 应用运行的会话中，例如 Code 标签页或 Cowork，您从应用中再次登录。1075最后一种形式出现在由 Claude Desktop 应用运行的会话中（例如 Code 标签页或 Cowork），此时您需要在应用中重新登录。
1052 1076
1053环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时没有帮助。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)。1077环境变量和 `apiKeyHelper` 优先于 `/login`，因此只要其中任何一个仍在提供密钥，单独运行 `/login` 是没有帮助的。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)。
1054 1078
1055**应该做什么：**1079**解决方法：**
1056 1080
1057* 如果消息命名 `ANTHROPIC_API_KEY`，在当前 shell 中取消设置它并从您的 shell 配置文件或 `.env` 文件中删除它，然后重新启动 `claude`1081* 如果消息中提到 `ANTHROPIC_API_KEY`，请在当前 shell 中取消设置它，并将其从 shell 配置文件或 `.env` 文件中删除，然后重新启动 `claude`
1058* 如果消息命名 `apiKeyHelper`，从您的 `settings.json` 中删除 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置1082* 如果消息中提到 `apiKeyHelper`，请从您的 `settings.json` 中删除 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置
1059* 运行 `/login` 以使用您的 claude.ai 账户登录1083* 运行 `/login`，使用您的 claude.ai 账户登录
1060* 之后运行 `/status` 以确认活跃凭证是您的订阅而不是 API 密钥1084* 之后运行 `/status`，确认当前生效的凭据是您的订阅而不是 API 密钥
1061* 如果您需要 API 密钥身份验证用于自动化，请要求您的组织管理员在 Console 中重新启用它1085* 如果您的自动化流程需要 API 密钥身份验证，请让组织管理员在 Console 中重新启用它
1062 1086
1063<h3 id="your-organization-has-disabled-claude-subscription-access">1087<h3 id="your-organization-has-disabled-claude-subscription-access">
1064 您的组织已禁用 Claude 订阅访问1088 您的组织已禁用 Claude 订阅访问
1065</h3>1089</h3>
1066 1090
1067您的 Claude 组织不允许使用订阅登录登录 Claude Code。使用同一账户再次运行 `/login` 会返回相同的错误。1091您的 Claude 组织不允许使用订阅登录来登录 Claude Code。使用同一账户再次运行 `/login` 会返回相同的错误。
1068 1092
1069```text theme={null}1093```text theme={null}
1070Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access1094Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access
1071```1095```
1072 1096
1073这是服务器端组织设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。1097这是服务器端的组织设置，因此无法通过本地设置、环境变量或 CLI 标志覆盖。
1074 1098
1075Agent SDK 和 `-p` 非交互式模式将此显示为 `oauth_org_not_allowed` 错误代码。1099Agent SDK 和 `-p` 非交互模式会将其呈现为 `oauth_org_not_allowed` 错误代码。
1076 1100
1077**应该做什么：**1101**解决方法：**
1078 1102
1079* 要求您的管理员为您的组织启用 Claude Code 访问1103* 请管理员为您的组织启用 Claude Code 访问权限
1080* 使用 Console API 密钥而不是您的订阅进行身份验证。请参阅 [Claude Console 身份验证](/docs/zh-CN/authentication#claude-console-authentication) 了解设置。1104* 改用 Console API 密钥而不是订阅进行身份验证。设置方法请参阅 [Claude Console 身份验证](/docs/zh-CN/authentication#claude-console-authentication)。
1081* 如果您是管理员且看不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)1105* 如果您是管理员但找不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)
1082 1106
1083<h3 id="routines-are-disabled-by-your-organizations-policy">1107<h3 id="routines-are-disabled-by-your-organizations-policy">
1084 例程被您的组织的策略禁用1108 Routine 已被您组织的策略禁用
1085</h3>1109</h3>
1086 1110
1087您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现错误，例如从 [Routines](/docs/zh-CN/routines) UI on claude.ai/code。在 Claude Code v2.1.227 或更高版本上，相同的设置也 [隐藏 `/schedule`](/docs/zh-CN/routines#troubleshooting) 在 CLI 中。1111您所在的 Team 或 Enterprise 组织中的 Owner 已在组织级别关闭了 Routine。当您尝试创建或运行 Routine 时（例如通过 claude.ai/code 上的 [Routines](/docs/zh-CN/routines) 界面），会出现此错误。在 Claude Code v2.1.227 或更高版本中，同一设置还会在 CLI 中[隐藏 `/schedule`](/docs/zh-CN/routines#troubleshooting)。
1088 1112
1089```text theme={null}1113```text theme={null}
1090Routines are disabled by your organization's policy.1114Routines are disabled by your organization's policy.
1091```1115```
1092 1116
1093这是服务器端设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。1117这是服务器端设置，因此无法通过本地设置、环境变量或 CLI 标志覆盖。
1094 1118
1095**应该做什么：**1119**解决方法：**
1096 1120
1097* 要求您的组织中的所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用 **Routines** 切换1121* 请您组织中的 Owner 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 启用 **Routines** 开关
1098* 对于不需要组织级例程的一次性计划工作，请参阅 [计划任务](/docs/zh-CN/scheduled-tasks)1122* 对于不需要组织级 Routine 的一次性定时工作，请参阅[定时任务](/docs/zh-CN/scheduled-tasks)
1099 1123
1100<h3 id="remote-control-requires-the-anthropic-api">1124<h3 id="remote-control-requires-the-anthropic-api">
1101 Remote Control 需要 Anthropic API1125 Remote Control 需要 Anthropic API
1102</h3>1126</h3>
1103 1127
1104会话不是直接与 Anthropic API 通信，因此 [Remote Control](/docs/zh-CN/remote-control) 需要。1128该会话没有直接与 Anthropic API 通信，而这是 [Remote Control](/docs/zh-CN/remote-control) 所必需的。
1105 1129
1106```text theme={null}1130```text theme={null}
1107Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.1131Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.
1108```1132```
1109 1133
1110第二句解释了什么将会话路由离开 Anthropic API；在 v2.1.219 之前，消息仅为第一句。根据原因，消息命名：1134第二句话解释了是什么让会话绕开了 Anthropic API；在 v2.1.219 之前，消息只有第一句话。根据原因不同，消息会指出：
1111 1135
1112* `CLAUDE_CODE_USE_*` 提供商变量，例如 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 的 `CLAUDE_CODE_USE_BEDROCK` 或 [Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 的 `CLAUDE_CODE_USE_VERTEX`1136* 某个 `CLAUDE_CODE_USE_*` 提供商变量，例如用于 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 的 `CLAUDE_CODE_USE_BEDROCK` 或用于 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 的 `CLAUDE_CODE_USE_VERTEX`
1113* [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机，例如 [LLM 网关](/docs/zh-CN/llm-gateway) 或代理，即使您使用 claude.ai 登录；在 v2.1.196 之前，自定义基础 URL 不会阻止 Remote Control1137* [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机，例如 [LLM 网关](/docs/zh-CN/llm-gateway)或代理，即使您使用 claude.ai 登录也是如此；在 v2.1.196 之前，自定义 base URL 不会阻止 Remote Control
1114* `ANTHROPIC_UNIX_SOCKET` 已设置，因此会话通过本地套接字而不是 `api.anthropic.com` 发送其请求1138* 设置了 `ANTHROPIC_UNIX_SOCKET`，因此会话通过本地套接字而不是发往 `api.anthropic.com` 来发送请求
1115* 企业 [云网关](/docs/zh-CN/claude-apps-gateway) 通过 `/login` 登录，不支持 Remote Control，没有变量可取消设置1139* 通过 `/login` 完成的企业[云网关](/docs/zh-CN/claude-apps-gateway)登录，它不支持 Remote Control，也没有可以取消设置的变量
1116 1140
1117**应该做什么：**1141**解决方法：**
1118 1142
1119* 取消设置消息命名的变量，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `ANTHROPIC_BASE_URL`，并重新启动会话，或从直接与 Anthropic API 通信的会话启动 Remote Control1143* 取消设置消息中指出的变量（例如 `CLAUDE_CODE_USE_BEDROCK` 或 `ANTHROPIC_BASE_URL`）并重启会话，或从直接与 Anthropic API 通信的会话中启动 Remote Control
1120* 如果变量未在您的 shell 中设置，请检查您的 [设置文件](/docs/zh-CN/settings#where-settings-live) 中的 `env` 键，该键将环境变量应用于每个会话1144* 如果该变量并未在您的 shell 中设置，请检查您[设置文件](/docs/zh-CN/settings#where-settings-live)中的 `env` 键，它会将环境变量应用到每个会话
1121* 对于此和其他 Remote Control 启动消息，请参阅 [Remote Control 故障排除](/docs/zh-CN/remote-control#troubleshooting)1145* 关于此消息及其他 Remote Control 启动消息，请参阅[排除 Remote Control 故障](/docs/zh-CN/remote-control#troubleshooting)
1122 1146
1123<h3 id="remote-control-couldnt-refresh-your-login">1147<h3 id="remote-control-couldnt-refresh-your-login">
1124 Remote Control 无法刷新您的登录1148 Remote Control 无法刷新您的登录
1125</h3>1149</h3>
1126 1150
1127Claude Code 在短期凭证上运行实时 [Remote Control](/docs/zh-CN/remote-control) 连接，它使用您保存的 claude.ai 登录获取和更新这些凭证。当 claude.ai 停止接受该登录或 Claude Code 没有保存的登录时，Claude Code 停止 Remote Control 并需要您再次登录。任一故障都可能在 Claude Code 仍在连接时或稍后在更新凭证时发生。1151Claude Code 使用短期凭据运行实时的 [Remote Control](/docs/zh-CN/remote-control) 连接，这些凭据是它借助您已保存的 claude.ai 登录获取和续期的。当 claude.ai 不再接受该登录，或者 Claude Code 已没有任何已保存的登录时，Claude Code 会停止 Remote Control，需要您重新登录。这两种失败都可能发生在 Claude Code 仍在连接时，也可能发生在之后续期凭据时。
1128 1152
1129当 Claude Code 要求登录服务刷新您保存的登录并且没有得到答复时，它会保持 Remote Control 运行并在连接的当前凭证仍然有效时再次尝试刷新。当 Claude Code 无法到达登录服务、请求超时或服务在不拒绝您的登录的情况下失败时，刷新会得不到答复。如果当该凭证过期时登录服务仍然没有答复，Claude Code 会停止 Remote Control 并报告 `OAuth token refresh failed`。1153当 Claude Code 请求登录服务刷新您已保存的登录却没有得到响应时，它会保持 Remote Control 运行，并在连接的当前凭据仍然有效期间再次尝试刷新。当 Claude Code 无法访问登录服务、请求超时，或服务失败但并未拒绝您的登录时，刷新就会得不到响应。如果在该凭据过期时登录服务仍未响应，Claude Code 会停止 Remote Control 并报告 `OAuth token refresh failed`。
1130 1154
1131当 Claude Code 停止 Remote Control 时，它在警告和以 `Remote Control disconnected` 开头的成绩单行中显示原因。您的本地会话继续运行而没有 Remote Control。本部分涵盖这些行：1155当 Claude Code 停止 Remote Control 时，它会在警告以及一条以 `Remote Control disconnected` 开头的会话记录行中显示原因。您的本地会话会在没有 Remote Control 的情况下继续运行。本节涵盖以下消息行：
1132 1156
1133```text theme={null}1157```text theme={null}
1134Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control1158Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
1140Remote Control disconnected — Signed out of Claude — run /login, then /remote-control1164Remote Control disconnected — Signed out of Claude — run /login, then /remote-control
1141```1165```
1142 1166
1143Claude Code 在消息中间命名原因：1167Claude Code 会在消息中间部分说明原因：
1144 1168
1145* ` Claude.ai login expired` 和 `Claude.ai login was rejected`：claude.ai 不再接受您保存的登录令牌，因为它已过期或被撤销1169* `Claude.ai login expired` 和 `Claude.ai login was rejected`：claude.ai 不再接受您已保存的登录令牌，因为它已过期或被撤销
1146* ` OAuth token unavailable`：当连接的凭证到期需要更新时，Claude Code 没有保存的登录令牌1170* `OAuth token unavailable`：当连接的凭据到期需要续期时，Claude Code 没有已保存的登录令牌
1147* `OAuth token refresh failed`：claude.ai 在 Claude Code 重新连接时拒绝了您保存的登录令牌，刷新令牌没有产生新令牌1171* `OAuth token refresh failed`：Claude Code 重新连接时，claude.ai 拒绝了您已保存的登录令牌，且刷新令牌没有产生新令牌
1148* `JWT refresh failed: no OAuth token`：Claude Code 找不到保存的登录令牌来更新1172* `JWT refresh failed: no OAuth token`：Claude Code 找不到可用于续期的已保存登录令牌
1149* ` Signed out of Claude`：您在此机器上登出，例如在另一个终端中运行 `/logout`，因此 Claude Code 没有保存的登录来更新连接1173* `Signed out of Claude`：您在这台机器上退出了登录，例如在另一个终端中运行了 `/logout`，因此 Claude Code 已没有可用于续期连接的已保存登录
1150 1174
1151**应该做什么：**1175**解决方法：**
1152 1176
1153* 运行 `/login` 再次登录1177* 运行 `/login` 重新登录
1154* 运行 `/remote-control` 重新连接会话。以 `run /login to restore Remote Control` 结尾的消息不需要此步骤：Claude Code 在您登录后自动重新连接。1178* 运行 `/remote-control` 重新连接会话。以 `run /login to restore Remote Control` 结尾的消息不需要此步骤：您登录后 Claude Code 会自动重新连接。
1155 1179
1156在 v2.1.224 之前，`OAuth token refresh failed — run /login to re-authenticate` 读作 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`，`JWT refresh failed: no OAuth token — run /login` 读作 `no OAuth token available for recovery (code <N>)`。` Claude.ai login expired`、`Claude.ai login was rejected` 和 `OAuth token unavailable` 消息在 v2.1.225 中添加。1180在 v2.1.224 之前，`OAuth token refresh failed — run /login to re-authenticate` 显示为 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`，`JWT refresh failed: no OAuth token — run /login` 显示为 `no OAuth token available for recovery (code <N>)`。`Claude.ai login expired`、`Claude.ai login was rejected` 和 `OAuth token unavailable` 消息是在 v2.1.225 中添加的。
1157 1181
1158在 v2.1.238 之前，Claude Code 将现在说 `Signed out of Claude` 的情况报告为 `JWT refresh failed: no OAuth token — run /login`，并在一次登录刷新没有得到答复后立即停止 Remote Control，显示 `Claude.ai login expired — run /login to restore Remote Control`。1182在 v2.1.238 之前，Claude Code 将现在显示为 `Signed out of Claude` 的情况报告为 `JWT refresh failed: no OAuth token — run /login`，并且只要有一次登录刷新未得到响应，就会以 `Claude.ai login expired — run /login to restore Remote Control` 停止 Remote Control。
1159 1183
1160<h3 id="remote-control-stopped-because-the-signed-in-account-changed">1184<h3 id="remote-control-stopped-because-the-signed-in-account-changed">
1161 Remote Control 停止，因为登录账户已更改1185 由于登录账户已更改，Remote Control 已停止
1162</h3>1186</h3>
1163 1187
1164Claude Code 在 [Remote Control](/docs/zh-CN/remote-control) 会话期间显示此行，当您在此机器上登录到不同的 claude.ai 账户或组织时。您在 Claude Code 会话外进行了切换，例如在另一个终端中运行 `/login`。1188在 [Remote Control](/docs/zh-CN/remote-control) 会话期间，当您在这台机器上登录到另一个 claude.ai 账户或组织时，Claude Code 会显示这行消息。这种切换是在 Claude Code 会话之外进行的，例如在另一个终端中运行了 `/login`。
1165 1189
1166您在通过 `/login` 登录时启动的 Remote Control 会话属于当时登录的 claude.ai 账户和组织。1190您在通过 `/login` 登录状态下启动的 Remote Control 会话，属于启动时所登录的 claude.ai 账户和组织。
1167 1191
1168```text theme={null}1192```text theme={null}
1169Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control1193Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control
1170```1194```
1171 1195
1172Claude Code 在 claude.ai 确认账户或组织已更改后立即停止 Remote Control 会话。您的本地会话继续运行而没有 Remote Control。1196一旦 claude.ai 确认账户或组织已更改，Claude Code 就会停止 Remote Control 会话。您的本地会话会在没有 Remote Control 的情况下继续运行。
1173 1197
1174**应该做什么：**1198**解决方法：**
1175 1199
1176* 运行 `/remote-control` 在当前账户或组织下启动新的 Remote Control 会话1200* 运行 `/remote-control`，在当前账户或组织下启动新的 Remote Control 会话
1177* 要切换回去，运行 `/login` 并再次登录到之前的账户或组织。然后运行 `/remote-control`。1201* 如需切换回去，请运行 `/login` 并重新登录之前的账户或组织，然后运行 `/remote-control`。
1178 1202
1179在 v2.1.234 之前，Claude Code 在您在 Claude Code 会话外切换到不同账户或组织时没有注意到。Claude Code 保持 Remote Control 会话连接，直到稍后对 Remote Control 服务器的请求失败，显示 `Remote Control server rejected the request (HTTP 404)`。该故障可能在切换后数小时发生。1203在 v2.1.234 之前，当您在 Claude Code 会话之外切换到其他账户或组织时，Claude Code 不会察觉。Claude Code 会保持 Remote Control 会话连接，直到之后某个发往 Remote Control 服务器的请求以 `Remote Control server rejected the request (HTTP 404)` 失败。该失败可能在切换后数小时才出现。
1180 1204
1181<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">1205<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">
1182 Remote Control 停止，因为运行会话的应用登出或切换了账户1206 由于运行会话的应用已退出登录或切换了账户，Remote Control 已停止
1183</h3>1207</h3>
1184 1208
1185当 Claude 桌面应用或 IDE 托管您的会话时，Claude Code 从该应用而不是从 `/login` 获取其登录令牌。当 claude.ai 拒绝该令牌时，Claude Code 要求应用提供新令牌。如果应用回答说它已登出或现在登录到不同的 Claude 账户，Claude Code 结束 [Remote Control](/docs/zh-CN/remote-control) 会话并向应用发送以下行之一：1209当 Claude 桌面应用或 IDE 托管您的会话时，Claude Code 会从该应用而不是从 `/login` 获取登录令牌。当 claude.ai 拒绝该令牌时，Claude Code 会向应用请求新令牌。如果应用回复它已退出登录，或者现在登录的是另一个 Claude 账户，Claude Code 会结束 [Remote Control](/docs/zh-CN/remote-control) 会话，并向应用发送以下消息行之一：
1186 1210
1187```text theme={null}1211```text theme={null}
1188Remote Control stopped — the app running this session is now signed in to a different Claude account1212Remote Control stopped — the app running this session is now signed in to a different Claude account
1189Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on1213Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on
1190```1214```
1191 1215
1192您的本地会话继续运行而没有 Remote Control。1216您的本地会话会在没有 Remote Control 的情况下继续运行。
1193 1217
1194**应该做什么：**1218**解决方法：**
1195 1219
1196* 如果应用已登出，再次登录，然后在应用中重新打开 Remote Control1220* 如果应用已退出登录，请在应用中重新登录，然后在应用中重新打开 Remote Control
1197* 如果应用切换了账户，Claude Code 无法在新账户下继续已结束的会话。在该账户下启动新的 Remote Control 会话。1221* 如果应用切换了账户，Claude Code 无法在新账户下继续已结束的会话。请在该账户下启动新的 Remote Control 会话。
1198 1222
1199在 v2.1.238 之前，Claude Code 在两种情况下都向应用发送了 [Remote Control 无法刷新您的登录](#remote-control-couldnt-refresh-your-login) 下列出的 `run /login` 消息。1223在 v2.1.238 之前，这两种情况下 Claude Code 都会向应用发送[Remote Control 无法刷新您的登录](#remote-control-couldnt-refresh-your-login)中列出的 `run /login` 消息。
1200 1224
1201<h3 id="oauth-token-revoked-or-expired">1225<h3 id="oauth-token-revoked-or-expired">
1202 OAuth 令牌被撤销或过期1226 OAuth 令牌已撤销或已过期
1203</h3>1227</h3>
1204 1228
1205您保存的登录不再有效。被撤销的令牌意味着您在任何地方登出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中失败。1229您已保存的登录不再有效。令牌被撤销意味着您在所有位置都退出了登录，或者管理员移除了访问权限；令牌过期意味着会话中途的自动刷新失败了。
1206 1230
1207两条消息都报告 API 为 Claude Code 发送的请求返回的拒绝。当保存的登录在失败的刷新后已被清除时，您会看到 [登录过期](#login-expired)。如果您使用 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 中的长期令牌进行身份验证，当该令牌过期或被撤销时，您会看到相同的消息。1231这两条消息报告的都是 API 对 Claude Code 所发送请求返回的拒绝。如果已保存的登录在刷新失败后已被清除，您看到的将是[登录已过期](#login-expired)。如果您在 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 中使用长期令牌进行身份验证，当该令牌过期或被撤销时，您也会看到同样的消息。
1208 1232
1209```text theme={null}1233```text theme={null}
1210OAuth token revoked · Please run /login1234OAuth token revoked · Please run /login
1211Please run /login · API Error: 401 OAuth token has expired ...1235Please run /login · API Error: 401 OAuth token has expired ...
1212```1236```
1213 1237
1214**应该做什么：**1238在[非交互模式](/docs/zh-CN/headless)（`-p`）和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下，结构化错误代码为 `authentication_failed`：
1239
1240```text theme={null}
1241Failed to authenticate: OAuth token revoked. Please log in again or contact your administrator.
1242Failed to authenticate. API Error: 401 OAuth token has expired ...
1243```
1215 1244
1216* 运行 `/login` 再次登录1245在 v2.1.287 之前，非交互模式和 Agent SDK 中的撤销消息为 `Your account does not have access to Claude. Please login again or contact your administrator.`
1217* 如果您使用 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量进行身份验证，Claude Code 在请求失败并显示 401 后会继续发送您设置的值，而不是切换到保存的登录的令牌。[`/status`](/docs/zh-CN/commands) 将此凭证显示为读取 `CLAUDE_CODE_OAUTH_TOKEN` 的 `Auth token` 行。使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成新令牌并使用它重新启动，或取消设置变量并运行 `/login`。在 v2.1.225 之前，Claude Code 可以在会话中用保存的登录的短期访问令牌替换变量的值，一旦该令牌过期，会话再次失败并显示 401 错误。1246
1218* 对于跨启动的重复登录提示，请参阅 [故障排除](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟检查和 macOS 凭证存储恢复步骤1247**解决方法：**
1219* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)1248
1249* 在 Claude Code 提示符下运行 `/login` 重新登录
1250* 如果您的 `-p` 命令或 Agent SDK 程序使用已保存的登录，请在同一环境中运行 `claude`，完成 `/login`，然后再次运行该命令或程序。对于无法交互式登录的自动化场景，请使用 [`ANTHROPIC_API_KEY`](/docs/zh-CN/env-vars) 进行身份验证，或[使用 `claude setup-token` 生成长期令牌](/docs/zh-CN/authentication#generate-a-long-lived-token)。
1251* 如果您使用 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量进行身份验证，在请求以 401 失败后，Claude Code 会继续发送您设置的值，而不会切换到已存储登录的令牌。[`/status`](/docs/zh-CN/commands) 会将此凭据显示为一个 `Auth token` 行，内容为 `CLAUDE_CODE_OAUTH_TOKEN`。请使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成新令牌并用它重启，或取消设置该变量并运行 `/login`。在 v2.1.225 之前，Claude Code 可能会在会话中途用已存储登录的短期访问令牌替换该变量的值，一旦该令牌过期，会话就会再次因 401 错误而失败。
1252* 如果每次启动都反复提示您登录，请参阅[故障排除](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired)中的系统时钟检查和 macOS 凭据存储恢复步骤
1253* 对于其他失败，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅[登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)
1220 1254
1221<h3 id="api-error-401-invalid-authentication-credentials">1255<h3 id="api-error-401-invalid-authentication-credentials">
1222 API 错误：401 无效的身份验证凭证1256 API Error: 401 Invalid authentication credentials
1223</h3>1257</h3>
1224 1258
1225API 识别了您凭证的格式，但拒绝了其背后的账户或组织。当凭证最近被撤销、组织被禁用或删除了您的访问权限或账户本身被停用时，Anthropic 返回此消息，因此过期的令牌不是原因。凭证可以是您保存的登录或批准的 `ANTHROPIC_API_KEY`，修复方式不同，因此首先运行 `/status` 查看哪个处于活跃状态。1259API 识别了您凭据的格式，但拒绝了其背后的账户或组织。当凭据最近被撤销、组织被停用或移除了您的访问权限，或账户本身被停用时，Anthropic 会返回此消息，因此原因并不是令牌过期。该凭据可能是您已保存的登录，也可能是已批准的 `ANTHROPIC_API_KEY`，两者的修复方法不同，因此请先运行 `/status` 查看当前生效的是哪一个。
1226 1260
1227```text theme={null}1261```text theme={null}
1228Please run /login · API Error: 401 Invalid authentication credentials1262Please run /login · API Error: 401 Invalid authentication credentials
1229```1263```
1230 1264
1231**应该做什么：**1265**解决方法：**
1232 1266
1233* 如果 `/status` 显示未标记为未使用的 `API key` 行，则批准的 [`ANTHROPIC_API_KEY`](/docs/zh-CN/authentication#authentication-precedence) 是活跃凭证并优先于您的登录，因此 `/login` 不会替换它。在 Claude Console 中轮换密钥，或通过运行 `unset ANTHROPIC_API_KEY` 回退到您的订阅，或在 PowerShell 中运行 `Remove-Item Env:ANTHROPIC_API_KEY`。1267* 如果 `/status` 显示一个未标记为未使用的 `API key` 行，说明已批准的 [`ANTHROPIC_API_KEY`](/docs/zh-CN/authentication#authentication-precedence) 是当前生效的凭据，并且优先于您的登录，因此 `/login` 不会替换它。请在 Claude Console 中轮换该密钥，或通过运行 `unset ANTHROPIC_API_KEY`（在 PowerShell 中为 `Remove-Item Env:ANTHROPIC_API_KEY`）回退到您的订阅。
1234* 如果 `/status` 仅显示您的登录，运行 `/login` 一次。如果凭证被撤销，新登录会替换它。1268* 如果 `/status` 只显示您的登录，请运行一次 `/login`。如果凭据已被撤销，新的登录会替换它。
1235* 如果相同的消息对相同的登录账户返回，则该账户或组织不再活跃。检查 `/status` 报告的账户和组织，并要求您的组织管理员恢复访问。1269* 如果同一登录账户再次出现相同消息，说明该账户或组织已不再活跃。请检查 `/status` 报告的账户和组织，并请您的组织管理员恢复访问权限。
1236* 如果 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 [LLM 网关](/docs/zh-CN/llm-gateway)，`401` 之后的文本是您网关的消息而不是 Anthropic 的，`/login` 不会改变它。改为修复您的网关期望的凭证。1270* 如果 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 [LLM 网关](/docs/zh-CN/llm-gateway)，`401` 之后的文本是您网关的消息而不是 Anthropic 的消息，`/login` 不会改变它。请改为修正网关所需的凭据。
1237 1271
1238<h3 id="login-expired">1272<h3 id="login-expired">
1239 登录过期1273 登录已过期
1240</h3>1274</h3>
1241 1275
1242Claude Code 尝试更新您保存的 claude.ai 登录，OAuth 服务拒绝了存储的刷新令牌，因此 Claude Code 清除了保存的凭证。之后，每个模型请求在到达 API 之前都会在本地停止，显示此消息，因为只有 `/login` 可以创建新凭证。1276Claude Code 尝试续期您已保存的 claude.ai 登录，但 OAuth 服务拒绝了已存储的刷新令牌，因此 Claude Code 清除了已保存的凭据。此后，每个模型请求都会在到达 API 之前于本地以此消息停止，因为只有 `/login` 才能创建新凭据。
1243 1277
1244在 v2.1.206 之前，Claude Code 无论如何都会发送模型请求，使用环境中剩余的任何凭证，每个模型都会失败，显示 [所选模型有问题](#theres-an-issue-with-the-selected-model) 或 401，而不是登录提示。1278在 v2.1.206 之前，Claude Code 仍会使用环境中剩余的任何凭据发送模型请求，然后每个模型都会以[所选模型存在问题](#theres-an-issue-with-the-selected-model)或 401 失败，而不是提示您登录。
1245 1279
1246```text theme={null}1280```text theme={null}
1247Login expired · Please run /login1281Login expired · Please run /login
1248```1282```
1249 1283
1250在 [非交互式模式](/docs/zh-CN/headless) (`-p`) 和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下所示，结构化错误代码为 `authentication_failed`：1284在[非交互模式](/docs/zh-CN/headless)（`-p`）和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下，结构化错误代码为 `authentication_failed`：
1251 1285
1252```text theme={null}1286```text theme={null}
1253Failed to authenticate: OAuth session expired and could not be refreshed1287Failed to authenticate: OAuth session expired and could not be refreshed
1254```1288```
1255 1289
1256这与 [OAuth 令牌被撤销或过期](#oauth-token-revoked-or-expired) 的状态不同。这些消息报告 API 返回的拒绝。Claude Code 本身为已失败更新的登录生成 `Login expired`，因此它不发送请求。当更新失败是因为账户本身被暂停而不是登录过时时，Claude Code 改为显示 [您的账户被冻结](#your-account-is-on-hold)。1290这与 [OAuth 令牌已撤销或已过期](#oauth-token-revoked-or-expired)并非同一状态。那些消息报告的是 API 返回的拒绝。而 `Login expired` 是 Claude Code 针对已续期失败的登录自行生成的，因此它不会发送任何请求。当续期失败是因为账户本身被暂停而不是登录过时，Claude Code 会改为显示[您的账户已被暂停](#your-account-is-on-hold)。
1257 1291
1258使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。1292使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用已保存的登录，永远不会看到此消息。
1259 1293
1260您可以在请求失败之前检查此状态：[`/status`](/docs/zh-CN/commands) 显示读取 `Expired — log in again` 的 `Login` 行，加上它为过期登录保存的组织和电子邮件。该行仅在保存的登录是您的活跃凭证且无法再刷新时出现。以其他方式进行身份验证的会话不显示该行，即使过期的登录仍然保存。在 v2.1.210 之前，`/status` 在此状态下没有指示登录曾经存在过，因为清除的凭证使其无法报告。1294您可以在请求失败之前检查是否处于此状态：[`/status`](/docs/zh-CN/commands) 会显示一个 `Login` 行，内容为 `Expired — log in again`，以及它为该过期登录保存的组织和电子邮件。只有当已保存的登录是您当前生效的凭据且无法再刷新时，才会显示该行。以其他方式进行身份验证的会话不会显示该行，即使仍保存着已过期的登录。在 v2.1.210 之前，`/status` 在此状态下不会提供任何曾存在登录的迹象，因为凭据已被清除，没有可报告的内容。
1261 1295
1262**应该做什么：**1296**解决方法：**
1263 1297
1264* 运行 `/login` 再次登录。在不登录的情况下重试会在每个请求上显示相同的消息。1298* 运行 `/login` 重新登录。不登录而直接重试，每个请求都会显示相同的消息。
1265* 在非交互式模式中，在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化，使用 `ANTHROPIC_API_KEY` 进行身份验证或 [使用 `claude setup-token` 生成长期令牌](/docs/zh-CN/authentication#generate-a-long-lived-token)。1299* 如果您在另一个 Claude Code 窗口中使用 claude.ai 账户登录，请参阅[未登录](#not-logged-in)，了解此会话何时会自动开始使用该登录。
1266* 如果登录持续失败，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)1300* 在非交互模式下，请在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化场景，请使用 `ANTHROPIC_API_KEY` 进行身份验证，或[使用 `claude setup-token` 生成长期令牌](/docs/zh-CN/authentication#generate-a-long-lived-token)。
1301* 如果登录一直失败，请参阅[登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)
1267 1302
1268<h3 id="could-not-refresh-your-login">1303<h3 id="could-not-refresh-your-login">
1269 无法刷新您的登录，因为另一个 Claude Code 进程正在刷新它1304 由于另一个 Claude Code 进程正在刷新您的登录，无法刷新
1270</h3>1305</h3>
1271 1306
1272此消息不意味着您的登录被拒绝。您保存的 claude.ai 登录已过期，需要更新。另一个 Claude Code 进程在同一机器上持有共享刷新锁，或退出并留下它，刷新在此会话等待时没有进展。Claude Code 在发送前停止请求：1307此消息并不表示您的登录被拒绝。您已保存的 claude.ai 登录已过期，需要续期。同一台机器上的另一个 Claude Code 进程持有共享的刷新锁，或者该进程已退出但遗留了该锁，在此会话等待期间刷新没有任何进展。Claude Code 会在发送前停止请求：
1273 1308
1274```text theme={null}1309```text theme={null}
1275Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login1310Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login
1276```1311```
1277 1312
1278在 [非交互式模式](/docs/zh-CN/headless) (`-p`) 和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下所示，结构化错误代码为 `server_error`：1313在[非交互模式](/docs/zh-CN/headless)（`-p`）和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下，结构化错误代码为 `server_error`：
1279 1314
1280```text theme={null}1315```text theme={null}
1281Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again1316Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again
1282```1317```
1283 1318
1284使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。1319使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用已保存的登录，永远不会看到此消息。
1285 1320
1286**应该做什么：**1321**解决方法：**
1287 1322
1288* 一分钟后重试。如果另一个进程首先完成刷新，此会话使用更新的登录。1323* 一分钟后重试。如果另一个进程先完成了刷新，此会话会使用续期后的登录。
1289* 如果消息持续返回，关闭其他 Claude Code 窗口和进程，然后重试。1324* 如果消息反复出现，请关闭其他 Claude Code 窗口和进程，然后重试。
1290* 如果在没有其他 Claude Code 进程运行的情况下返回，运行 `/login`。再次登录不会等待刷新锁。1325* 如果在没有其他 Claude Code 进程运行的情况下仍出现该消息，请运行 `/login`。重新登录不会等待刷新锁。
1291 1326
1292<h3 id="couldnt-save-your-login">1327<h3 id="couldnt-save-your-login">
1293 无法保存您的登录1328 无法保存您的登录
1294</h3>1329</h3>
1295 1330
1296您使用 claude.ai 登录，但 Claude Code 无法将登录保存到其凭证存储，因此登录未完成。在 macOS 上，当登录钥匙链锁定时（例如在睡眠或空闲时），在 Claude Code 已在同一会话中读取或保存凭证之后，可能会发生这种情况。1331您已使用 claude.ai 登录，但 Claude Code 无法将登录保存到其凭据存储中，因此登录未完成。在 macOS 上，如果 Claude Code 在同一会话中已经读取或保存过登录钥匙串中的凭据，之后钥匙串被锁定（例如在睡眠或空闲时），就可能发生这种情况。
1297 1332
1298```text theme={null}1333```text theme={null}
1299Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.1334Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
1300Couldn't save your login. Try logging in again.1335Couldn't save your login. Try logging in again.
1301```1336```
1302 1337
1303第一种形式出现在 macOS 上，第二种形式出现在其他地方。临时凭证存储故障（例如超时或不可读的存储）会产生相同的消息。1338第一种形式出现在 macOS 上，第二种形式出现在其他所有平台上。暂时性的凭据存储失败（例如超时或存储无法读取）也会产生同样的消息。
1304 1339
1305**应该做什么：**1340**解决方法：**
1306 1341
1307* 在 macOS 上，解锁登录钥匙链，然后再次运行 `/login`1342* 在 macOS 上，解锁登录钥匙串，然后再次运行 `/login`
1308* 在其他平台上，再次运行 `/login`1343* 在其他平台上，再次运行 `/login`
1309* 如果登录仍然不保存，请参阅 [未登录或令牌过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 了解钥匙链解锁命令和其他凭证存储恢复步骤1344* 如果登录仍然无法保存，请参阅[未登录或令牌已过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired)，了解钥匙串解锁命令和其他凭据存储恢复步骤
1310 1345
1311<h3 id="failed-to-start-oauth-callback-server">1346<h3 id="failed-to-start-oauth-callback-server">
1312 Failed to start OAuth callback server1347 无法启动 OAuth 回调服务器
1313</h3>1348</h3>
1314 1349
1315当 `/login`、`claude auth login` 或 `claude setup-token` 通过浏览器登录您时，Claude Code 在 `127.0.0.1` 上打开一个监听端口，以便您的浏览器可以将登录结果返回给它。此消息意味着 Claude Code 无法打开该端口，登录在浏览器窗口或登录 URL 出现之前停止：1350当 `/login`、`claude auth login` 或 `claude setup-token` 通过浏览器为您登录时，Claude Code 会在 `127.0.0.1` 上打开一个监听端口，以便浏览器将登录结果返回给它。此消息表示 Claude Code 无法打开该端口，登录会在浏览器窗口或登录 URL 出现之前停止：
1316 1351
1317```text theme={null}1352```text theme={null}
1318Failed to start OAuth callback server: Failed to start server. Is port 0 in use?1353Failed to start OAuth callback server: Failed to start server. Is port 0 in use?
1319```1354```
1320 1355
1321如果您的消息以 `Is port 0 in use?` 结尾，尝试在 IPv4 环回地址 `127.0.0.1` 上监听的尝试完全失败。因为故障发生在登录 URL 存在之前，`Paste code here if prompted` 流不可用作解决方法。1356如果您的消息以 `Is port 0 in use?` 结尾，说明在 IPv4 回环地址 `127.0.0.1` 上监听的尝试直接失败了。由于失败发生在登录 URL 生成之前，`Paste code here if prompted` 流程无法作为变通方案使用。
1322 1357
1323**应该做什么：**1358**解决方法：**
1324 1359
1325* 要立即登录而不需要本地监听器：如果您使用 claude.ai 订阅，在登录有效的机器上运行 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 并将其打印的令牌设置为此机器上的 `CLAUDE_CODE_OAUTH_TOKEN`。否则将 `ANTHROPIC_API_KEY` 设置为来自 [Claude Console](https://platform.claude.com/settings/keys) 的密钥。[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) 解释了 Claude Code 在存在多个凭证时如何选择。1360* 如需不使用本地监听器立即登录：如果您使用 claude.ai 订阅，请在可以正常登录的机器上运行 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token)，并在这台机器上将它输出的令牌设置为 `CLAUDE_CODE_OAUTH_TOKEN`。否则，请将 `ANTHROPIC_API_KEY` 设置为来自 [Claude Console](https://platform.claude.com/settings/keys) 的密钥。[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)解释了 Claude Code 如何在多个凭据之间进行选择。
1326* 要在此机器上改用浏览器登录，Claude Code 必须能够在 `127.0.0.1` 上监听。如果它在沙箱内运行，检查沙箱的策略是否允许在本地端口上监听，然后再次运行 `/login`。如果它应该能够但仍然失败，运行 `/feedback` 以便报告包含您的环境详细信息。1361* 如果要改为在这台机器上使用浏览器登录，Claude Code 必须能够在 `127.0.0.1` 上监听。如果它在沙箱中运行，请检查沙箱策略是否允许监听本地端口，然后再次运行 `/login`。如果它本应能够监听却仍然失败，请运行 `/feedback`，以便报告中包含您的环境详细信息。
1327 1362
1328<h3 id="claude-login-not-accepted">1363<h3 id="claude-login-not-accepted">
1329 Claude login not accepted1364 Claude 登录未被接受
1330</h3>1365</h3>
1331 1366
1332您尝试启动 [云会话](/docs/zh-CN/claude-code-on-the-web)，服务器拒绝使用 401 创建它：它不接受此机器发送的 Claude 登录，通常是因为登录过期或被撤销。1367您尝试启动一个[云端会话](/docs/zh-CN/claude-code-on-the-web)，服务器以 401 拒绝创建它：服务器不接受这台机器发送的 Claude 登录，通常是因为该登录已过期或被撤销。
1333 1368
1334当服务器给出自己的原因时，行的第一部分是该原因。否则该行读作：1369如果服务器给出了原因，该行的第一部分就是服务器自己的原因。否则，该行显示为：
1335 1370
1336```text theme={null}1371```text theme={null}
1337Claude login not accepted · Run /login, then try again1372Claude login not accepted · Run /login, then try again
1338```1373```
1339 1374
1340**应该做什么：**1375**解决方法：**
1341 1376
1342* 运行 `/login`，完成登录，然后再次启动会话1377* 运行 `/login`，完成登录，然后再次启动会话
1343 1378
1344<h3 id="artifacts-need-a-claude-ai-login">1379<h3 id="artifacts-need-a-claude-ai-login">
1345 工件需要 claude.ai 登录1380 Artifact 需要 claude.ai 登录
1346</h3>1381</h3>
1347 1382
1348Claude Code 拒绝了 [工件](/docs/zh-CN/artifacts) 发布或读取，因为会话没有可用于工件的 claude.ai 登录。1383Claude Code 拒绝了 [Artifact](/docs/zh-CN/artifacts) 的发布或读取，因为该会话没有可用于 Artifact 的 claude.ai 登录。
1349 1384
1350消息的每种形式都以相同的词开头，然后是取决于您的会话如何进行身份验证的补救措施。没有竞争凭证时，它读作：1385该消息的每种形式都以相同的文字开头，后面跟着的补救措施取决于您的会话如何进行身份验证。没有竞争凭据时，消息显示为：
1351 1386
1352```text theme={null}1387```text theme={null}
1353Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.1388Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.
1354```1389```
1355 1390
1356**应该做什么：**1391**解决方法：**
1357 1392
1358* 运行 `/login` 并选择 **Claude account with subscription**。**Anthropic Console account** 选项不提供 claude.ai 凭证。1393* 运行 `/login` 并选择 **Claude account with subscription**。**Anthropic Console account** 选项不提供 claude.ai 凭据。
1359* 当消息命名优先的凭证（如 `ANTHROPIC_API_KEY`、`apiKeyHelper` 设置或之前 `/login` 保存的 Console 密钥）时，按消息说的方式删除它，然后运行 `/login`1394* 当消息指出某个优先级更高的凭据时，例如 `ANTHROPIC_API_KEY`、`apiKeyHelper` 设置或之前的 `/login` 保存的 Console 密钥，请按消息所述将其移除，然后运行 `/login`
1360* 当消息说此远程会话通过启动它的机器进行身份验证时，在该机器上登录到 claude.ai，然后重新连接会话1395* 当消息说明此远程会话通过启动它的机器进行身份验证时，请在那台机器上登录 claude.ai，然后重新连接会话
1361* 当消息说凭证由会话的主机环境注入时，您无法在该会话中更改它；启动登录到 claude.ai 的会话1396* 当消息说明凭据由会话的宿主环境注入时，您无法在该会话中更改它；请启动一个已登录 claude.ai 的会话
1362* 请参阅 [可用性](/docs/zh-CN/artifacts#availability) 了解工件具有的其他要求，例如计划、模型提供商和组织策略1397* 请参阅[可用性](/docs/zh-CN/artifacts#availability)，了解 Artifact 的其他要求，例如套餐、模型提供商和组织策略
1363 1398
1364<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">1399<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">
1365 管理员策略需要 Cloud gateway 登录1400 管理员策略要求使用云网关登录
1366</h3>1401</h3>
1367 1402
1368管理员在此机器上的 [托管设置](/docs/zh-CN/managed-settings) 将 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 设置为 `"gateway"` 或设置 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)。除非您通过 `CLAUDE_CODE_USE_BEDROCK` 等变量选择云提供商，Claude Code 仅接受 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录。您会看到两条消息之一：1403这台机器上管理员的[托管设置](/docs/zh-CN/managed-settings)将 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 设置为 `"gateway"`，或设置了 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)。除非您通过 `CLAUDE_CODE_USE_BEDROCK` 等变量选择了云服务提供商，否则 Claude Code 只接受 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录。您会看到以下两种消息之一：
1369 1404
1370```text theme={null}1405```text theme={null}
1371Not signed in to the Cloud gateway — run /login.1406Not signed in to the Cloud gateway — run /login.
1372```1407```
1373 1408
1374当会话没有网关登录时，模型请求失败，显示此消息，例如因为您自策略到达机器后未运行 `/login`。1409当会话没有网关登录时，模型请求会以此消息失败，例如因为在该策略下发到这台机器后您还没有运行过 `/login`。
1410
1411如果这台机器上还存在 Anthropic 签发的凭据，并且托管设置设置了 `forceLoginMethod` 或 `forceLoginOrgUUID`，Claude Code 则会在启动时退出。该凭据可能是 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 变量、`apiKeyHelper` 设置，或之前的 Claude Console 登录保存的 API 密钥。
1375 1412
1376如果机器还持有 Anthropic 颁发的凭证且托管设置设置了 `forceLoginMethod` 或 `forceLoginOrgUUID`，Claude Code 在启动时改为以此消息退出：1413启动消息会指出会话所配置的凭据、它的设置位置以及移除它的步骤。例如，当您在 shell 中设置了 `ANTHROPIC_API_KEY` 变量时，消息显示为：
1377 1414
1378```text theme={null}1415```text theme={null}
1379Administrator policy requires a Cloud gateway sign-in on this machine; the1416Administrator policy requires a Cloud gateway sign-in on this machine, but this session is configured with an API key from ANTHROPIC_API_KEY, which a gateway machine does not accept.
1380Anthropic-issued credential configured here (ANTHROPIC_API_KEY,1417
1381ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.1418To continue: unset ANTHROPIC_API_KEY (or run in a shell without it), then run claude and sign in with /login.
1382```1419```
1383 1420
1384**应该做什么：**1421**解决方法：**
1422
1423* 对于 `Not signed in to the Cloud gateway`，请运行 `/login` 并在 **Cloud gateway** 界面上完成登录
1424* 对于启动消息，请按照消息末尾的步骤移除该凭据
1425* 如果您认为这台机器不应要求使用网关，请让管理该机器的管理员从其托管设置中移除 `forceLoginMethod` 和 `forceLoginGatewayUrl`
1385 1426
1386* 运行 `/login` 并在 **Cloud gateway** 屏幕上完成登录1427在 v2.1.284 之前，启动消息会列出可能的凭据，而不是指出已配置的那一个。它以 `Administrator policy requires a Cloud gateway sign-in on this machine; the Anthropic-issued credential configured here (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.` 开头。如果您看到的是这种措辞且无法判断要移除哪个凭据，请更新到 v2.1.284 或更高版本，然后再次启动 `claude`。
1387* 对于启动消息，删除您配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 设置。要删除保存的 Console API 密钥，运行 `claude auth logout`，这也会删除保存的 claude.ai 登录。如果您使用 `CLAUDE_CODE_USE_*` 选择云提供商，会话然后以无登录启动。否则启动 `claude` 并运行 `/login`
1388* 如果您认为机器不应该需要网关，请要求管理该机器的管理员从其托管设置中删除 `forceLoginMethod` 和 `forceLoginGatewayUrl`
1389 1428
1390在 v2.1.265 上，回归也在某些 LLM 网关和代理配置中显示第一条消息，这些配置使用 API 密钥、`apiKeyHelper` 或自定义标头进行身份验证，即使机器上没有管理员要求。更新到 v2.1.266 或更高版本。您不需要更改您的配置。1429在 v2.1.265 上，一个回归问题还会在某些使用 API 密钥、`apiKeyHelper` 或自定义标头进行身份验证的 LLM 网关和代理配置中显示第一条消息，即使机器上没有管理员要求也是如此。请更新到 v2.1.266 或更高版本。您无需更改配置。
1391 1430
1392在 v2.1.261 之前，在将 `forceLoginMethod` 设置为 `"gateway"` 的机器上，Claude Code 使用剩余的保存登录而不是失败模型请求，并使用 `This machine's managed settings require a first-party login` 而不是启动消息报告配置的环境凭证。在 v2.1.265 之前，其托管设置仅设置 `forceLoginGatewayUrl` 的机器不需要网关登录，Claude Code 在那里使用剩余凭证。1431在 v2.1.261 之前，在将 `forceLoginMethod` 设置为 `"gateway"` 的机器上，Claude Code 会使用遗留的已保存登录，而不是让模型请求失败，并且会以 `This machine's managed settings require a first-party login` 报告已配置的环境凭据，而不是显示启动消息。
1393 1432
1394<h3 id="your-account-is-on-hold">1433<h3 id="your-account-is-on-hold">
1395 您的账户被冻结1434 您的账户已被暂停
1396</h3>1435</h3>
1397 1436
1398您的 Claude 账户背后的登录已被暂停。Claude Code 在尝试更新您保存的登录并了解冻结时显示第一条消息，在您在浏览器中完成的登录报告时显示第二条消息：1437您登录所用的 Claude 账户已被暂停。当 Claude Code 尝试续期您已保存的登录并获知暂停时，会显示第一条消息；当您在浏览器中完成的登录报告暂停时，会显示第二条消息：
1399 1438
1400```text theme={null}1439```text theme={null}
1401Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted1440Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
1402Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted1441Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted
1403```1442```
1404 1443
1405使用同一账户再次登录不会清除消息，因为冻结是在账户上而不是登录上。在 [非交互式模式](/docs/zh-CN/headless) (`-p`) 和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，结构化错误代码为 `account_on_hold`。在 v2.1.235 之前，Claude Code 将被冻结的账户报告为 [登录过期 · 请运行 /login](#login-expired)，其恢复步骤无法清除冻结。1444使用同一账户重新登录不会清除该消息，因为暂停针对的是账户而不是登录。在[非交互模式](/docs/zh-CN/headless)（`-p`）和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，结构化错误代码为 `account_on_hold`。在 v2.1.235 之前，Claude Code 会将被暂停的账户报告为 [Login expired · Please run /login](#login-expired)，而其恢复步骤无法解除暂停。
1406 1445
1407**应该做什么：**1446**解决方法：**
1408 1447
1409* 打开消息中的链接以查看冻结的详细信息或对其提出上诉1448* 打开消息中的链接，查看暂停的详细信息或提出申诉
1410* 如果您有另一个 Claude 账户或不受冻结影响的 API 密钥，您可以在冻结解决期间继续工作：使用该账户运行 `/login`，或使用 `ANTHROPIC_API_KEY` 设置密钥1449* 如果您有不受暂停影响的其他 Claude 账户或 API 密钥，可以在暂停解决期间继续工作：使用该账户运行 `/login`，或通过 `ANTHROPIC_API_KEY` 设置该密钥
1411 1450
1412<h3 id="anthropic-profile-login-expired">1451<h3 id="anthropic-profile-login-expired">
1413 Anthropic 配置文件登录过期1452 Anthropic 配置文件登录已过期
1414</h3>1453</h3>
1415 1454
1416Claude Code 通过 Anthropic 凭证配置文件进行身份验证，其保存的登录凭证已过期，且配置文件不包含 Claude Code 可用于更新它的刷新凭证。Claude Code 在本地停止每个请求而不重试，因为重试会读取相同的过期凭证。1455Claude Code 正在通过一个 Anthropic 凭据配置文件进行身份验证，该配置文件中已保存的登录凭据已过期，并且配置文件中没有 Claude Code 可用于续期的刷新凭据。Claude Code 会在本地停止每个请求且不重试，因为重试只会读取同一个已过期的凭据。
1417 1456
1418```text theme={null}1457```text theme={null}
1419Anthropic profile login expired · Re-authenticate your Anthropic profile1458Anthropic profile login expired · Re-authenticate your Anthropic profile
1420Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile1459Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile
1421```1460```
1422 1461
1423这仅在活跃凭证来自 Anthropic 凭证配置文件时出现，您使用 `ANTHROPIC_PROFILE` 环境变量选择该文件，Claude Code 从您的 Anthropic 配置目录中发现为活跃配置文件，或 Claude Code 在您 [不使用 API 密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key) 时写入。使用 `/login` 的 claude.ai 选项、API 密钥、持有者令牌（如 `ANTHROPIC_AUTH_TOKEN`）或第三方提供商进行身份验证的会话永远不会看到此消息。1462只有当生效的凭据来自 Anthropic 凭据配置文件时才会出现此消息，该配置文件可以是您通过 `ANTHROPIC_PROFILE` 环境变量选择的、Claude Code 在您的 Anthropic 配置目录中发现为活跃配置文件的，或是您[在没有 API 密钥的情况下登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)时 Claude Code 写入的。使用 API 密钥、bearer 令牌（例如 `ANTHROPIC_AUTH_TOKEN`）或第三方提供商进行身份验证的会话永远不会看到此消息。
1424 1463
1425在 [提供无密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key) 的机器上，运行 `/login`，选择 Anthropic Console 账户，并再次登录以更新无密钥 Console 登录或 Claude Platform CLI 的 `ant auth login` 写入的配置文件。Claude Code 替换该配置文件中的过期凭证。对于联合配置文件或另一个工具创建的配置文件，`/login` 不会更新凭证。您看到的形式取决于您是否显式选择了配置文件或 Claude Code 发现了它：1464在[提供无密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)的机器上，运行 `/login`，选择 Anthropic Console 账户并重新登录，即可续期由无密钥 Console 登录或 Claude Platform CLI 的 `ant auth login` 写入的配置文件。Claude Code 会替换该配置文件中已过期的凭据。对于联合身份配置文件或由其他工具创建的配置文件，`/login` 不会续期凭据。您看到哪种形式，取决于配置文件是您选择的还是 Claude Code 发现的：
1426 1465
1427* 当您显式设置 `ANTHROPIC_PROFILE` 时，消息以 `Re-authenticate your Anthropic profile` 结尾。1466* 当您显式设置了 `ANTHROPIC_PROFILE` 时，消息以 `Re-authenticate your Anthropic profile` 结尾。
1428* 当 Claude Code 从您的配置目录发现配置文件时，消息提供 `/login`，因为 Claude Code 给予工作的 `/login` 优先于发现的配置文件，然后改为使用您的 claude.ai 或 Console 账户进行身份验证。在 v2.1.234 之前，Claude Code 在这种情况下也显示 `Re-authenticate your Anthropic profile` 形式。1467* 当 Claude Code 从您的配置目录中发现该配置文件时，消息会提供 `/login` 选项，因为 Claude Code 让可用的 `/login` 优先于所发现的配置文件，然后改用您的 claude.ai 或 Console 账户进行身份验证。在 v2.1.234 之前，这种情况下 Claude Code 也会显示 `Re-authenticate your Anthropic profile` 形式。
1429 1468
1430**应该做什么：**1469**解决方法：**
1431 1470
1432* 再次登录到配置文件，然后重试：在 [提供无密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key) 的机器上，运行 `/login` 并为无密钥 Console 登录或 Claude Platform CLI 的 `ant auth login` 写入的配置文件选择 Anthropic Console 账户；对于其他配置文件，使用创建它们的工具1471* 重新登录该配置文件，然后重试：在[提供无密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)的机器上，对于由无密钥 Console 登录或 Claude Platform CLI 的 `ant auth login` 写入的配置文件，运行 `/login` 并选择 Anthropic Console 账户；对于其他配置文件，请使用创建它们的工具
1433* 如果管理员配置了配置文件的凭证，请要求他们颁发新凭证1472* 如果该配置文件的凭据由管理员预配，请让他们签发一个新的凭据
1434* 运行 `/status` 以确认活跃凭证源和配置文件名称1473* 运行 `/status`，确认当前生效的凭据来源和配置文件名称
1435* 要停止使用配置文件，如果您设置了 `ANTHROPIC_PROFILE`，则取消设置它，然后以其他方式进行身份验证，例如 `/login` 或 `ANTHROPIC_API_KEY`1474* 如需停止使用该配置文件，请取消设置 `ANTHROPIC_PROFILE`（如果您设置过），然后以其他方式进行身份验证，例如 `/login` 或 `ANTHROPIC_API_KEY`
1436 1475
1437<h3 id="oauth-scope-requirement">1476<h3 id="oauth-scope-requirement">
1438 OAuth 范围要求1477 OAuth 作用域要求
1439</h3>1478</h3>
1440 1479
1441存储的令牌早于较新功能需要的权限范围：1480已存储的令牌早于某个新功能所需的权限作用域：
1442 1481
1443```text theme={null}1482```text theme={null}
1444OAuth token does not meet scope requirement: user:profile1483OAuth token does not meet scope requirement: user:profile
1445```1484```
1446 1485
1447**应该做什么：**1486**解决方法：**
1448 1487
1449* 运行 `/login` 以获取具有当前范围的新令牌。您不需要先登出。1488* 运行 `/login` 获取具有当前作用域的新令牌。您无需先注销。
1450 1489
1451<h3 id="claude-ai-rejected-the-session-token">1490<h3 id="claude-ai-rejected-the-session-token">
1452 claude.ai 拒绝了会话令牌1491 claude.ai 拒绝了会话令牌
1453</h3>1492</h3>
1454 1493
1455[claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 请求失败，因为 claude.ai 拒绝了您的 Claude Code 登录中的令牌。被拒绝的令牌是您的登录，而不是连接器在 claude.ai 中的自己的授权，因此再次授权连接器不会解决它。在 `/mcp` 中，连接器显示为 `session token rejected`，其详细视图读作：1494[claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)请求失败，因为 claude.ai 拒绝了来自您 Claude Code 登录的令牌。被拒绝的令牌是您的登录，而不是该连接器在 claude.ai 中自身的授权，因此重新授权连接器并不能解决问题。在 `/mcp` 中，该连接器显示为 `session token rejected`，其详细信息视图显示：
1456 1495
1457```text theme={null}1496```text theme={null}
1458claude.ai rejected the session token. Run /login, then reconnect.1497claude.ai rejected the session token. Run /login, then reconnect.
1459```1498```
1460 1499
1461**应该做什么：**1500**解决方法：**
1462 1501
1463* 运行 `/login` 再次登录1502* 运行 `/login` 重新登录
1464* 从 `/mcp` 重新连接连接器，或运行 `/mcp reconnect <server>`。在您再次登录之前重新连接会使连接器处于相同状态。`/mcp` 面板的 **Reconnect** 选项报告 `your claude.ai session token was rejected`；输入的 `/mcp reconnect <server>` 形式报告成功重新连接，即使令牌仍然被拒绝。1503* 从 `/mcp` 重新连接该连接器，或运行 `/mcp reconnect <server>`。在重新登录之前重新连接，连接器会保持相同状态。`/mcp` 面板的 **Reconnect** 选项会报告 `your claude.ai session token was rejected`；而键入的 `/mcp reconnect <server>` 形式会报告重新连接成功，尽管令牌仍然被拒绝。
1465 1504
1466在 v2.1.222 之前，Claude Code 改为将连接器标记为需要身份验证，这指向您连接器的授权流程，即使完成它也不会解决状态。1505在 v2.1.222 之前，Claude Code 会将该连接器标记为需要身份验证，这会引导您进入连接器的授权流程，而完成该流程并不能解决此状态。
1467 1506
1468<h3 id="mcp-server-needs-you-to-sign-in-again">1507<h3 id="mcp-server-needs-you-to-sign-in-again">
1469 MCP 服务器需要您再次登录1508 MCP 服务器需要您重新登录
1470</h3>1509</h3>
1471 1510
1472远程 [MCP 服务器](/docs/zh-CN/mcp) 在会话中期拒绝了工具调用上的凭证，通常是因为登录或令牌过期或令牌缺少工具需要的权限。工具调用失败，`/mcp` 将服务器标记为 [需要身份验证](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)。1511某个远程 [MCP 服务器](/docs/zh-CN/mcp)在会话中途的工具调用中拒绝了凭据，通常是因为登录或令牌已过期，或令牌缺少工具所需的权限。该工具调用失败，`/mcp` 会将该服务器标记为[需要身份验证](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)。
1473 1512
1474对于您从 Claude Code 登录的服务器，包括 claude.ai 连接器，登录已过期或被撤销：1513对于您从 Claude Code 登录的服务器（包括 claude.ai 连接器），登录已过期或被撤销：
1475 1514
1476```text theme={null}1515```text theme={null}
1477MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)1516MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)
1478```1517```
1479 1518
1480运行 `/mcp`，选择服务器，并从其菜单再次登录。1519运行 `/mcp`，选择该服务器，然后从其菜单中重新登录。
1481 1520
1482对于使用 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 脚本配置的服务器，Claude Code 已在显示此之前重新运行 helper 并重试调用一次：1521对于配置了 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 脚本的服务器，Claude Code 在显示以下消息之前已经重新运行过该 helper 并重试了一次调用：
1483 1522
1484```text theme={null}1523```text theme={null}
1485MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)1524MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)
1486```1525```
1487 1526
1488检查 helper 返回服务器接受的凭证，然后从 `/mcp` 重新连接，这会再次运行 helper。1527检查该 helper 是否返回服务器接受的凭据，然后从 `/mcp` 重新连接，这会再次运行该 helper。
1489 1528
1490对于在其配置中具有静态 `Authorization` 标头的服务器：1529对于在配置中带有静态 `Authorization` 标头的服务器：
1491 1530
1492```text theme={null}1531```text theme={null}
1493MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)1532MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)
1494```1533```
1495 1534
1496在配置服务器的位置更新标头值，然后从 `/mcp` 重新连接。1535在配置该服务器的位置更新标头值，然后从 `/mcp` 重新连接。
1497 1536
1498在 v2.1.273 之前，过期的登录、`headersHelper` 和 `Authorization` 标头情况都显示 `MCP server "<name>" requires re-authorization (token expired)`。1537在 v2.1.273 之前，登录过期、`headersHelper` 和 `Authorization` 标头这几种情况都显示 `MCP server "<name>" requires re-authorization (token expired)`。
1499 1538
1500服务器也可以使用 HTTP 403 `insufficient_scope` 拒绝工具调用，以要求您授权范围，有时是您的令牌已列出的范围。消息命名该范围：1539服务器也可能以 HTTP 403 `insufficient_scope` 拒绝工具调用，要求您授权某个作用域，有时该作用域甚至已列在您的令牌中。消息会指出该作用域：
1501 1540
1502```text theme={null}1541```text theme={null}
1503MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate1542MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate
1504```1543```
1505 1544
1506运行 `/mcp`，选择服务器，并从其菜单再次进行身份验证。1545运行 `/mcp`，选择该服务器，然后从其菜单中重新进行身份验证。
1507 1546
1508当服务器的配置既不设置 [`oauth.scopes`](/docs/zh-CN/mcp#restrict-oauth-scopes) 也不设置 [`authServerMetadataUrl`](/docs/zh-CN/mcp#override-oauth-metadata-discovery) 时，Claude Code 请求服务器命名的范围。使用任一设置，Claude Code 改为请求该设置的范围。如果您固定了 `oauth.scopes`，在再次进行身份验证之前将缺失的范围添加到该列表。1547当服务器的配置既未设置 [`oauth.scopes`](/docs/zh-CN/mcp#restrict-oauth-scopes) 也未设置 [`authServerMetadataUrl`](/docs/zh-CN/mcp#override-oauth-metadata-discovery) 时，Claude Code 会请求服务器指出的作用域。如果设置了其中任一项，Claude Code 会改为请求该设置中的作用域。如果您固定了 `oauth.scopes`，请在重新进行身份验证之前将缺失的作用域添加到该列表中。
1509 1548
1510在 v2.1.274 之前，这种情况显示 `needs you to sign in again` 消息，在 v2.1.273 之前它显示 `requires re-authorization (token expired)`，如其他情况。1549在 v2.1.274 之前，这种情况显示 `needs you to sign in again` 消息；在 v2.1.273 之前，它与其他情况一样显示 `requires re-authorization (token expired)`。
1511 1550
1512<h3 id="mcp-server-url-is-missing-or-not-a-valid-url">1551<h3 id="mcp-server-url-is-missing-or-not-a-valid-url">
1513 MCP 服务器 URL 缺失或不是有效的 URL1552 MCP 服务器 URL 缺失或不是有效的 URL
1514</h3>1553</h3>
1515 1554
1516Claude Code 拒绝为远程 MCP 服务器启动 OAuth 登录，因为服务器的配置 `url` 不解析为 URL。除非 Claude Code 有更具体的配置问题要为服务器报告，否则在您的 shell 中运行 [`claude mcp login <name>`](/docs/zh-CN/mcp#authenticate-from-the-command-line) 会将拒绝打印为：1555Claude Code 拒绝为某个远程 MCP 服务器启动 OAuth 登录，因为该服务器配置的 `url` 无法解析为 URL。除非 Claude Code 对该服务器有更具体的配置问题需要报告，否则在您的 shell 中运行 [`claude mcp login <name>`](/docs/zh-CN/mcp#authenticate-from-the-command-line) 会将该拒绝输出为：
1517 1556
1518```text theme={null}1557```text theme={null}
1519Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.1558Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.
1520```1559```
1521 1560
1522**应该做什么：**1561**解决方法：**
1523 1562
1524* 将条目的 `url` 设置为服务器的真实端点，其中配置服务器，或设置其 [`${VAR}` 引用](/docs/zh-CN/mcp#environment-variable-expansion-in-mcp-json) 命名的环境变量，然后再次运行登录。1563* 在配置该服务器的位置，将该条目的 `url` 设置为服务器的真实端点，或设置其 [`${VAR}` 引用](/docs/zh-CN/mcp#environment-variable-expansion-in-mcp-json)所指的环境变量，然后再次运行登录。
1525 1564
1526<h3 id="issuer-mismatch-in-authorization-response">1565<h3 id="issuer-mismatch-in-authorization-response">
1527 授权响应中的发行者不匹配1566 授权响应中的颁发者不匹配
1528</h3>1567</h3>
1529 1568
1530在 [MCP OAuth 登录](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 期间，授权服务器重定向回 Claude Code，其中 `iss` 参数不命名 Claude Code 从服务器的 OAuth 元数据期望的发行者。此步骤中的错误发行者是授权服务器混合攻击的样子，因此 Claude Code 失败登录而不是交换授权代码。Claude Code 在浏览器登录后在 `/mcp` 服务器菜单中显示错误：1569在 [MCP OAuth 登录](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)期间，授权服务器重定向回 Claude Code 时所携带的 `iss` 参数与 Claude Code 根据服务器 OAuth 元数据所期望的颁发者不一致。此步骤中出现错误的颁发者正是授权服务器混淆攻击（mix-up attack）的表现形式，因此 Claude Code 会让登录失败，而不是交换授权码。Claude Code 会在浏览器登录后，在 `/mcp` 服务器菜单中显示该错误：
1531 1570
1532```text theme={null}1571```text theme={null}
1533Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"1572Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"
1534```1573```
1535 1574
1536`expected` 是来自服务器的 OAuth 元数据的发行者，`received` 是重定向携带的 `iss` 值。其重定向不携带 `iss` 参数的登录通过检查，除非服务器的元数据设置 `authorization_response_iss_parameter_supported`，在这种情况下 Claude Code 失败登录。1575`expected` 是来自服务器 OAuth 元数据的颁发者，`received` 是重定向所携带的 `iss` 值。重定向未携带 `iss` 参数的登录会通过检查，除非服务器的元数据设置了 `authorization_response_iss_parameter_supported`，这种情况下 Claude Code 会让登录失败。
1537 1576
1538**应该做什么：**1577**解决方法：**
1539 1578
1540* 从 `/mcp` 再次尝试登录1579* 从 `/mcp` 再次尝试登录
1541* 如果错误重复，将其报告给服务器操作员。修复是服务器端的：授权服务器必须在 `iss` 参数中返回与在其元数据中宣传的相同发行者1580* 如果错误重复出现，请向服务器运营方报告。需要在服务器端修复：授权服务器必须在 `iss` 参数中返回与其元数据中公布的相同的颁发者
1542* 要在修复服务器时连接，使用 [`MCP_SDK_GENERATION=v1`](/docs/zh-CN/env-vars) 启动 Claude Code，其 [运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 不运行此检查。这消除了对混合攻击的保护，因此更喜欢服务器端修复1581* 如需在服务器修复期间进行连接，请使用 [`MCP_SDK_GENERATION=v1`](/docs/zh-CN/env-vars) 启动 Claude Code，其[运行时](/docs/zh-CN/mcp#mcp-client-runtimes)不执行此检查。这会移除一项针对混淆攻击的防护，因此请优先采用服务器端修复
1543 1582
1544在 v2.1.232 之前，Claude Code 仅在逐步推出中或当您设置 `MCP_SDK_GENERATION=v2` 时使用 v2 运行时。1583在 v2.1.232 之前，Claude Code 仅在逐步推出时或您设置 `MCP_SDK_GENERATION=v2` 时才使用 v2 运行时。
1545 1584
1546<h3 id="refusing-to-send-credentials-to-non-https-token-endpoint">1585<h3 id="refusing-to-send-credentials-to-non-https-token-endpoint">
1547 拒绝向非 https 令牌端点发送凭证1586 拒绝向非 https 令牌端点发送凭据
1548</h3>1587</h3>
1549 1588
1550在 [v2 运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 上，Claude Code 仅向通过 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 处提供的令牌端点发送 [MCP OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 令牌请求。此消息意味着服务器的令牌端点都不是，因此 Claude Code 在发送请求前停止。这发生在浏览器登录之后，因此浏览器步骤首先成功，并且每当 Claude Code 刷新服务器的令牌时再次发生。1589在 [v2 运行时](/docs/zh-CN/mcp#mcp-client-runtimes)上，Claude Code 只会将 [MCP OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 令牌请求发送到通过 HTTPS 提供服务的令牌端点，或位于 `localhost`、`127.0.0.1` 或 `::1` 的令牌端点。此消息表示服务器的令牌端点两者都不是，因此 Claude Code 在发送请求前就停止了。这发生在浏览器登录之后，因此浏览器步骤会先成功，并且每当 Claude Code 刷新该服务器的令牌时都会再次发生。
1551 1590
1552在其完整形式中，消息来自 MCP SDK 并引用它拒绝的令牌端点。在调试日志中，它遵循 `Error during auth completion:` 用于登录或 `Token refresh failed:` 用于刷新。在您的 shell 中，`claude mcp login <name>` 在 `Couldn't complete authentication for "<name>":` 之后打印它，在会话中，`/mcp` 在服务器的菜单下显示它：1591该消息的完整形式来自 MCP SDK，并会引用它拒绝的令牌端点。在调试日志中，对于登录，它跟在 `Error during auth completion:` 之后；对于刷新，它跟在 `Token refresh failed:` 之后。在您的 shell 中，`claude mcp login <name>` 会在 `Couldn't complete authentication for "<name>":` 之后输出它；在会话中，`/mcp` 会在服务器菜单下显示它：
1553 1592
1554```text theme={null}1593```text theme={null}
1555Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).1594Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).
1556```1595```
1557 1596
1558Claude Code 将具有查询字符串或长随机外观路径段的服务器 URL 视为可能的秘密。对于这样的服务器，它在显示或记录它们之前会编辑 MCP SDK 引发的登录错误。此错误然后读作可能在版本之间更改的短名称，例如 `io`，后跟 `from the MCP SDK for` 和编辑的服务器 URL。MCP SDK 的其他错误在那里采用相同的形状。编辑的消息只能是此错误，当服务器的令牌端点是纯 `http://` 在 `localhost`、`127.0.0.1` 或 `::1` 以外的地址时。1597Claude Code 会将带有查询字符串或较长的随机外观路径段的服务器 URL 视为可能是机密的。对于此类服务器，它会在显示或记录 MCP SDK 引发的登录错误之前对其进行脱敏。此时该错误会显示为一个可能因版本而变化的简短名称（例如 `io`），后跟 `from the MCP SDK for` 和经过脱敏的服务器 URL。来自 MCP SDK 的其他错误在这种情况下也采用相同的形式。只有当服务器的令牌端点是位于 `localhost`、`127.0.0.1` 或 `::1` 以外地址的普通 `http://` 时，脱敏后的消息才可能是此错误。
1559 1598
1560**应该做什么：**1599**解决方法：**
1561 1600
1562* 通过 HTTPS 提供该令牌端点，例如通过将服务器放在终止 TLS 的反向代理或隧道后面，并配置服务器以宣传 `https://` 地址1601* 通过 HTTPS 提供该令牌端点，例如将服务器置于终止 TLS 的反向代理或隧道之后，并配置服务器公布 `https://` 地址
1563* 要在不更改服务器的情况下连接，使用 [`MCP_SDK_GENERATION=v1`](/docs/zh-CN/env-vars) 启动 Claude Code，其 [运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 不应用此规则并通过纯 HTTP 发送令牌请求。该选择持续到您退出并应用于每个服务器。v1 运行时也跳过 [发行者检查](#issuer-mismatch-in-authorization-response)，因此更喜欢通过 HTTPS 提供端点1602* 如需在不更改服务器的情况下进行连接，请使用 [`MCP_SDK_GENERATION=v1`](/docs/zh-CN/env-vars) 启动 Claude Code，其[运行时](/docs/zh-CN/mcp#mcp-client-runtimes)不应用此规则，会通过普通 HTTP 发送令牌请求。该选择会持续到您退出为止，并适用于所有服务器。v1 运行时还会跳过[颁发者检查](#issuer-mismatch-in-authorization-response)，因此请优先通过 HTTPS 提供该端点
1564 1603
1565<h3 id="aws-credentials-expired-or-invalid">1604<h3 id="aws-credentials-expired-or-invalid">
1566 AWS 凭证已过期或无效1605 AWS 凭据已过期或无效
1567</h3>1606</h3>
1568 1607
1569您的 AWS 会话令牌已过期或被拒绝。此消息出现在来自 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 的 401，这是这些提供商报告过期安全令牌的方式。1608您的 AWS 会话令牌已过期或被拒绝。当 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)返回 401 时会出现此消息，这是这些提供商报告安全令牌过期的方式。
1570 1609
1571中间的操作提示因您的设置而异。稳定部分是前导 `AWS credentials expired or invalid`：1610中间的操作提示因您的设置而异。稳定不变的部分是开头的 `AWS credentials expired or invalid`：
1572 1611
1573```text theme={null}1612```text theme={null}
1574AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...1613AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...
1575```1614```
1576 1615
1577在 v2.1.273 之前，仅当配置了 `awsAuthRefresh` 时才出现此消息。1616在 v2.1.273 之前，只有在配置了 `awsAuthRefresh` 时才会出现此消息。
1578 1617
1579**应该做什么：**1618**解决方法：**
1580 1619
1581* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员1620* 如果提示说明凭据由此环境管理，则凭据归启动 Claude Code 的应用所有，此处的其他步骤不适用：请重试，或联系您的管理员
1582* 如果设置了 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)，在另一个终端中运行消息中命名的命令，例如 `aws sso login --profile myprofile`，并完成浏览器登录，然后重试。否则自己刷新您使用的 AWS 凭证：您的 SSO 登录、访问密钥、API 密钥或代理令牌1621* 如果设置了 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)，请在另一个终端中运行消息中指出的命令（例如 `aws sso login --profile myprofile`）并完成浏览器登录，然后重试。否则，请自行刷新您所使用的 AWS 凭据：您的 SSO 登录、访问密钥、API 密钥或代理令牌
1583* 在交互式会话中设置 `awsAuthRefresh`，您可以改为运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials** 以运行相同的命令而不重新启动 Claude Code。请参阅 [配置 AWS 凭证](/docs/zh-CN/claude-platform-on-aws#1-configure-aws-credentials)1622* 在设置了 `awsAuthRefresh` 的交互式会话中，您也可以运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials**，无需重启 Claude Code 即可运行同一命令。请参阅[配置 AWS 凭据](/docs/zh-CN/claude-platform-on-aws#1-configure-aws-credentials)
1584* 如果刷新命令成功后错误重复，通过在同一 shell 和配置文件中使用 `aws sts get-caller-identity` 在 Claude Code 外确认身份有效1623* 如果刷新命令成功后错误仍然重复出现，请在同一 shell 和 profile 中运行 `aws sts get-caller-identity`，确认该身份在 Claude Code 之外有效
1585 1624
1586<h3 id="aws-authentication-failed">1625<h3 id="aws-authentication-failed">
1587 AWS 身份验证失败1626 AWS 身份验证失败
1589 1628
1590您的 AWS 提供商返回了 403，或 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 返回了 401。1629您的 AWS 提供商返回了 403，或 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 返回了 401。
1591 1630
1592Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺失 IAM 权限的 `AccessDeniedException`。Claude Code 无法区分这两个原因。1631Amazon Bedrock 将安全令牌过期报告为 403，但 403 也是它报告授权被拒绝的方式，例如因缺少 IAM 权限而产生的 `AccessDeniedException`。Claude Code 无法区分这两种原因。
1593 1632
1594来自 Amazon Bedrock 的 401 也在这里而不是在 [AWS 凭证已过期或无效](#aws-credentials-expired-or-invalid) 下，因为 Amazon Bedrock 不将过期令牌报告为 401。来自该端点的 401 通常来自请求路径中的其他内容，例如公司代理。1633来自 Amazon Bedrock 的 401 也会归到这里，而不是[AWS 凭据已过期或无效](#aws-credentials-expired-or-invalid)，因为 Amazon Bedrock 不会将令牌过期报告为 401。来自该端点的 401 通常来自请求路径中的其他环节，例如企业代理。
1595 1634
1596凭证刷新修复过期令牌，无法修复其他原因，因此消息提供两者：1635刷新凭据可以修复令牌过期，但无法修复其他原因，因此消息同时提供了两种方案：
1597 1636
1598```text theme={null}1637```text theme={null}
1599AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...1638AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...
1600```1639```
1601 1640
1602中间的操作提示因您的设置而异。稳定部分是前导 `AWS authentication failed`。1641中间的操作提示因您的设置而异。稳定不变的部分是开头的 `AWS authentication failed`。
1603 1642
1604当 403 是 Amazon Bedrock 的答案，说您无权访问具有指定模型 ID 的模型时，提示改为告诉您在 Amazon Bedrock 控制台中为您的账户和区域启用模型。1643当 403 是 Amazon Bedrock 表示您无权访问指定模型 ID 的模型时，提示会改为告诉您在 Amazon Bedrock 控制台中为您的账户和区域启用该模型。
1605 1644
1606在 v2.1.273 之前，仅当配置了 `awsAuthRefresh` 时才出现此消息。1645在 v2.1.273 之前，只有在配置了 `awsAuthRefresh` 时才会出现此消息。
1607 1646
1608**应该做什么：**1647**解决方法：**
1609 1648
1610* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员1649* 如果提示说明凭据由此环境管理，则凭据归启动 Claude Code 的应用所有，此处的其他步骤不适用：请重试，或联系您的管理员
1611* 刷新您的 AWS 凭证以防过期凭证是原因：运行消息中命名的 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) 命令（当设置时），或自己刷新您的 SSO 登录、访问密钥、API 密钥或代理令牌1650* 刷新您的 AWS 凭据，以防原因是凭据过期：如果设置了 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration)，请运行消息中指出的该命令；否则请自行刷新您的 SSO 登录、访问密钥、API 密钥或代理令牌
1612* 如果您的凭证是最新的，确认 [IAM 配置](/docs/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用1651* 如果您的凭据是最新的，请确认 [IAM 配置](/docs/zh-CN/amazon-bedrock#iam-configuration)中的 IAM 权限已附加到您正在使用的身份，并且所选模型已为您的账户和区域启用
1613* 运行 `aws sts get-caller-identity` 以确认您的请求使用哪个身份1652* 运行 `aws sts get-caller-identity`，确认您的请求使用的是哪个身份
1614 1653
1615<h3 id="google-cloud-credentials-expired-or-invalid">1654<h3 id="google-cloud-credentials-expired-or-invalid">
1616 Google Cloud 凭证已过期或无效1655 Google Cloud 凭据已过期或无效
1617</h3>1656</h3>
1618 1657
1619您的 [Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) Google Cloud 凭证已过期或被拒绝：请求返回了 401，这是 Agent Platform 报告凭证过期的方式。1658您用于 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 的 Google Cloud 凭据已过期或被拒绝：请求返回了 401，这是 Agent Platform 报告凭据过期的方式。
1620 1659
1621中间的操作提示因您的设置而异。稳定部分是前导 `Google Cloud credentials expired or invalid`：1660中间的操作提示因您的设置而异。稳定不变的部分是开头的 `Google Cloud credentials expired or invalid`：
1622 1661
1623```text theme={null}1662```text theme={null}
1624Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...1663Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...
1625```1664```
1626 1665
1627**应该做什么：**1666**解决方法：**
1628 1667
1629* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员1668* 如果提示说明凭据由此环境管理，则凭据归启动 Claude Code 的应用所有，此处的其他步骤不适用：请重试，或联系您的管理员
1630* 如果您使用应用默认凭证进行身份验证，运行消息中命名的 [`gcpAuthRefresh`](/docs/zh-CN/google-vertex-ai#advanced-credential-configuration) 命令或 `gcloud auth application-default login`，并完成登录，然后重试1669* 如果您使用应用默认凭据进行身份验证，请运行消息中指出的 [`gcpAuthRefresh`](/docs/zh-CN/google-vertex-ai#advanced-credential-configuration) 命令或 `gcloud auth application-default login` 并完成登录，然后重试
1631* 如果您通过设置了 `CLAUDE_CODE_SKIP_VERTEX_AUTH` 的 [LLM 网关](/docs/zh-CN/llm-gateway) 路由，刷新 `ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_CUSTOM_HEADERS` 中的网关令牌，然后重试1670* 如果您在设置了 `CLAUDE_CODE_SKIP_VERTEX_AUTH` 的情况下通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由，请刷新 `ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_CUSTOM_HEADERS` 中的网关令牌，然后重试
1632* 如果您使用服务账户密钥文件进行身份验证，确认 `GOOGLE_APPLICATION_CREDENTIALS` 指向有效密钥。请参阅 [配置 GCP 凭证](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials)1671* 如果您使用服务账号密钥文件进行身份验证，请确认 `GOOGLE_APPLICATION_CREDENTIALS` 指向有效的密钥。请参阅[配置 GCP 凭据](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials)
1633* 如果刷新后错误重复，通过在同一 shell 中使用 `gcloud auth application-default print-access-token` 在 Claude Code 外确认身份有效1672* 如果刷新后错误仍然重复出现，请在同一 shell 中运行 `gcloud auth application-default print-access-token`，确认该身份在 Claude Code 之外可以正常工作
1634 1673
1635在 v2.1.273 之前，来自 Agent Platform 的 401 显示通用 `Please run /login` 或 `Failed to authenticate` 消息，无法刷新 Google Cloud 凭证。1674在 v2.1.273 之前，来自 Agent Platform 的 401 会改为显示通用的 `Please run /login` 或 `Failed to authenticate` 消息，而这些消息无法刷新 Google Cloud 凭据。
1636 1675
1637<h3 id="google-cloud-authentication-failed">1676<h3 id="google-cloud-authentication-failed">
1638 Google Cloud 身份验证失败1677 Google Cloud authentication failed
1639</h3>1678</h3>
1640 1679
1641[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 返回了 403，它用于授权拒绝而不是过期凭证。通常您进行身份验证的身份缺少 IAM 权限，或模型未为您的项目启用。1680[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 返回了 403，该平台使用此状态码表示授权被拒绝，而非凭据过期。通常是您用于身份验证的身份缺少某项 IAM 权限，或者您的项目未启用该模型。
1642 1681
1643中间的操作提示因您的设置而异。稳定部分是前导 `Google Cloud authentication failed`：1682中间的操作提示因您的设置而异。固定不变的部分是开头的 `Google Cloud authentication failed`：
1644 1683
1645```text theme={null}1684```text theme={null}
1646Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...1685Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...
1647```1686```
1648 1687
1649**应该做什么：**1688**解决方法：**
1650 1689
1651* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员1690* 如果提示表明凭据由当前环境管理，则凭据归启动 Claude Code 的应用所有，此处的其他步骤不适用：请重试，或联系您的管理员
1652* 确认 [IAM 配置](/docs/zh-CN/google-vertex-ai#iam-configuration) 中的角色已授予您进行身份验证的身份1691* 确认 [IAM 配置](/docs/zh-CN/google-vertex-ai#iam-configuration)中的角色已授予您用于身份验证的身份
1653* 确认模型已为您的项目启用。请参阅 [请求模型访问](/docs/zh-CN/google-vertex-ai#2-request-model-access)1692* 确认您的项目已启用该模型。请参阅[申请模型访问权限](/docs/zh-CN/google-vertex-ai#2-request-model-access)
1654 1693
1655在 v2.1.273 之前，来自 Agent Platform 的 403 显示通用 `Please run /login` 或 `Failed to authenticate` 消息，无法刷新 Google Cloud 凭证。1694在 v2.1.273 之前，来自 Agent Platform 的 403 会改为显示通用的 `Please run /login` 或 `Failed to authenticate` 消息，而这些操作无法刷新 Google Cloud 凭据。
1656 1695
1657<h3 id="microsoft-foundry-authentication-failed">1696<h3 id="microsoft-foundry-authentication-failed">
1658 Microsoft Foundry 身份验证失败1697 Microsoft Foundry authentication failed
1659</h3>1698</h3>
1660 1699
1661[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 返回了 401 或 403：请求上的 Azure 凭证被拒绝，或其背后的身份无权访问 Foundry 资源。`/login` 无法铸造 Azure 凭证。中间的操作提示因您的设置而异。稳定部分是前导 `Microsoft Foundry authentication failed`：1700[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 返回了 401 或 403：请求中的 Azure 凭据被拒绝，或者其背后的身份无权访问 Foundry 资源。`/login` 无法生成 Azure 凭据。中间的操作提示因您的设置而异。固定不变的部分是开头的 `Microsoft Foundry authentication failed`：
1662 1701
1663```text theme={null}1702```text theme={null}
1664Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...1703Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...
1665```1704```
1666 1705
1667**应该做什么：**1706**解决方法：**
1668 1707
1669* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员1708* 如果提示表明凭据由当前环境管理，则凭据归启动 Claude Code 的应用所有，此处的其他步骤不适用：请重试，或联系您的管理员
1670* 刷新您在 [配置 Azure 凭证](/docs/zh-CN/microsoft-foundry#2-configure-azure-credentials) 中配置的凭证：轮换 `ANTHROPIC_FOUNDRY_API_KEY`、铸造新的 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 或运行 `az login` 以便默认 Microsoft Entra 凭证链可以再次登录1709* 刷新您在[配置 Azure 凭据](/docs/zh-CN/microsoft-foundry#2-configure-azure-credentials)中配置的凭据：轮换 `ANTHROPIC_FOUNDRY_API_KEY`、生成新的 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`，或运行 `az login` 以便默认的 Microsoft Entra 凭据链可以重新登录
1671* 如果凭证是最新的，确认身份有权访问 Foundry 资源。请参阅 [Azure RBAC 配置](/docs/zh-CN/microsoft-foundry#azure-rbac-configuration)1710* 如果凭据有效，请确认该身份有权访问 Foundry 资源。请参阅 [Azure RBAC 配置](/docs/zh-CN/microsoft-foundry#azure-rbac-configuration)
1672 1711
1673在 v2.1.273 之前，来自 Microsoft Foundry 的 401 或 403 显示通用 `Please run /login` 或 `Failed to authenticate` 消息，无法刷新 Azure 凭证。1712在 v2.1.273 之前，来自 Microsoft Foundry 的 401 或 403 会改为显示通用的 `Please run /login` 或 `Failed to authenticate` 消息，而这些操作无法刷新 Azure 凭据。
1674 1713
1675<h3 id="could-not-load-aws-or-google-cloud-credentials">1714<h3 id="could-not-load-aws-or-google-cloud-credentials">
1676 无法加载 AWS 或 Google Cloud 凭证1715 Could not load AWS or Google Cloud credentials
1677</h3>1716</h3>
1678 1717
1679Claude Code 无法从 AWS 凭证提供商链或从它运行的机器上的 Google 应用默认凭证获取可用凭证，因此没有请求到达您的云提供商。Claude Code 清除其缓存凭证并在显示此消息之前重试两次。`·` 之后的详细信息命名具体原因，例如过期的 SSO 会话、缺失的应用默认凭证报告为 `Could not load the default credentials` 或被撤销的登录报告为 `invalid_grant`：1718Claude Code 无法在其运行的机器上从 AWS 凭据提供程序链或 Google 应用默认凭据中获取可用的凭据，因此没有请求到达您的云提供商。Claude Code 会清除其缓存的凭据并重试两次，然后才显示此消息。`·` 之后的详细信息会指出具体原因，例如 SSO 会话已过期、缺少应用默认凭据（报告为 `Could not load the default credentials`），或登录已被撤销（报告为 `invalid_grant`）：
1680 1719
1681```text theme={null}1720```text theme={null}
1682API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.1721API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
1683API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.1722API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.
1684```1723```
1685 1724
1686在 [非交互式模式](/docs/zh-CN/headless) 中使用 `-p` 和在 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，结构化错误代码为 `cloud_credential_error`。在 v2.1.267 之前，消息仅显示 `API Error:` 之后的详细信息文本，结构化代码为 `server_error` 或 `unknown`。1725在使用 `-p` 的[非交互模式](/docs/zh-CN/headless)和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，结构化错误代码为 `cloud_credential_error`。在 v2.1.267 之前，该消息仅显示 `API Error:` 之后的详细文本，结构化代码为 `server_error` 或 `unknown`。
1687 1726
1688**应该做什么：**1727**解决方法：**
1689 1728
1690* 运行您的提供商的登录命令，例如 `aws sso login --profile myprofile` 或 `gcloud auth application-default login`，然后重试。[Bedrock、Agent Platform 或 Foundry 凭证未加载](/docs/zh-CN/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading) 显示如何在 Claude Code 外确认凭证1729* 运行您的提供商的登录命令，例如 `aws sso login --profile myprofile` 或 `gcloud auth application-default login`，然后重试。[Bedrock、Agent Platform 或 Foundry 凭据无法加载](/docs/zh-CN/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading)介绍了如何在 Claude Code 之外确认凭据
1691* 如果详细信息读作 `AWS default-chain credential resolve timed out`，链挂起而不是失败，因此改为遵循 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out)1730* 如果详细信息为 `AWS default-chain credential resolve timed out`，则表示凭据链卡住了而非失败，请改为按照 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out) 进行处理
1692 1731
1693<h3 id="aws-default-chain-credential-resolve-timed-out">1732<h3 id="aws-default-chain-credential-resolve-timed-out">
1694 AWS default-chain credential resolve 超时1733 AWS default-chain credential resolve timed out
1695</h3>1734</h3>
1696 1735
1697AWS 默认凭证提供商链在 60 秒内未生成凭证，因此 Claude Code 停止了解析并失败了请求。此超时是 [无法加载 AWS 或 Google Cloud 凭证](#could-not-load-aws-or-google-cloud-credentials) 的一个原因。故障是本地凭证解析：请求从未到达 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此错误出现之前清除其 [凭证缓存](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout) 并重试，因此当您看到它时链已在重复尝试中停滞。1736AWS 默认凭据提供程序链未能在 60 秒内生成凭据，因此 Claude Code 停止了解析并使请求失败。此超时是 [Could not load AWS or Google Cloud credentials](#could-not-load-aws-or-google-cloud-credentials) 的原因之一。失败发生在本地凭据解析阶段：请求从未到达 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 会在此错误出现之前清除其[凭据缓存](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)并重试，因此当您看到此错误时，凭据链已在多次尝试中停滞。
1698 1737
1699```text theme={null}1738```text theme={null}
1700API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.1739API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.
1701```1740```
1702 1741
1703常见原因是您的 AWS 配置文件中的 `credential_process` 命令等待它无法接收的输入，以及其实例元数据服务 (IMDS) 从不回答链探针的容器或 VM。1742常见原因包括：AWS 配置文件中的 `credential_process` 命令在等待它无法接收的输入，以及容器或虚拟机的实例元数据服务（IMDS）始终未响应凭据链的探测。
1704 1743
1705在 v2.1.267 之前，消息读作 `API Error: AWS default-chain credential resolve timed out`。1744在 v2.1.267 之前，该消息为 `API Error: AWS default-chain credential resolve timed out`。
1706在 v2.1.207 之前，停滞的链使请求无限期等待而不是失败。1745在 v2.1.207 之前，停滞的凭据链会让请求无限期等待，而不是失败。
1707 1746
1708**应该做什么：**1747**解决方法：**
1709 1748
1710* 在同一 shell 中使用相同的 `AWS_PROFILE` 运行 `aws sts get-caller-identity`。如果它也挂起，修复配置文件；提示交互式的 `credential_process` 命令是常见原因。1749* 在同一 shell 中使用相同的 `AWS_PROFILE` 运行 `aws sts get-caller-identity`。如果它也卡住，请修复该配置文件；以交互方式提示输入的 `credential_process` 命令是常见原因。
1711* 在启动 Claude Code 之前完成登录步骤，例如 `aws sso login --profile myprofile`，以便链从本地 SSO 缓存而不是等待浏览器流解析1750* 在启动 Claude Code 之前完成登录步骤，例如 `aws sso login --profile myprofile`
1712* 如果您的链运行合法需要超过 60 秒的交互式登录，例如通过 `aws-vault` 等包装器的 SSO 与 MFA，使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制1751* 如果您的凭据链运行的交互式登录确实需要超过 60 秒，例如通过 `aws-vault` 等包装工具进行带 MFA 的 SSO，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高该限制
1713 1752
1714<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">1753<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">
1715 Bedrock 设置验证超时等待 AWS1754 Bedrock setup verification timed out waiting for AWS
1716</h3>1755</h3>
1717 1756
1718在 [Bedrock 设置向导](/docs/zh-CN/amazon-bedrock#sign-in-with-bedrock) 的凭证验证期间对 AWS 的调用，例如凭证查找或身份检查，未在 60 秒限制内完成。向导停止等待并失败验证步骤：1757在 [Bedrock 设置向导](/docs/zh-CN/amazon-bedrock#sign-in-with-bedrock)的凭据验证过程中，对 AWS 的某个调用（例如凭据查找或身份检查）未能在 60 秒限制内完成。向导停止等待，并使验证步骤失败：
1719 1758
1720```text theme={null}1759```text theme={null}
1721Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.1760Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.
1722```1761```
1723 1762
1724该数字反映您的限制：默认 60 秒，或您在 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 中设置的值。1763其中的数字反映您的限制：默认为 60 秒，或您在 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 中设置的值。
1725 1764
1726常见原因是停滞对 AWS 的请求的网络或代理，包括 SSO 令牌刷新，以及仍在等待您看不到的输入的凭证 helper。仅当 helper 合法需要更多时间时才提高限制。1765常见原因包括：网络或代理使发往 AWS 的请求（包括 SSO 令牌刷新）停滞，以及凭据助手仍在等待您看不到的输入。仅当助手确实需要更多时间时才提高该限制。
1727 1766
1728对 AWS 的单个停滞请求也可能在其自己的每请求超时上失败，这在同一步骤上显示较短的消息：1767发往 AWS 的单个停滞请求也可能因其自身的单次请求超时而失败，此时同一步骤会显示一条较短的消息：
1729 1768
1730```text theme={null}1769```text theme={null}
1731A request to AWS timed out. Check your network and proxy settings, then try again.1770A request to AWS timed out. Check your network and proxy settings, then try again.
1732```1771```
1733 1772
1734当相同的超时在模型固定步骤上发生时，向导将模型标记为 `unreachable` 而不是显示任一消息。1773当相同的超时发生在模型固定步骤时，向导会将模型标记为 `unreachable`，而不显示上述任一消息。
1735 1774
1736**应该做什么：**1775**解决方法：**
1737 1776
1738* 在同一 shell 中运行 `aws sts get-caller-identity`。如果它也挂起，停滞在 Claude Code 外，在您的网络、您的代理或您的 AWS 配置文件中的凭证 helper 中；首先修复它。1777* 在同一 shell 中运行 `aws sts get-caller-identity`。如果它也卡住，则停滞发生在 Claude Code 之外，位于您的网络、代理或 AWS 配置文件中的凭据助手；请先修复该问题。
1739* 在打开向导之前完成任何交互式登录，例如 `aws sso login --profile myprofile`1778* 在打开向导之前完成所有交互式登录，例如 `aws sso login --profile myprofile`
1740* 如果您的 AWS 配置文件中的凭证 helper 合法需要超过 60 秒来提示您，使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制1779* 如果 AWS 配置文件中的凭据助手确实需要超过 60 秒来提示您，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高该限制
1741 1780
1742<h3 id="cloud-gateway-session-expired">1781<h3 id="cloud-gateway-session-expired">
1743 Cloud gateway 会话已过期1782 Cloud gateway session expired
1744</h3>1783</h3>
1745 1784
1746您通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录，此机器上保存的网关会话已过期且无法更新，或网关不再接受它，例如在网关的 [JWT 密钥被替换](/docs/zh-CN/claude-apps-gateway-deploy#jwt-secret-rotation) 后。如果您在交互式启动 `claude` 时看到此行，会话已打开且未登录网关：1785您通过 [Claude apps 网关](/docs/zh-CN/claude-apps-gateway)登录，而保存在此机器上的网关会话已过期且无法续期，或者网关不再接受该会话，例如在网关的 [JWT 密钥被替换](/docs/zh-CN/claude-apps-gateway-deploy#jwt-secret-rotation)之后。如果您在以交互方式启动 `claude` 时看到这行消息，则表示会话已以未登录网关的状态打开：
1747 1786
1748```text theme={null}1787```text theme={null}
1749Cloud gateway session expired — run /login to reconnect.1788Cloud gateway session expired — run /login to reconnect.
1750```1789```
1751 1790
1752相同的行可能在会话中期出现，当网关凭证过期且 Claude Code 无法更新它时。1791当网关凭据过期且 Claude Code 无法续期时，同一行消息也可能在会话中途出现。
1753 1792
1754在 [非交互式](/docs/zh-CN/headless) 运行、后台或其他无人值守会话或 `claude` 子命令（除 `claude auth` 外）中，Claude Code 改为在网关不再接受会话时以此消息退出：1793在[非交互](/docs/zh-CN/headless)运行、后台或其他无人值守会话，或除 `claude auth` 以外的 `claude` 子命令中，当网关不再接受该会话时，Claude Code 会改为显示以下消息并退出：
1755 1794
1756```text theme={null}1795```text theme={null}
1757Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.1796Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.
1758```1797```
1759 1798
1760**应该做什么：**1799**解决方法：**
1761 1800
1762* 在会话中运行 `/login` 并完成浏览器登录1801* 在会话中运行 `/login` 并完成浏览器登录
1763* 对于非交互式启动，在同一环境中启动 `claude`，运行 `/login`，然后重新运行您的命令1802* 对于非交互式启动，请在同一环境中启动 `claude`，运行 `/login`，然后重新运行您的命令
1764 1803
1765<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">1804<h3 id="sign-in-timed-out-while-waiting-for-you-to-continue">
1766 登录超时，等待您继续1805 Sign-in timed out while waiting for you to continue
1767</h3>1806</h3>
1768 1807
1769在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录期间，网关命名了登录的账户，Claude Code 要求您在保存凭证之前确认它。您将确认保持打开状态超过登录自己的过期，网关未颁发可更新它的刷新令牌，因此当您继续时 Claude Code 未存储任何内容：1808在 [Claude apps 网关](/docs/zh-CN/claude-apps-gateway)登录过程中，网关给出了已登录的账户，Claude Code 在保存凭据之前请您确认该账户。您让确认界面保持打开的时间超过了该次登录自身的有效期，且网关未签发可用于续期的刷新令牌，因此当您继续时，Claude Code 未存储任何内容：
1770 1809
1771```text theme={null}1810```text theme={null}
1772Sign-in timed out while waiting for you to continue. Try again.1811Sign-in timed out while waiting for you to continue. Try again.
1773```1812```
1774 1813
1775**应该做什么：**1814**解决方法：**
1776 1815
1777* 再次运行 `/login` 并在登录过期之前确认账户1816* 再次运行 `/login`，并在登录过期之前确认账户
1778 1817
1779<h3 id="gateway-refused-the-request">1818<h3 id="gateway-refused-the-request">
1780 Gateway 拒绝了请求1819 Gateway refused the request
1781</h3>1820</h3>
1782 1821
1783您通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录，请求返回了 403：网关或其背后的上游拒绝了它。再次登录不会改变拒绝，因此消息指向您的网关管理员：1822您通过 [Claude apps 网关](/docs/zh-CN/claude-apps-gateway)登录，而某个请求返回了 403：网关或其背后的上游拒绝了该请求。重新登录不会改变拒绝结果，因此消息会提示您联系网关管理员：
1784 1823
1785```text theme={null}1824```text theme={null}
1786Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...1825Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...
1787```1826```
1788 1827
1789**应该做什么：**1828**解决方法：**
1790 1829
1791* 要求您的网关管理员查找请求。`API Error:` 尾部携带网关返回的拒绝1830* 请您的网关管理员查询该请求。`API Error:` 之后的部分包含网关返回的拒绝信息
1792* 对于管理员：网关上的 [访问控制规则](/docs/zh-CN/claude-apps-gateway-config#http-tuning) 返回 403，[审计日志](/docs/zh-CN/claude-apps-gateway-deploy#logs) 记录其原因，上游的授权拒绝按 [上游错误消息](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages) 传递1831* 对于管理员：网关上的[访问控制规则](/docs/zh-CN/claude-apps-gateway-config#http-tuning)会返回 403，[审计日志](/docs/zh-CN/claude-apps-gateway-deploy#logs)会记录该 403 及其原因；上游的授权拒绝会按照[上游错误消息](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages)中的说明透传
1793 1832
1794在 v2.1.273 之前，网关会话上的 403 显示通用 `Please run /login` 或 `Failed to authenticate` 消息，再次登录不会清除拒绝。1833在 v2.1.273 之前，网关会话上的 403 会改为显示通用的 `Please run /login` 或 `Failed to authenticate` 消息，且重新登录无法消除该拒绝。
1795 1834
1796<h2 id="network-and-connection-errors">1835<h2 id="network-and-connection-errors">
1797 网络和连接错误1836 网络和连接错误
2132Context limit reached · /compact or /clear to continue2171Context limit reached · /compact or /clear to continue
2133```2172```
2134 2173
2135当设置了 [`DISABLE_COMPACT`](/docs/zh-CN/env-vars) 时，该行仅显示 `/clear`。较长形式的错误，例如下面的压缩失败形式，保留 `Prompt is too long ·` 的措辞。在 `-p` 输出和记录中，文本保持为 `Prompt is too long`。2174当设置了 [`DISABLE_COMPACT`](/docs/zh-CN/env-vars) 时，该行仅显示 `/clear`。较长形式的错误，例如下面的压缩失败形式，保留 `Prompt is too long ·` 的措辞。在 `-p` 输出和会话记录中，文本保持为 `Prompt is too long`。
2136 2175
2137当您在[用户设置](/docs/zh-CN/settings-reference#autocompactenabled)中关闭自动压缩时，该行也会显示：2176当您在[用户设置](/docs/zh-CN/settings-reference#autocompactenabled)中关闭自动压缩时，该行也会显示：
2138 2177
2140Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on2179Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
2141```2180```
2142 2181
2143`/config` 中的**自动压缩**切换将 `autoCompactEnabled` 写入用户设置。该提示仅在 `/config` 更改会生效时出现。例如，当 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 或 [`DISABLE_COMPACT`](/docs/zh-CN/env-vars) 关闭自动压缩时，它不会出现。当更高优先级的范围（如项目或托管设置）将 `autoCompactEnabled` 设置为 `false` 时，它也不会出现。在 v2.1.235 之前，该行没有自动压缩提示。2182`/config` 中的**自动压缩**切换将 `autoCompactEnabled` 写入用户设置。该提示仅在 `/config` 更改会生效时出现。例如，当 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 或 [`DISABLE_COMPACT`](/docs/zh-CN/env-vars) 关闭自动压缩时，它不会出现。当更高优先级的作用域（如项目或托管设置）将 `autoCompactEnabled` 设置为 `false` 时，它也不会出现。在 v2.1.235 之前，该行没有自动压缩提示。
2144 2183
2145Amazon Bedrock 将此条件报告为 `Input is too long for requested model.`，Claude Code 以相同方式处理。在 v2.1.217 之前，Claude Code 不识别 Bedrock 的措辞，因此自动压缩从不在其上触发，`/compact` 失败并显示相同错误。2184Amazon Bedrock 将此条件报告为 `Input is too long for requested model.`，Claude Code 以相同方式处理。在 v2.1.217 之前，Claude Code 不识别 Bedrock 的措辞，因此自动压缩从不在其上触发，`/compact` 失败并显示相同错误。
2146 2185
2147[Claude apps gateway](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages) 在云上游以提供商自己的错误形状拒绝请求时，将此条件报告为 `capability_rejected: prompt_too_long`。Claude Code 将该令牌视为与 `Prompt is too long` 相同。在 v2.1.228 之前，Claude Code 不识别该令牌，因此自动压缩不会在其上触发。2186[Claude apps gateway](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages) 在云上游以提供商自己的错误形状拒绝请求时，将此条件报告为 `capability_rejected: prompt_too_long`。Claude Code 将该错误标识视为与 `Prompt is too long` 相同。在 v2.1.228 之前，Claude Code 不识别该错误标识，因此自动压缩不会在其上触发。
2148 2187
2149当自动压缩在此轮上运行并因底层错误（如不可用的模型或身份验证失败）而失败时，该消息在分隔符后命名该错误：2188当自动压缩在此轮上运行并因底层错误（如不可用的模型或身份验证失败）而失败时，该消息在分隔符后命名该错误：
2150 2189
2156 2195
2157当自动压缩在此错误上运行时，它通常会总结您最早的交换并保留最新的。作为最后的手段，Claude Code 会以不同的方式总结：2196当自动压缩在此错误上运行时，它通常会总结您最早的交换并保留最新的。作为最后的手段，Claude Code 会以不同的方式总结：
2158 2197
2159* 当它无法总结任何完整交换时，Claude Code 会逐字保留您最新的提示，并总结其前面的所有内容。2198* 当它无法总结任何完整交换时，Claude Code 会逐字保留您最新的提示词，并总结其前面的所有内容。
2160* 在这种情况下，当对话不以您的提示结尾时，Claude Code 会改为总结整个对话。2199* 在这种情况下，当对话不以您的提示词结尾时，Claude Code 会改为总结整个对话。
2161 2200
2162当它将转发的内容不包含模型回复且您自己的文本少于约 1,000 个令牌（如在超大粘贴后发送的短重试）时，Claude Code 会跳过此恢复。运行 `/clear` 以重新开始。在 v2.1.269 之前，每当压缩无法总结完整交换时就会失败，因此处于该状态的会话在每一轮都会再次遇到此错误。2201当它将转发的内容不包含模型回复且您自己的文本少于约 1,000 个 token（如在超大粘贴后发送的短重试）时，Claude Code 会跳过此恢复。运行 `/clear` 以重新开始。在 v2.1.269 之前，每当压缩无法总结完整交换时就会失败，因此处于该状态的会话在每一轮都会再次遇到此错误。
2163 2202
2164单交换对话没有更早的轮次可总结。当自动压缩会在其上运行时，Claude Code 会跳过尝试并解释请求中填充的内容。当 API 在其错误中不报告令牌计数时，消息读取：2203单交换对话没有更早的轮次可总结。当自动压缩会在其上运行时，Claude Code 会跳过尝试并解释请求中填充的内容。当 API 在其错误中不报告 token 计数时，消息读取：
2165 2204
2166```text theme={null}2205```text theme={null}
2167Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.2206Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.
2168```2207```
2169 2208
2170当 API 在其错误中报告令牌计数时，Claude Code 将其与对话大小的自己估计进行比较，以判断请求的大部分是什么：对话自己的内容，还是 Claude Code 与其一起发送的系统提示、工具定义和附件内容。当对话自己的内容是请求的大部分时，消息读取：2209当 API 在其错误中报告 token 计数时，Claude Code 将其与对话大小的自己估计进行比较，以判断请求的大部分是什么：对话自己的内容，还是 Claude Code 与其一起发送的系统提示词、工具定义和附件内容。当对话自己的内容是请求的大部分时，消息读取：
2171 2210
2172```text theme={null}2211```text theme={null}
2173Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).2212Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).
2179Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.2218Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.
2180```2219```
2181 2220
2182在 v2.1.162 之前，Claude Code 尝试了压缩，并在失败时显示裸露的 `Prompt is too long`。2221在 v2.1.162 之前，Claude Code 仍会尝试压缩，并在失败时显示裸露的 `Prompt is too long`。
2183 2222
2184**要做什么：**2223**要做什么：**
2185 2224
2186* 运行 `/compact` 以总结较早的轮次并释放空间，或运行 `/clear` 以重新开始。如果 `/compact` 回答 `Not enough messages to compact.`，则对话是单个交换，没有更早的内容可总结，因此空间由该单个提示和 Claude Code 与每个请求一起发送的内容占用：运行 `/clear` 并使用较少的粘贴文本或较小的附件重新发送，或使用下面的步骤减少工具定义和内存文件2225* 运行 `/compact` 以总结较早的轮次并释放空间，或运行 `/clear` 以重新开始。如果 `/compact` 回答 `Not enough messages to compact.`，则对话是单个交换，没有更早的内容可总结，因此空间由该单个提示词和 Claude Code 与每个请求一起发送的内容占用：运行 `/clear` 并使用较少的粘贴文本或较小的附件重新发送，或使用下面的步骤减少工具定义和记忆文件
2187* 运行 `/context` 以查看窗口消耗内容的分解：系统提示、工具、内存文件和消息2226* 运行 `/context` 以查看窗口消耗内容的分解：系统提示词、工具、记忆文件和消息
2188* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中删除其工具定义2227* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中删除其工具定义
2189* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到仅在相关时加载的[路径范围规则](/docs/zh-CN/memory#path-specific-rules)中2228* 修剪大型 `CLAUDE.md` 记忆文件，或将说明移到仅在相关时加载的[路径范围规则](/docs/zh-CN/memory#path-specific-rules)中
2190* 自动压缩默认开启，通常可防止此错误。如果您在 `/config` 中或使用 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 关闭了它，请将其重新打开。如果您保持关闭，请在窗口填满之前自己运行 `/compact`。2229* 自动压缩默认开启，通常可防止此错误。如果您在 `/config` 中或使用 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 关闭了它，请将其重新打开。如果您保持关闭，请在窗口填满之前自己运行 `/compact`。
2191 2230
2192有关上下文如何填满的交互式视图，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。2231有关上下文如何填满的交互式视图，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。
2193 2232
2194<h3 id="context-exceeds-the-token-limit">2233<h3 id="context-exceeds-the-token-limit">
2195 上下文超过令牌限制2234 上下文超过 token 限制
2196</h3>2235</h3>
2197 2236
2198`/context` 在其输出顶部显示此警告，当对话超过模型的上下文窗口时。请求失败，显示 [`Prompt is too long`](#prompt-is-too-long)，直到您释放空间。交互式会话将该错误显示为 `Context limit reached` 行。2237当对话超过模型的上下文窗口时，`/context` 在其输出顶部显示此警告。在您释放空间之前，请求会失败并显示 [`Prompt is too long`](#prompt-is-too-long)。交互式会话将该错误显示为 `Context limit reached` 行。
2199 2238
2200```text theme={null}2239```text theme={null}
2201Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2240Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
2220 请求过大2259 请求过大
2221</h3>2260</h3>
2222 2261
2223原始请求体在令牌化之前超过了 API 的 32MB 限制，通常是由于大型粘贴内容、工具结果或附件。此限制与[上下文窗口](#prompt-is-too-long)分开。2262原始请求体在 token 化之前超过了 API 的 32MB 限制，通常是由于大型粘贴内容、工具结果或附件。此限制与[上下文窗口](#prompt-is-too-long)分开。
2224 2263
2225```text theme={null}2264```text theme={null}
2226Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.2265Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.
2305pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.2344pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.
2306```2345```
2307 2346
2308页面范围读取使用 `pdftoppm` 呈现页面。使用消息提供的命令安装 poppler-utils，或在其他平台上安装将 `pdftoppm` 放在您的 `PATH` 上的 poppler 构建。请参阅[Read 工具行为](/docs/zh-CN/tools-reference#read-tool-behavior)以了解哪些 PDF 按页面范围读取。2347页面范围读取使用 `pdftoppm` 呈现页面。使用消息提供的命令安装 poppler-utils，或在其他平台上安装将 `pdftoppm` 放在您的 `PATH` 上的 poppler 构建版本。请参阅[Read 工具行为](/docs/zh-CN/tools-reference#read-tool-behavior)以了解哪些 PDF 按页面范围读取。
2309 2348
2310<h3 id="extra-inputs-are-not-permitted">2349<h3 id="extra-inputs-are-not-permitted">
2311 不允许额外输入2350 不允许额外输入
2317API Error: 400 ... Extra inputs are not permitted ... context_management2356API Error: 400 ... Extra inputs are not permitted ... context_management
2318```2357```
2319 2358
2320Claude Code 发送 `context_management` 和 `effort` 等仅限测试版的字段，以及启用它们的 `anthropic-beta` 头。当网关转发正文但删除头时，API 会看到它不识别的字段。2359Claude Code 发送 `context_management` 等仅限测试版的字段，以及启用它们的 `anthropic-beta` 头。当网关转发正文但删除头时，API 会看到它不识别的字段。
2321 2360
2322**要做什么：**2361**要做什么：**
2323 2362
2324* 配置您的网关以转发 `anthropic-beta` 头。有关网关必须转发的内容，请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。2363* 配置您的网关以转发 `anthropic-beta` 头。有关网关必须转发的内容，请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。
2325* 作为后备，在启动前设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-CN/env-vars)。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)涵盖确切范围。2364* 作为回退方案，在启动前设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-CN/env-vars)。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)涵盖确切范围。
2326 2365
2327<h3 id="tool-input-schema-is-invalid">2366<h3 id="tool-input-schema-is-invalid">
2328 工具输入架构无效2367 工具输入 schema 无效
2329</h3>2368</h3>
2330 2369
2331请求中的工具声明了 `input_schema`，该架构未通过 API 的 JSON Schema 验证，因此 API 拒绝了整个请求。`tools.` 后的数字是失败工具在请求的工具列表中的位置，而不是您可以查找的名称。2370请求中的工具声明了 `input_schema`，该 schema 未通过 API 的 JSON Schema 验证，因此 API 拒绝了整个请求。`tools.` 后的数字是失败工具在请求的工具列表中的位置，而不是您可以查找的名称。
2332 2371
2333```text theme={null}2372```text theme={null}
2334API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid2373API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2335API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'2374API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'
2336```2375```
2337 2376
2338第一种形式意味着架构不是有效的 JSON Schema draft 2020-12。第二种意味着顶级属性名称与消息引用的模式不匹配。2377第一种形式意味着 schema 不是有效的 JSON Schema draft 2020-12。第二种意味着顶级属性名称与消息引用的模式不匹配。
2339 2378
2340Claude Code [在加载服务器的工具时排除其输入架构会失败此验证的 MCP 工具](/docs/zh-CN/mcp#tools-with-invalid-input-schemas)，因此请求通常永远不会包含一个。2379Claude Code [在加载服务器的工具时排除其输入 schema 会失败此验证的 MCP 工具](/docs/zh-CN/mcp#tools-with-invalid-input-schemas)，因此请求通常永远不会包含一个。
2341 2380
2342在[禁用标志获取的部署](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)上，或在标志从未到达的机器上，Claude Code 在服务器的日志中记录哪个工具会被拒绝，但仍然发送它，因此此错误仍然可能发生。2381在[禁用标志获取的部署](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)上，或在标志从未到达的机器上，Claude Code 在服务器的日志中记录哪个工具会被拒绝，但仍然发送它，因此此错误仍然可能发生。
2343 2382
2344该错误也可能发生在其架构在 `$schema` 中声明 JSON Schema 方言（而不是 draft 2020-12）的工具上。Claude Code 不会根据 JSON Schema 元架构检查这些架构，尽管顶级属性名称检查仍然适用。2383该错误也可能发生在其 schema 在 `$schema` 中声明 JSON Schema 方言（而不是 draft 2020-12）的工具上。Claude Code 不会根据 JSON Schema 元 schema 检查这些 schema，尽管顶级属性名称检查仍然适用。
2345 2384
2346在 v2.1.216 之前，没有部署运行排除检查。2385在 v2.1.216 之前，没有部署运行排除检查。
2347 2386
2348**要做什么：**2387**要做什么：**
2349 2388
2350* 如果您的 Claude Code 版本早于 v2.1.216，运行 `claude update`。2389* 如果您的 Claude Code 版本早于 v2.1.216，运行 `claude update`。
2351* 删除或[禁用](/docs/zh-CN/mcp#disable-a-server-without-removing-it)声明无效架构的 MCP 服务器。该错误仅按位置命名工具。在 v2.1.216 或更高版本上，检查每个服务器的日志，查找命名其输入架构会被拒绝的工具的行。如果没有日志命名一个，一次禁用一个服务器。2390* 删除或[禁用](/docs/zh-CN/mcp#disable-a-server-without-removing-it)声明无效 schema 的 MCP 服务器。该错误仅按位置命名工具。在 v2.1.216 或更高版本上，检查每个服务器的日志，查找命名其输入 schema 会被拒绝的工具的行。如果没有日志命名一个，一次禁用一个服务器。
2352* 如果您维护服务器，请修复工具的 `input_schema`。架构必须是有效的 JSON Schema，顶级属性名称必须为 1 到 64 个字符长，并仅使用 ASCII 字母和数字、`_`、`.` 和 `-`。请参阅[具有无效输入架构的工具](/docs/zh-CN/mcp#tools-with-invalid-input-schemas)。2391* 如果您维护服务器，请修复工具的 `input_schema`。schema 必须是有效的 JSON Schema，顶级属性名称必须为 1 到 64 个字符长，并仅使用 ASCII 字母和数字、`_`、`.` 和 `-`。请参阅[具有无效输入 schema 的工具](/docs/zh-CN/mcp#tools-with-invalid-input-schemas)。
2353 2392
2354<h3 id="tool-use-name-over-200-characters">2393<h3 id="tool-use-name-over-200-characters">
2355 tool\_use.name 超过 200 个字符2394 tool\_use.name 超过 200 个字符
2361API Error: 400 ... tool_use.name: String should have at most 200 characters2400API Error: 400 ... tool_use.name: String should have at most 200 characters
2362```2401```
2363 2402
2364Claude Code 在响应到达时以及加载保存的对话时将这样的名称切割为 200 个字符，因此调用失败，显示普通的 `No such tool available` 工具错误，对话继续而不显示此 API 错误。2403Claude Code 在响应到达时以及加载保存的对话时将这样的名称截断为 200 个字符，因此该调用会失败并显示 [`No such tool available`](#no-such-tool-available) 工具错误，对话继续而不显示此 API 错误。
2365 2404
2366**要做什么：**2405**要做什么：**
2367 2406
2368* 运行 `claude update`，然后恢复对话。更新的版本在加载记录时修复过长的名称，因此卡住的对话再次工作。2407* 运行 `claude update`，然后恢复对话。更新的版本在加载会话记录时修复过长的名称，因此卡住的对话再次工作。
2369 2408
2370在 v2.1.281 之前，过长的名称保留在历史中，API 拒绝了重新发送对话的每个请求，包括 `/compact` 和 `--resume`，因此此错误重复，对话被卡住。2409在 v2.1.281 之前，过长的名称保留在历史中，API 拒绝了重新发送对话的每个请求，包括 `/compact` 和 `--resume`，因此此错误重复，对话被卡住。
2371 2410
2373 所选模型存在问题2412 所选模型存在问题
2374</h3>2413</h3>
2375 2414
2376配置的模型名称未被识别，或您的帐户无权访问它。从 v2.1.160 开始，尾部提示（此处以其交互形式显示）因表面而异。2415配置的模型名称未被识别，或您的帐户无权访问它。从 v2.1.160 开始，尾部提示（此处以其交互形式显示）因使用入口而异。
2377 2416
2378```text theme={null}2417```text theme={null}
2379There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.2418There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.
2382**要做什么：**2421**要做什么：**
2383 2422
2384* **交互式 CLI**：运行 `/model` 从您帐户可用的模型中选择。2423* **交互式 CLI**：运行 `/model` 从您帐户可用的模型中选择。
2385* **非交互模式 (`-p`)**：使用有效的别名或 ID 传递 `--model`，或设置 [`ANTHROPIC_MODEL`](/docs/zh-CN/env-vars)。错误文本在此表面上显示 `Run --model`。2424* **非交互模式 (`-p`)**：使用有效的别名或 ID 传递 `--model`，或设置 [`ANTHROPIC_MODEL`](/docs/zh-CN/env-vars)。错误文本在此使用入口上显示 `Run --model`。
2386* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中的 [`Options` 上设置 `model`](/docs/zh-CN/agent-sdk/typescript#options)，或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/docs/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。2425* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中的 [`Options` 上设置 `model`](/docs/zh-CN/agent-sdk/typescript#options)，或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/docs/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。
2387* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此它们不会过时。请参阅[模型配置](/docs/zh-CN/model-config)。2426* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此它们不会过时。请参阅[模型配置](/docs/zh-CN/model-config)。
2388* 如果错误的模型在 CLI 中不断返回，则某处设置了过时的 ID。按[优先级顺序](/docs/zh-CN/model-config#setting-your-model)检查您可以设置模型的位置，并删除过时的值。2427* 如果错误的模型在 CLI 中不断返回，则某处设置了过时的 ID。按[优先级顺序](/docs/zh-CN/model-config#setting-your-model)检查您可以设置模型的位置，并删除过时的值。
2416 模型未找到2455 模型未找到
2417</h3>2456</h3>
2418 2457
2419您使用名称切换到模型，Claude Code 无法确认存在具有该名称的模型。当名称不是 [model alias](/docs/zh-CN/model-config#model-aliases) 或 Claude Code 在本地接受的另一种拼写时，Claude Code 使用最小 API 请求验证它，此错误通常是您的 API 端点的答案。使用 `/model <name>` 时，无法成为模型 ID 的名称（如包含空格的名称）会获得相同的消息。2458您使用名称切换到模型，Claude Code 无法确认存在具有该名称的模型。当名称不是[模型别名](/docs/zh-CN/model-config#model-aliases)或 Claude Code 在本地接受的另一种拼写时，Claude Code 使用最小 API 请求验证它，此错误通常是您的 API 端点的答案。使用 `/model <name>` 时，无法成为模型 ID 的名称（如包含空格的名称）会获得相同的消息。
2420 2459
2421```text theme={null}2460```text theme={null}
2422Model 'claude-opus-9' not found2461Model 'claude-opus-9' not found
2423```2462```
2424 2463
2425在具有提供商特定模型 ID 的提供商上，消息可能会添加 `Try '...' instead` 建议，该建议命名您提供商的后备模型 ID。2464在具有提供商特定模型 ID 的提供商上，消息可能会添加 `Try '...' instead` 建议，该建议命名您提供商的备用模型 ID。
2426 2465
2427**要做什么：**2466**要做什么：**
2428 2467
2429* 运行 `/model` 不带参数并从您帐户可用的模型中选择，或使用 [model alias](/docs/zh-CN/model-config#model-aliases)（如 `sonnet`），它解析为维护的默认值2468* 运行 `/model` 不带参数并从您帐户可用的模型中选择，或使用[模型别名](/docs/zh-CN/model-config#model-aliases)（如 `sonnet`），它解析为维护的默认值
2430* 如果您输入了完整 ID，请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用，但您的提供商或地区尚未提供。2469* 如果您输入了完整 ID，请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用，但您的提供商或地区尚未提供。
2431* 在 Agent SDK 中，`setModel()` 失败，显示此消息，会话继续在其前一个模型上运行。在 TypeScript SDK 中，调用 [`supportedModels()`](/docs/zh-CN/agent-sdk/typescript#query-object) 以列出您可以切换到的模型。2470* 在 Agent SDK 中，`setModel()` 失败，显示此消息，会话继续在其前一个模型上运行。在 TypeScript SDK 中，调用 [`supportedModels()`](/docs/zh-CN/agent-sdk/typescript#query-object) 以列出您可以切换到的模型。
2432* 在 v2.1.265 之前，`/model` 也以此错误拒绝了 `opusplan[1m]` 别名拼写。在这些版本上，更新 Claude Code，或在[设置](/docs/zh-CN/model-config#setting-your-model)中或使用 `--model` 设置模型。2471* 在 v2.1.265 之前，`/model` 也以此错误拒绝了 `opusplan[1m]` 别名拼写。在这些版本上，更新 Claude Code，或在[设置](/docs/zh-CN/model-config#setting-your-model)中或使用 `--model` 设置模型。
2435 无法通过 API 确认模型2474 无法通过 API 确认模型
2436</h3>2475</h3>
2437 2476
2438您通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法或运行 Claude Code CLI 的应用程序（如 [Desktop app](/docs/zh-CN/desktop)）切换了模型，确认模型 ID 与您的 API 端点的请求在五秒内没有得到答复。会话保持其当前模型。2477您通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法或运行 Claude Code CLI 的应用程序（如 [Desktop app](/docs/zh-CN/desktop)）切换了模型，向您的 API 端点确认模型 ID 的请求在五秒内没有得到答复。会话保持其当前模型。
2439 2478
2440```text theme={null}2479```text theme={null}
2441Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.2480Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.
2475Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.2514Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.
2476```2515```
2477 2516
2478在 Claude Desktop app 运行的会话中，消息说改为`登出并登入`而不是命名命令。2517在 Claude Desktop app 运行的会话中，消息会提示 `sign out and sign in again`，而不是命名命令。
2479 2518
2480**要做什么：**2519**要做什么：**
2481 2520
2503 2542
2504**要做什么：**2543**要做什么：**
2505 2544
2506更新该二进制文件，然后启动新会话。二进制文件的来源决定了如何，除了在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#pin-the-version)中：2545更新该二进制文件，然后启动新会话。二进制文件的来源决定了如何更新，除了在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#pin-the-version)中：
2507 2546
2508| 发出请求的二进制文件 | 如何更新它 |2547| 发出请求的二进制文件 | 如何更新它 |
2509| :- | :- |2548| :- | :- |
2510| 您安装的 Claude Code | 运行 `claude update` |2549| 您安装的 Claude Code | 运行 `claude update` |
2511| Claude desktop app | 更新应用 |2550| Claude desktop app | 更新应用 |
2512| [VS Code extension](/docs/zh-CN/vs-code) 捆绑的二进制文件 | 更新扩展 |2551| [VS Code extension](/docs/zh-CN/vs-code) 捆绑的二进制文件 | 更新扩展 |
2513| Agent SDK 包捆绑的二进制文件 | [升级 SDK 包](/docs/zh-CN/agent-sdk/hosting#runtime-dependencies)，然后重启您的应用程序。在[编译的单文件可执行文件](/docs/zh-CN/agent-sdk/typescript#compile-to-a-single-executable)中，重建它 |2552| Agent SDK 包捆绑的二进制文件 | [升级 SDK 包](/docs/zh-CN/agent-sdk/hosting#runtime-dependencies)，然后重启您的应用程序。在[编译的单文件可执行文件](/docs/zh-CN/agent-sdk/typescript#compile-to-a-single-executable)中，重新构建它 |
2514 2553
2515* 对于按模型措辞，您可以通过切换到另一个模型来继续在当前会话中工作：在 CLI 中运行 `/model`，在流式输入模式下的 TypeScript SDK 的 `Query` 对象上调用 [`setModel()`](/docs/zh-CN/agent-sdk/typescript#query-object)，或在 Python SDK 的 `ClaudeSDKClient` 上调用 [`set_model()`](/docs/zh-CN/agent-sdk/python#claudesdkclient)2554* 对于按模型措辞，您可以通过切换到另一个模型来继续在当前会话中工作：在 CLI 中运行 `/model`，在流式输入模式下的 TypeScript SDK 的 `Query` 对象上调用 [`setModel()`](/docs/zh-CN/agent-sdk/typescript#query-object)，或在 Python SDK 的 `ClaudeSDKClient` 上调用 [`set_model()`](/docs/zh-CN/agent-sdk/python#claudesdkclient)
2516* 对于组织政策措辞，在继续之前更新2555* 对于组织政策措辞，在继续之前更新
2519 模型受您的组织设置限制2558 模型受您的组织设置限制
2520</h3>2559</h3>
2521 2560
2522您的组织管理员在 claude.ai 管理控制台中禁用了此模型，或托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表或 [`deniedModels`](/docs/zh-CN/model-config#block-specific-models-or-versions) 列表排除了它。当受限制的模型使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置时，通知在启动时出现，并命名会话使用的模型。如果托管设置没有为会话留下允许的模型，请参阅[托管设置阻止默认模型](#managed-settings-block-the-default-model)。替换通知也可能在会话中期出现，在组织管理员在 claude.ai 管理控制台中禁用会话正在运行的模型之后。2561您的组织管理员在 claude.ai 管理控制台中禁用了此模型，或托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表或 [`deniedModels`](/docs/zh-CN/model-config#block-specific-models-or-versions) 列表排除了它。当 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置指定了受限制的模型时，通知在启动时出现，并命名会话改用的模型。如果托管设置没有为会话留下允许的模型，请参阅[托管设置阻止默认模型](#managed-settings-block-the-default-model)。在管理员于 claude.ai 管理控制台中禁用会话正在运行的模型之后，替换通知也可能在会话中途出现。
2523 2562
2524```text theme={null}2563```text theme={null}
2525Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.2564Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
2527 2566
2528为受限制的模型键入 `/model <name>` 被拒绝，会话保持其当前模型。对于在管理控制台中禁用的模型，拒绝读取 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`。对于托管设置排除的模型，它读取 `Model '<name>' is not available. Your organization restricts model selection.`2567为受限制的模型键入 `/model <name>` 被拒绝，会话保持其当前模型。对于在管理控制台中禁用的模型，拒绝读取 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`。对于托管设置排除的模型，它读取 `Model '<name>' is not available. Your organization restricts model selection.`
2529 2568
2530以代理、技能或命令名称为前缀的通知意味着限制适用于该[子代理的请求模型](/docs/zh-CN/sub-agents#choose-a-model)：子代理在替换模型上运行，您的会话模型保持不变。在 v2.1.223 之前，Claude Code 仅为使用 Agent 工具启动的子代理显示通知。2569以 Agent、skill 或命令名称为前缀的通知意味着限制适用于该[子代理的请求模型](/docs/zh-CN/sub-agents#choose-a-model)：子代理在替换模型上运行，您的会话模型保持不变。在 v2.1.223 之前，Claude Code 仅为使用 Agent 工具启动的子代理显示通知。
2531 2570
2532Claude Code 将模型族别名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，受限制的族别名解析为您的组织的设置允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限制时才拒绝 `/model <alias>`。在 v2.1.205 之前，族别名基于其最新版本单独被替换或拒绝，即使同一族的较旧版本被允许。2571Claude Code 将模型族别名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，受限制的族别名解析为您的组织的设置允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限制时才拒绝 `/model <alias>`。在 v2.1.205 之前，族别名仅基于其最新版本被替换或拒绝，即使同一族的较旧版本被允许。
2533 2572
2534**要做什么：**2573**要做什么：**
2535 2574
2536* 运行 `/model` 从您的组织允许的模型中选择。受限制的模型从选择器中隐藏。2575* 运行 `/model` 从您的组织允许的模型中选择。受限制的模型从选择器中隐藏。
2537* 如果受限制的模型在 `--model`、`ANTHROPIC_MODEL`、设置文件的 `model` 字段或[子代理](/docs/zh-CN/sub-agents#choose-a-model)、技能或命令的 `model` frontmatter 中设置，删除或更新该值，以便通知不会再次出现2576* 如果受限制的模型在 `--model`、`ANTHROPIC_MODEL`、设置文件的 `model` 字段或[子代理](/docs/zh-CN/sub-agents#choose-a-model)、skill 或命令的 `model` frontmatter 中设置，删除或更新该值，以便通知不会再次出现
2538* 如果您需要访问受限制的模型，请要求您的组织管理员启用它。请参阅[组织模型限制](/docs/zh-CN/model-config#organization-model-restrictions)。2577* 如果您需要访问受限制的模型，请要求您的组织管理员启用它。请参阅[组织模型限制](/docs/zh-CN/model-config#organization-model-restrictions)。
2539 2578
2540<h3 id="cant-switch-to-the-default-model">2579<h3 id="cant-switch-to-the-default-model">
2559* 要求您的管理员更新消息命名的托管设置2598* 要求您的管理员更新消息命名的托管设置
2560* 对于 `couldn't read` 措辞，重启 Claude Code；如果它继续发生，要求您的管理员检查托管设置2599* 对于 `couldn't read` 措辞，重启 Claude Code；如果它继续发生，要求您的管理员检查托管设置
2561 2600
2562如果会话改为在这些托管设置下以 `Claude Code can't start` 消息失败启动，请参阅[托管设置阻止默认模型](#managed-settings-block-the-default-model)。2601如果会话改为在这些托管设置下以 `Claude Code can't start` 消息启动失败，请参阅[托管设置阻止默认模型](#managed-settings-block-the-default-model)。
2563 2602
2564<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">2603<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">
2565 模型切换被 PreModelSwitch hook 阻止2604 模型切换被 PreModelSwitch hook 阻止
2576* **hook 写入的原因**：PreModelSwitch hook 在[拒绝切换或要求确认](/docs/zh-CN/hooks#premodelswitch-decision-control)时提供了该原因。解决它要求的内容，或选择您的 hook 允许的模型。2615* **hook 写入的原因**：PreModelSwitch hook 在[拒绝切换或要求确认](/docs/zh-CN/hooks#premodelswitch-decision-control)时提供了该原因。解决它要求的内容，或选择您的 hook 允许的模型。
2577* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其[超时](/docs/zh-CN/hooks#timeouts)之前不回答的 hook 阻止切换。修复挂起的命令或提高该 hook 的 `timeout`，然后再次切换。2616* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其[超时](/docs/zh-CN/hooks#timeouts)之前不回答的 hook 阻止切换。修复挂起的命令或提高该 hook 的 `timeout`，然后再次切换。
2578* **`confirmation required, and this session cannot ask`**：hook 回答 `ask` 而没有原因，控制请求无法显示确认提示。[`-p` 运行](/docs/zh-CN/headless)中的 `/model` 命令以原因后的 `(run /model interactively to confirm)` 报告相同条件。从交互式会话进行切换，或更改 hook 对此模型的决定。2617* **`confirmation required, and this session cannot ask`**：hook 回答 `ask` 而没有原因，控制请求无法显示确认提示。[`-p` 运行](/docs/zh-CN/headless)中的 `/model` 命令以原因后的 `(run /model interactively to confirm)` 报告相同条件。从交互式会话进行切换，或更改 hook 对此模型的决定。
2579* **`so organization-managed PreModelSwitch hooks could not be checked`**：Claude Code 无法判断您的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hook，例如因为托管插件加载失败。这些 hook 之一可能阻止切换，因此 Claude Code 拒绝而不是应用未检查的切换。原因的开始命名失败的内容。Claude Code 在每次切换尝试时重新检查，因此已清除的失败停止阻止；如果它继续失败，运行 `claude --debug` 并再次切换以捕获详细信息，然后修复插件或要求您的管理员修复它。2618* **`so organization-managed PreModelSwitch hooks could not be checked`**：Claude Code 无法判断您的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hook，例如因为托管插件加载失败。这些 hook 之一可能阻止切换，因此 Claude Code 拒绝而不是应用未检查的切换。原因的开头命名失败的内容。Claude Code 在每次切换尝试时重新检查，因此已清除的失败不再阻止；如果它继续失败，运行 `claude --debug` 并再次切换以捕获详细信息，然后修复插件或要求您的管理员修复它。
2580* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 运行在没有判决的情况下结束，Claude Code 不将其视为批准。运行 `claude --debug` 以查看失败的内容，然后再次切换。2619* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 运行在没有判决的情况下结束，Claude Code 不将其视为批准。运行 `claude --debug` 以查看失败的内容，然后再次切换。
2581 2620
2582在 v2.1.260 之前，托管插件拒绝读取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重试了一次插件加载，然后在会话中拒绝了后来的切换，即使您的组织没有管理任何插件。在这些版本上重启会话以再次运行插件加载。2621在 v2.1.260 之前，托管插件拒绝读取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重试了一次插件加载，然后在会话中拒绝了后来的切换，即使您的组织没有管理任何插件。在这些版本上重启会话以再次运行插件加载。
2585 无法将其保存为您的默认值2624 无法将其保存为您的默认值
2586</h3>2625</h3>
2587 2626
2588您选择了一个模型以保存为您的默认值，例如使用 `/model <name>` 或 `/model` 选择器中的 Enter，Claude Code 无法将选择写入您的用户设置文件 `~/.claude/settings.json`。切换本身已应用，因此当前会话在您选择的模型上运行，但您的默认值保持不变，下一个会话在旧值上启动。2627您选择了一个模型以保存为您的默认值，例如使用 `/model <name>` 或 `/model` 选择器中的 `Enter`，Claude Code 无法将选择写入您的用户设置文件 `~/.claude/settings.json`。切换本身已应用，因此当前会话在您选择的模型上运行，但您的默认值保持不变，下一个会话在旧值上启动。
2589 2628
2590```text theme={null}2629```text theme={null}
2591Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)2630Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)
2594文件路径后的原因说明失败的内容：2633文件路径后的原因说明失败的内容：
2595 2634
2596* **`can't be written (<code>)`**：写入失败，显示括号中的操作系统错误代码，如 `EROFS`（当文件或其链接到的文件位于拒绝写入的文件系统上时）。使文件可写并再次切换。如果另一个工具生成文件，请在该工具中设置 `model` 键；请参阅[您在 Claude Code 中所做的更改在新会话中丢失](/docs/zh-CN/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。2635* **`can't be written (<code>)`**：写入失败，显示括号中的操作系统错误代码，如 `EROFS`（当文件或其链接到的文件位于拒绝写入的文件系统上时）。使文件可写并再次切换。如果另一个工具生成文件，请在该工具中设置 `model` 键；请参阅[您在 Claude Code 中所做的更改在新会话中丢失](/docs/zh-CN/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。
2597* **`isn't valid JSON`**：磁盘上的文件不解析，Claude Code 保持不动而不是覆盖它无法读回的内容。修复语法错误，然后再次切换；请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。2636* **`isn't valid JSON`**：磁盘上的文件无法解析，Claude Code 保持不动而不是覆盖它无法读回的内容。修复语法错误，然后再次切换；请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。
2598 2637
2599以 `couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)` 结尾的通知意味着写入在三秒后未完成。它在后台继续，因此默认值可能仍然被保存；检查您的下一个会话启动的模型，或再次运行 `/model <name>`。2638以 `couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)` 结尾的通知意味着写入在三秒后未完成。它在后台继续，因此默认值可能仍然被保存；检查您的下一个会话启动的模型，或再次运行 `/model <name>`。
2600 2639
2601在 v2.1.265 之前，通知说模型被`保存为您的新会话默认值`，即使写入失败。2640在 v2.1.265 之前，即使写入失败，通知也会说模型已 `saved as your default for new sessions`。
2641
2642<h3 id="advisor-is-less-capable-than-the-current-main-model">
2643 Advisor 的能力低于当前主模型
2644</h3>
2645
2646您的 [advisor 模型](/docs/zh-CN/advisor)排名低于会话的主模型，因此 Claude Code 保留该选择，但不会将 advisor 附加到主模型的请求上。
2647
2648```text theme={null}
2649Advisor set to Opus 4.8
2650Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.
2651```
2652
2653其他消息报告相同的情况：
2654
2655* 在交互式会话中，通知显示 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`。
2656* 使用 `--advisor` 标志启动时，警告显示 `"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.`，会话仍会启动。
2657
2658**要做什么：**
2659
2660* 选择排名更高的 advisor 或排名更低的主模型。[选择 advisor 模型](/docs/zh-CN/advisor#choose-an-advisor-model)展示了排名，并列出每个主模型可接受的 advisor。
2661* 如果您希望该 advisor 能够为其模型提供建议的[子代理](/docs/zh-CN/sub-agents)继续使用它，请保留 advisor 设置
2662
2663在 v2.1.287 之前，Claude Code 对若干组合的排名不同。它会在 Sonnet 5.5 advisor 搭配 Opus 4.7 或 Opus 4.8 主模型时显示此提示，而现在接受该组合。它还会附加一些现在会产生此提示的 advisor，例如 Opus 4.8 advisor 搭配 Sonnet 5.5 主模型。
2602 2664
2603<h3 id="thinking-type-enabled-is-not-supported-for-this-model">2665<h3 id="thinking-type-enabled-is-not-supported-for-this-model">
2604 thinking.type.enabled 此模型不支持2666 thinking.type.enabled 此模型不支持
2617* 如果您在 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中遇到这个，升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本。Opus 5 需要 TypeScript SDK v0.3.219 或更高版本。Opus 5.5 需要 TypeScript SDK v0.3.280 或更高版本。Sonnet 5.5 需要 TypeScript SDK v0.3.284 或更高版本2679* 如果您在 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中遇到这个，升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本。Opus 5 需要 TypeScript SDK v0.3.219 或更高版本。Opus 5.5 需要 TypeScript SDK v0.3.280 或更高版本。Sonnet 5.5 需要 TypeScript SDK v0.3.284 或更高版本
2618 2680
2619<h3 id="effort-isnt-available-with-thinking-turned-off">2681<h3 id="effort-isnt-available-with-thinking-turned-off">
2620 关闭思考时努力不可用2682 关闭思考时 effort 不可用
2621</h3>2683</h3>
2622 2684
2623您关闭了[扩展思考](/docs/zh-CN/model-config#extended-thinking)并以[努力级别](/docs/zh-CN/model-config#adjust-effort-level)高于 `high` 运行。模型不接受该组合，因此 API 拒绝了请求。2685您关闭了[扩展思考](/docs/zh-CN/model-config#extended-thinking)并以高于 `high` 的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)运行。模型不接受该组合，因此 API 拒绝了请求。
2624 2686
2625```text theme={null}2687```text theme={null}
2626API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)2688API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)
2630 2692
2631**要做什么：**2693**要做什么：**
2632 2694
2633* [降低努力级别](/docs/zh-CN/model-config#set-the-effort-level)到 `high` 或以下。2695* [降低 effort 级别](/docs/zh-CN/model-config#set-the-effort-level)到 `high` 或以下。
2634* 打开思考，例如通过取消设置 [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 或从您的设置中删除 [`"alwaysThinkingEnabled": false`](/docs/zh-CN/settings-reference#alwaysthinkingenabled)。2696* 重新打开思考，例如通过取消设置 [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 或从您的设置中删除 [`"alwaysThinkingEnabled": false`](/docs/zh-CN/settings-reference#alwaysthinkingenabled)。
2635 2697
2636在 v2.1.242 之前，Claude Code 显示了 API 自己的消息：`API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` 在 v2.1.251 之前，Claude Code 以您设置的努力级别发送请求，因此 Opus 5 拒绝了关闭思考时高于 `high` 的每个请求。Claude Code 现在向它知道拒绝该组合的模型（如 Opus 5）发送努力 `high`。2698在 v2.1.242 之前，Claude Code 显示了 API 自己的消息：`API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` 在 v2.1.251 之前，Claude Code 以您设置的 effort 级别发送请求，因此 Opus 5 拒绝了关闭思考时高于 `high` 的每个请求。Claude Code 现在向它知道拒绝该组合的模型（如 Opus 5）改为发送 effort `high`。
2637 2699
2638<h3 id="thinking-budget-exceeds-output-limit">2700<h3 id="thinking-budget-exceeds-output-limit">
2639 思考预算超过输出限制2701 思考预算超过输出限制
2647 2709
2648**要做什么：**2710**要做什么：**
2649 2711
2650* 提高 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-CN/env-vars) 高于思考预算2712* 将 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-CN/env-vars) 提高到思考预算以上
2651* 请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)以了解预算如何与输出长度交互2713* 请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)以了解预算如何与输出长度交互
2652 2714
2653<h3 id="tool-use-or-thinking-block-mismatch">2715<h3 id="tool-use-or-thinking-block-mismatch">
2668 2730
2669**要做什么：**2731**要做什么：**
2670 2732
2671* 如果您使用 Opus 4.7 或 Opus 4.8，首先运行 `claude update`。v2.1.156 之前的版本可以在正常工具使用期间触发此错误，`/rewind` 不会清除它。2733* 如果您使用 Opus 4.7 或 Opus 4.8，首先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，`/rewind` 不会清除它。
2672* 运行 `/rewind`，或按 Esc 两次，回退到损坏轮次之前的检查点并从那里继续。请参阅[检查点](/docs/zh-CN/checkpointing)以了解如何创建和恢复检查点。2734* 运行 `/rewind`，或按 Esc 两次，回退到损坏轮次之前的检查点并从那里继续。请参阅[检查点](/docs/zh-CN/checkpointing)以了解如何创建和恢复检查点。
2673 2735
2674<h3 id="invalid-data-in-redacted-thinking-block">2736<h3 id="invalid-data-in-redacted-thinking-block">
2692 删除了不支持的工具内容2754 删除了不支持的工具内容
2693</h3>2755</h3>
2694 2756
2695当 Claude Code 直接连接到 Anthropic API 并加载或预览保存的会话时，它删除 Anthropic API 不接受的工具内容，并在两个思考块之间删除的内容所在的位置留下此行：2757当 Claude Code 直接连接到 Anthropic API 并加载或预览保存的会话时，它删除 Anthropic API 不接受的工具内容，并在两个思考块之间被删除内容所在的位置留下此行：
2696 2758
2697```text theme={null}2759```text theme={null}
2698[Unsupported tool content removed]2760[Unsupported tool content removed]
2702 2764
2703**要做什么：**2765**要做什么：**
2704 2766
2705* 当您看到占位符行时，无需任何操作。会话继续而不删除的内容。2767* 当您看到占位符行时，无需任何操作。会话在没有已删除内容的情况下继续。
2706* 如果恢复会话的每一轮都失败，显示 400 错误，运行 `claude update` 并再次恢复会话。v2.1.246 之前的版本不删除内容。2768* 如果恢复会话的每一轮都失败，显示 400 错误，运行 `claude update` 并再次恢复会话。v2.1.246 之前的版本不删除内容。
2707 2769
2708<h3 id="role-system-must-precede-an-assistant-message">2770<h3 id="role-system-must-precede-an-assistant-message">
2715API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...2777API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
2716```2778```
2717 2779
2718Claude Code 将其一些提醒和附件文本作为系统消息发送到对话中。当 API 拒绝一个的位置时，Claude Code 重试请求一次，将该文本作为普通用户消息发送。API 的兄弟位置措辞，如 `use the top-level 'system' parameter for the initial system prompt`，获得相同的恢复。2780Claude Code 将其一些提醒和附件文本作为系统消息发送到对话中。当 API 拒绝其中一条的位置时，Claude Code 重试请求一次，将该文本作为普通用户消息发送。API 的同类位置措辞，如 `use the top-level 'system' parameter for the initial system prompt`，获得相同的恢复。
2719 2781
2720当错误确实出现时，被拒绝的系统消息不是 Claude Code 可以删除的。这通常意味着 Claude Code 和 API 之间的代理或 [LLM gateway](/docs/zh-CN/llm-gateway) 添加了自己的系统消息或重新排序了对话。2782当错误确实出现时，被拒绝的系统消息不是 Claude Code 可以删除的。这通常意味着 Claude Code 和 API 之间的代理或 [LLM gateway](/docs/zh-CN/llm-gateway) 添加了自己的系统消息。
2721 2783
2722**要做什么：**2784**要做什么：**
2723 2785
2724* 如果错误在通过 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 配置的代理或网关后的每一轮上重复，连接而不使用代理以确认源，并向操作它的人报告错误2786* 如果错误在通过 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 配置的代理或网关后的每一轮上重复，不使用代理进行连接以确认来源，并向运营它的人报告错误
2725* 运行 `/clear` 以启动新对话。如果错误也在那里返回，原因在请求路径上，而不在保存的对话中。2787* 运行 `/clear` 以启动新对话。如果错误也在那里返回，原因在请求路径上，而不在保存的对话中。
2726 2788
2727在 v2.1.280 之前，Claude Code 不识别此措辞，因此当被拒绝的系统消息是 Claude Code 本身发送的时，错误也出现，对话的每个后来轮次都以相同方式失败。2789在 v2.1.280 之前，Claude Code 不识别此措辞，因此当被拒绝的系统消息是 Claude Code 本身发送的时，错误也出现，对话的每个后来轮次都以相同方式失败。
2739API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block2801API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block
2740```2802```
2741 2803
2742来自 API 的托管[网络搜索工具](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)的结果携带只有 API 可以读取的加密字段。`encrypted_stdout` 措辞命名读取这样的结果的托管代码执行程序的输出，API 也加密。API 拒绝重放它无法解密的内容的请求，如为不同组织生成的内容。2804来自 API 的托管[网络搜索工具](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)的结果携带只有 API 可以读取的加密字段。`encrypted_stdout` 措辞命名读取这样的结果的托管代码执行程序的输出，API 也会对其加密。API 拒绝重放它无法解密的内容的请求，如为不同组织生成的内容。
2743 2805
2744Claude Code 自己的 [WebSearch 工具](/docs/zh-CN/tools-reference#websearch-tool-behavior)将搜索结果记录为纯文本，因此这些块通常通过代理或 [LLM gateway](/docs/zh-CN/llm-gateway) 到达对话，该网关自己运行了托管网络搜索。2806Claude Code 自己的 [WebSearch 工具](/docs/zh-CN/tools-reference#websearch-tool-behavior)将搜索结果记录为纯文本，因此这些块通常通过自己运行了托管网络搜索的代理或 [LLM gateway](/docs/zh-CN/llm-gateway) 到达对话。
2745 2807
2746对于三个网络搜索措辞，Claude Code 将搜索调用、结果和引用排除在它发送的内容之外并重试请求一次，因此会话继续而不显示错误。`encrypted_stdout` 措辞没有这样的恢复，因此该消息仍然到达您。在 v2.1.282 之前，Claude Code 也保留了被拒绝的网络搜索块，每个后来的轮次和 `/compact` 都以相同方式失败。2808对于三个网络搜索措辞，Claude Code 将搜索调用、结果和引用排除在它发送的内容之外并重试请求一次，因此会话继续而不显示错误。`encrypted_stdout` 措辞没有这样的恢复，因此该消息仍然会显示给您。在 v2.1.282 之前，Claude Code 也保留了被拒绝的网络搜索块，每个后来的轮次和 `/compact` 都以相同方式失败。
2747 2809
2748**要做什么：**2810**要做什么：**
2749 2811
2750* 如果您在 v2.1.281 或更早版本上，每一轮都失败，显示网络搜索措辞之一，运行 `claude update` 并恢复会话2812* 如果您在 v2.1.281 或更早版本上，每一轮都失败，显示网络搜索措辞之一，运行 `claude update` 并恢复会话
2751* 如果错误持续，或消息命名 `encrypted_stdout`，运行 `/rewind` 回退到添加内容的轮次之前的检查点，或运行 `/clear` 启动不携带它的对话2813* 如果错误持续，或消息命名 `encrypted_stdout`，运行 `/rewind` 回退到添加内容的轮次之前的检查点，或运行 `/clear` 启动不携带它的对话
2752* 如果您在代理或网关后运行 Claude Code，向操作它的人报告错误2814* 如果您在代理或网关后运行 Claude Code，向运营它的人报告错误
2753 2815
2754<h3 id="usage-policy-refusal">2816<h3 id="usage-policy-refusal">
2755 使用政策拒绝2817 使用政策拒绝
2757 2819
2758API 拒绝了响应，因为对话中的内容触发了[使用政策](https://www.anthropic.com/legal/aup)检查。2820API 拒绝了响应，因为对话中的内容触发了[使用政策](https://www.anthropic.com/legal/aup)检查。
2759 2821
2760消息包括请求 ID 和消息 ID，您可以引用给支持，如果您认为拒绝不正确。2822消息包括请求 ID 和消息 ID，如果您认为拒绝不正确，可以将其提供给支持人员。
2761 2823
2762```text theme={null}2824```text theme={null}
2763API Error: Opus 4.6 can't help with this. Start a new session to continue.2825API Error: Opus 4.6 can't help with this. Start a new session to continue.
2767 2829
2768消息命名拒绝的模型，或当没有记录模型时命名 `Claude`。2830消息命名拒绝的模型，或当没有记录模型时命名 `Claude`。
2769 2831
2770检查评估完整对话，而不仅仅是您的最新提示，因此在同一会话中发送新消息通常会重新触发相同的拒绝。使用 `--continue` 或 `--resume` 退出并重新打开会话后也是如此，因为磁盘上的记录仍然包含触发内容。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，此消息也涵盖模型的安全措施标记为网络安全主题的请求。请参阅[安全措施标记了网络安全主题](#safety-measures-flagged-a-cybersecurity-topic)。2832检查评估完整对话，而不仅仅是您的最新提示词，因此在同一会话中发送新消息通常会重新触发相同的拒绝。使用 `--continue` 或 `--resume` 退出并重新打开会话后也是如此，因为磁盘上的会话记录仍然包含触发内容。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，此消息也涵盖模型的安全措施标记为网络安全主题的请求。请参阅[安全措施标记了网络安全主题](#safety-measures-flagged-a-cybersecurity-topic)。
2771 2833
2772在 v2.1.219 之前，消息读取 `Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.`2834在 v2.1.219 之前，消息读取 `Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.`
2773 2835
2775 2837
2776* 按 Esc 两次或运行 `/rewind` 回退到触发拒绝的轮次之前的检查点，然后重新表述或采取不同的方法。请参阅[检查点](/docs/zh-CN/checkpointing)。2838* 按 Esc 两次或运行 `/rewind` 回退到触发拒绝的轮次之前的检查点，然后重新表述或采取不同的方法。请参阅[检查点](/docs/zh-CN/checkpointing)。
2777* 如果您无法识别哪个轮次导致了它，运行 `/clear` 在同一项目中启动新对话。您之前的对话保留在磁盘上，并在 `/resume` 中保持可用。2839* 如果您无法识别哪个轮次导致了它，运行 `/clear` 在同一项目中启动新对话。您之前的对话保留在磁盘上，并在 `/resume` 中保持可用。
2778* 在[非交互模式](/docs/zh-CN/headless)(`-p`) 中，其中回退不可用，在没有 `--continue` 的新会话中使用重新表述的提示重试。政策检查因模型而异，因此使用 `--model` 切换到不同的模型也可能在某些情况下解决拒绝。2840* 在[非交互模式](/docs/zh-CN/headless)(`-p`) 中，由于无法回退，请在不带 `--continue` 的新会话中使用重新表述的提示词重试。政策检查因模型而异，因此使用 `--model` 切换到不同的模型在某些情况下也可能解决拒绝。
2779 2841
2780<h3 id="safety-measures-flagged-a-cybersecurity-topic">2842<h3 id="safety-measures-flagged-a-cybersecurity-topic">
2781 安全措施标记了网络安全主题2843 安全措施标记了网络安全主题
2787API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude2849API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude
2788```2850```
2789 2851
2790消息链接到[网络安全验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。在 Opus 5.5 和 Sonnet 5.5 上，消息以 `<model>'s safeguards flagged this session` 开头。当标记的类别有可用的后备模型时，Claude Code [切换模型](/docs/zh-CN/model-config#automatic-model-fallback) 而不是显示此错误。2852消息链接到[网络安全验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。在 Opus 5.5 和 Sonnet 5.5 上，消息改以 `<model>'s safeguards flagged this session` 开头。当标记的类别有可用的备用模型时，Claude Code [切换模型](/docs/zh-CN/model-config#automatic-model-fallback)而不是显示此错误。
2791 2853
2792在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标记会产生[使用政策拒绝](#usage-policy-refusal)消息。2854在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标记会改为产生[使用政策拒绝](#usage-policy-refusal)消息。
2793 2855
2794保护措施本身是服务器端的，早于 v2.1.203；自那以后的客户端版本仅更改了消息的措辞。2856保护措施本身是服务器端的，早于 v2.1.203；自那以后的客户端版本仅更改了消息的措辞。
2795从 v2.1.203 到 v2.1.218，消息读取 `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:` 后跟相同的帮助中心链接，交互式会话附加 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`2857从 v2.1.203 到 v2.1.218，消息读取 `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:` 后跟相同的帮助中心链接，交互式会话附加 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`
2852 命令行错误2914 命令行错误
2853</h2>2915</h2>
2854 2916
2855这些错误来自 `claude` 命令行及其子命令、您在提示符处提交的命令名称，以及诸如 `/security-review` 之类的命令，这些命令在运行其提示之前通过运行 shell 命令来收集上下文。它们也来自 `/tui`，它会重新启动 CLI。2917这些错误来自 `claude` 命令行及其子命令、您在提示符处提交的命令名称，以及 `/security-review` 等在其提示词运行前通过执行 shell 命令收集上下文的命令。它们也可能来自会重新启动 CLI 的 `/tui`。
2856 2918
2857<h3 id="conflict-between-bg-and-print">2919<h3 id="conflict-between-bg-and-print">
2858 `--bg` 和 `--print` 之间的冲突2920 `--bg` 与 `--print` 冲突
2859</h3>2921</h3>
2860 2922
2861此消息需要 Claude Code v2.1.198 或更高版本。您在同一个 `claude` 调用中将 `--bg` 与 `-p` 或 `--print` 结合使用。`--bg` 启动一个[后台会话](/docs/zh-CN/agent-view#from-your-shell)，您稍后可以使用 `claude agents` 附加到该会话，而 `--print` 以[非交互方式](/docs/zh-CN/headless)运行，永远不会启动 `claude agents` 附加到的交互会话。在 v2.1.198 之前，此组合会以静默方式创建一个永远无法附加的后台作业。2923此消息需要 Claude Code v2.1.198 或更高版本。您在同一次 `claude` 调用中将 `--bg` 与 `-p` 或 `--print` 组合使用。`--bg` 会启动一个[后台会话](/docs/zh-CN/agent-view#from-your-shell)，您稍后可通过 `claude agents` 附加到该会话；而 `--print` 以[非交互方式](/docs/zh-CN/headless)运行，永远不会启动 `claude agents` 所附加的交互式会话。在 v2.1.198 之前，这种组合会静默创建一个永远无法附加的后台作业。
2862 2924
2863```text theme={null}2925```text theme={null}
2864--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.2926--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.
2865```2927```
2866 2928
2867**应该做什么：**2929**解决方法：**
2868 2930
2869* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，所以 `claude --bg "<task>"` 是完整的命令。请参阅[从您的 shell 分派新代理](/docs/zh-CN/agent-view#from-your-shell)。2931* 去掉 `-p` 或 `--print`。`--bg` 将提示词作为其位置参数，因此 `claude --bg "<task>"` 就是完整的命令。请参阅[从 shell 中 Dispatch 新的 Agent](/docs/zh-CN/agent-view#from-your-shell)。
2870* 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`2932* 若要以非交互方式运行提示词并打印结果，而不是创建后台会话，请去掉 `--bg` 并运行 `claude -p "<task>"`
2933
2934<h3 id="conflict-between-a-system-prompt-flag-and-its-file-form">
2935 系统提示词标志与其文件形式冲突
2936</h3>
2937
2938您在一次 `claude` 调用中同时传入了 [`--append-subagent-system-prompt`](/docs/zh-CN/cli-reference#cli-flags) 和 `--append-subagent-system-prompt-file`，因此 `claude` 以退出码 1 退出，而不是启动会话：
2939
2940```text theme={null}
2941Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.
2942```
2943
2944在 v2.1.283 之前，当您将 `--system-prompt` 与 `--system-prompt-file` 一起传入，或将 `--append-system-prompt` 与 `--append-system-prompt-file` 一起传入时，`claude` 也会以同样的方式退出，因为这些成对的标志会相互冲突，而不是[组合使用](/docs/zh-CN/cli-reference#system-prompt-flags)。在这些版本中，消息会指出您组合使用的那一对标志。
2945
2946**解决方法：**
2947
2948* 保留标志的一种形式并去掉另一种。若要将固定的提示词文件与每次运行的文本组合，请在启动前将文本合并到文件中，而不是同时传入两个标志
2871 2949
2872<h3 id="invalid-agents-configuration">2950<h3 id="invalid-agents-configuration">
2873 无效的 `--agents` 配置2951 无效的 `--agents` 配置
2874</h3>2952</h3>
2875 2953
2876您传递给 `--agents` 的值无效，所以 `claude` 以代码 1 退出，而不是启动会话。当您传递 `--safe-mode` 或设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars#variables) 时，Claude Code 会完全忽略 `--agents`。使用 `--resume` 或 `--continue` 时，不会检查内联 JSON 值，会话会启动；从文件读取的值在每次启动时都会被检查。在 v2.1.242 之前，Claude Code 无论如何都会启动会话。2954您传给 `--agents` 的值无效，因此 `claude` 以退出码 1 退出，而不是启动会话。当您传入 `--safe-mode` 或设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars#variables) 时，Claude Code 会完全忽略 `--agents`。使用 `--resume` 或 `--continue` 时，内联 JSON 值不会被检查，会话会正常启动；从文件读取的值则在每次启动时都会被检查。在 v2.1.242 之前，Claude Code 无论如何都会启动会话。
2877 2955
2878```text theme={null}2956```text theme={null}
2879Error: Invalid --agents configuration:2957Error: Invalid --agents configuration:
2880<what failed>2958<what failed>
2881```2959```
2882 2960
2883第一行之后的内容取决于值如何失败。Claude Code 按顺序运行这些检查，并在第一个失败的检查处停止。如果您的值有两种问题，您只有在修复第一个问题后才会看到第二个问题：2961第一行之后的内容取决于该值失败的方式。Claude Code 按顺序运行以下检查，并在第一个失败的检查处停止。如果您的值有两类问题，您只有在修复第一类问题后才会看到第二类：
2884 2962
28851. 当值以 `{` 开头但不能解析为 JSON，或 `--agents` 文件的内容不能解析时，Claude Code 会打印一行 `invalid JSON:`，其中包含 JSON 解析器自己的消息29631. 当值以 `{` 开头但无法解析为 JSON，或 `--agents` 文件的内容无法解析时，Claude Code 会打印一行 `invalid JSON:`，其中包含 JSON 解析器自身的消息
28862. 当它解析但代理定义与 [CLI 定义的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)的架构不匹配时，Claude Code 会为每个问题打印一行29642. 当值可以解析，但某个 Agent 定义不符合 [CLI 定义的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)的 schema 时，Claude Code 会为每个问题打印一行
28873. 当代理名称以 `-` 开头时，Claude Code 会打印 `<name>: agent names must not start with '-'`29653. 当 Agent 名称以 `-` 开头时，Claude Code 会打印 `<name>: agent names must not start with '-'`
2888 2966
2889当有超过 20 行问题时，Claude Code 会打印前 20 行，并用 `…and N more` 替换其余部分。2967当问题行超过 20 行时，Claude Code 会打印前 20 行，并将其余部分替换为 `…and N more`。
2890 2968
2891使用 `--print` 时，`--agents` 也接受 [JSON 文件的路径](/docs/zh-CN/sub-agents#choose-the-subagent-scope)代替内联对象。在 v2.1.281 之前，`--agents` 仅接受内联 JSON，并将文件路径视为无效 JSON。文件形式有其自己的拒绝，打印在此消息的位置，包括这些：2969使用 `--print` 时，`--agents` 还接受 [JSON 文件的路径](/docs/zh-CN/sub-agents#choose-the-subagent-scope)来代替内联对象。在 v2.1.281 之前，`--agents` 只接受内联 JSON，并将文件路径视为无效 JSON。文件形式有其自身的拒绝情况，会代替此消息打印出来，包括以下几种：
2892 2970
2893* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**：Claude Code 在交互会话中将值读取为文件路径。将定义作为内联 JSON 传递，或添加 `-p` 从文件读取它们。2971* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**：Claude Code 在交互式会话中将该值读取为文件路径。请以内联 JSON 的形式传入定义，或添加 `-p` 以从文件读取定义。
2894* **`Error: --agents file not found: <path>`**：该路径不存在任何文件。不以 `{` 开头且不是有效 JSON 的值被读取为路径，所以您的 shell 损坏的内联 JSON 也可能以这种方式失败。检查路径或引号，然后再次运行命令。2972* **`Error: --agents file not found: <path>`**：该路径下不存在文件。不以 `{` 开头且不是有效 JSON 的值会被读取为路径，因此被 shell 破坏的内联 JSON 也可能以这种方式失败。请检查路径或引号，然后再次运行命令。
2895 2973
2896**应该做什么：**2974**解决方法：**
2897 2975
2898* 修复消息列出的每个问题，然后再次运行命令。请参阅 [CLI 定义的子代理采用的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。2976* 修复消息列出的每个问题，然后再次运行命令。请参阅 [CLI 定义的子代理可接受的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。
2899 2977
2900<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">2978<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">
2901 无法从 `--restricted` 会话创建云会话2979 无法从 `--restricted` 会话创建云端会话
2902</h3>2980</h3>
2903 2981
2904当您使用 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 启动会话时，Claude Code 拒绝从中创建[云会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)，因为新会话将在受限进程之外运行，不会强制执行受限模式。Claude Code 在客户端拒绝，在联系服务器之前，所以不会创建云会话：2982当您使用 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 启动会话时，Claude Code 会拒绝从该会话创建[云端会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)，因为新会话将在受限进程之外运行，不会强制执行受限模式。Claude Code 在客户端拒绝，且发生在联系服务器之前，因此不会创建任何云端会话：
2905 2983
2906```text theme={null}2984```text theme={null}
2907Cloud sessions cannot be created from a --restricted session: they would not enforce it.2985Cloud sessions cannot be created from a --restricted session: they would not enforce it.
2908```2986```
2909 2987
2910**应该做什么：**2988**解决方法：**
2911 2989
2912* 在受限会话中本地运行任务2990* 在受限会话中本地运行该任务
2913* 如果您控制会话的启动方式，请启动一个没有 `--restricted` 的新 `claude` 会话，并从那里创建云会话2991* 如果您能控制会话的启动方式，请不带 `--restricted` 启动一个新的 `claude` 会话，并从那里创建云端会话
2914 2992
2915在 v2.1.248 之前，Claude Code 没有 `--restricted` 标志；较早的版本会以未知选项错误拒绝该标志本身。2993在 v2.1.248 之前，Claude Code 没有 `--restricted` 标志；更早的版本会以未知选项错误拒绝该标志本身。
2916 2994
2917<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">2995<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">
2918 您的组织的策略禁用了云会话2996 云端会话已被您组织的策略禁用
2919</h3>2997</h3>
2920 2998
2921您的组织的 `allow_remote_sessions` 策略已关闭，所以[云会话](/docs/zh-CN/claude-code-on-the-web)和使用它们的命令不可用：2999您组织的 `allow_remote_sessions` 策略已关闭，因此[云端会话](/docs/zh-CN/claude-code-on-the-web)以及使用云端会话的命令均不可用：
2922 3000
2923```text theme={null}3001```text theme={null}
2924Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.3002Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.
2925```3003```
2926 3004
2927当您[从终端创建云会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)时，消息会出现，当您提交需要云会话的命令时，例如 `/teleport`、`/remote-env` 或 `/web-setup`。在 v2.1.268 之前，提交其中一个命令会返回[`Unknown command`](#unknown-command)。3005当您[从终端创建云端会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)时，以及当您提交需要云端会话的命令（例如 `/teleport`、`/remote-env` 或 `/web-setup`）时，会出现此消息。在 v2.1.268 之前，提交这些命令之一会返回 [`Unknown command`](#unknown-command)。
2928 3006
2929这是一个服务器端组织策略，所以它不能从本地设置、环境变量或 CLI 标志中被覆盖。3007这是服务器端的组织策略，因此无法通过本地设置、环境变量或 CLI 标志覆盖。
2930 3008
2931如果 Claude Code 还没有加载您的组织策略或无法获取它，这些命令会回答 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`。3009如果 Claude Code 尚未加载您组织的策略或无法获取该策略，这些命令会改为回复 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`。
2932 3010
2933**应该做什么：**3011**解决方法：**
2934 3012
2935* 请您的组织中的[所有者](/docs/zh-CN/server-managed-settings#access-control)在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 的 Claude Code 管理员设置中启用云会话3013* 请您组织中的 [Owner](/docs/zh-CN/server-managed-settings#access-control) 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 的 Claude Code 管理设置中启用云端会话
2936* 如果消息说它无法验证策略，请检查您的网络连接，然后重新启动 Claude Code 并重试3014* 如果消息提示无法验证策略，请检查您的网络连接，然后重新启动 Claude Code 并重试
2937 3015
2938<h3 id="the-json-schema-value-is-not-a-valid-json-schema">3016<h3 id="the-json-schema-value-is-not-a-valid-json-schema">
2939 `--json-schema` 值不是有效的 JSON Schema3017 `--json-schema` 的值不是有效的 JSON Schema
2940</h3>3018</h3>
2941 3019
2942您传递给 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 的架构在[非交互模式](/docs/zh-CN/headless#get-structured-output)中失败了 JSON Schema 编译，所以 `claude` 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出，没有错误，任何使用 `format` 关键字的架构都被视为无效。3020您在[非交互模式](/docs/zh-CN/headless#get-structured-output)下传给 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 的 schema 未能通过 JSON Schema 编译，因此 `claude` 以退出码 1 退出，而不是运行提示词。在 v2.1.205 之前，无效的 schema 会产生非结构化输出且不报错，并且任何使用 `format` 关键字的 schema 都会被视为无效。
2943 3021
2944```text theme={null}3022```text theme={null}
2945Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values3023Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values
2946```3024```
2947 3025
2948第二个冒号后的文本是验证器的诊断，并命名失败的关键字或位置。使用 `format` 关键字的架构，例如 `"format": "email"`，是有效的：Claude Code 接受 `format` 作为注释，不强制执行它。3026第二个冒号之后的文本是验证器的诊断信息，会指出失败的关键字或位置。使用 `format` 关键字的 schema（例如 `"format": "email"`）是有效的：Claude Code 将 `format` 作为注解接受，但不强制执行。
2949 3027
2950Claude Code 在架构编译之前运行两个检查：它拒绝不可解析的 JSON 值，显示 `Error: --json-schema is not valid JSON`，以及不是对象的有效 JSON，显示 `Error: --json-schema must be a JSON object`。3028Claude Code 在 schema 编译之前会运行两项检查：对于无法解析为 JSON 的值，它会以 `Error: --json-schema is not valid JSON` 拒绝；对于是有效 JSON 但不是对象的值，它会以 `Error: --json-schema must be a JSON object` 拒绝。
2951 3029
2952**应该做什么：**3030**解决方法：**
2953 3031
2954* 修复诊断命名的架构部分，然后重新运行命令3032* 修复诊断信息指出的 schema 部分，然后重新运行命令
2955* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)以获取工作架构和命令3033* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)，了解可用的 schema 和命令示例
2956 3034
2957<h3 id="settings-file-exceeds-the-2mib-limit">3035<h3 id="settings-file-exceeds-the-2mib-limit">
2958 设置文件超过 2MiB 限制3036 设置文件超过 2MiB 限制
2959</h3>3037</h3>
2960 3038
2961您传递给 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 的文件大于 2 MiB，所以 `claude` 在启动时以代码 1 退出，而不是加载它。在 v2.1.214 之前，Claude Code 读取文件时没有大小检查，多 GB 文件或诸如 `/dev/zero` 之类的设备文件会无限增长内存。3039您传给 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 的文件大于 2 MiB，因此 `claude` 在启动时以退出码 1 退出，而不是加载该文件。在 v2.1.214 之前，Claude Code 读取文件时不检查大小，数 GB 的文件或 `/dev/zero` 之类的设备文件会使内存无限增长。
2962 3040
2963```text theme={null}3041```text theme={null}
2964Error: Settings file exceeds the 2MiB limit: /path/to/settings.json3042Error: Settings file exceeds the 2MiB limit: /path/to/settings.json
2965```3043```
2966 3044
2967Claude Code 以相同的方式拒绝不是常规文件的 `--settings` 路径：设备、FIFO 或套接字报告 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`，后跟路径，目录报告 `EISDIR` 原因。3045对于不是常规文件的 `--settings` 路径，Claude Code 也会以同样方式拒绝：设备、FIFO 或套接字会报告 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`，后跟路径；目录则会报告 `EISDIR` 原因。
2968 3046
2969**应该做什么：**3047**解决方法：**
2970 3048
2971* 将 `--settings` 指向 2 MiB 以下的常规 JSON 设置文件。请参阅[设置](/docs/zh-CN/settings)了解格式。3049* 将 `--settings` 指向一个小于 2 MiB 的常规 JSON 设置文件。有关格式，请参阅[设置](/docs/zh-CN/settings)。
2972 3050
2973<h3 id="the-current-directory-no-longer-exists">3051<h3 id="the-current-directory-no-longer-exists">
2974 当前目录不再存在3052 当前目录已不存在
2975</h3>3053</h3>
2976 3054
2977您从一个在您的 shell 进入后被删除或移动的目录启动了 `claude`，例如另一个 shell 删除的 worktree 或临时目录。Claude Code 无法读取其工作目录，所以它在启动会话之前以代码 1 退出，在交互和[非交互](/docs/zh-CN/headless)模式中都是如此。在 v2.1.239 之前，Claude Code 会因缩小的捆绑源和原始 `ENOENT ... uv_cwd` 堆栈在 stderr 上崩溃，而不是显示此消息。3055您从一个在 shell 进入后被删除或移动的目录中启动了 `claude`，例如被另一个 shell 删除的 worktree 或临时目录。Claude Code 无法读取其工作目录，因此无论是交互模式还是[非交互](/docs/zh-CN/headless)模式，它都会在启动会话前以退出码 1 退出。在 v2.1.239 之前，Claude Code 会崩溃，并在 stderr 上输出压缩后的 bundle 源代码和原始的 `ENOENT ... uv_cwd` 堆栈，而不是此消息。
2978 3056
2979```text theme={null}3057```text theme={null}
2980The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.3058The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
2981error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.3059error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.
2982```3060```
2983 3061
2984两种形式的原因和修复是相同的。3062两种形式的原因和解决方法相同。
2985 3063
2986当 Claude Code 因其他原因（例如权限更改）无法读取工作目录时，消息会命名错误代码：`Can't read the current directory (EACCES). Start Claude Code from a different directory.`3064当 Claude Code 因其他原因（例如权限变更）无法读取工作目录时，消息会改为指出错误代码：`Can't read the current directory (EACCES). Start Claude Code from a different directory.`
2987 3065
2988在 macOS 上，`~/Desktop`、`~/Documents`、`~/Downloads` 或 iCloud Drive 中目录的 `EPERM` 通常意味着 macOS 阻止您的终端应用访问该文件夹。读取该文件夹的其他命令也会以相同的方式失败：即使使用 `sudo`，`ls` 也会报告 `Operation not permitted`。3066在 macOS 上，如果 `~/Desktop`、`~/Documents`、`~/Downloads` 或 iCloud Drive 中的目录出现 `EPERM`，通常意味着 macOS 阻止了您的终端应用访问该文件夹。读取该文件夹的其他命令也会以同样方式失败：在那里运行 `ls` 会报告 `Operation not permitted`，即使使用 `sudo` 也是如此。
2989 3067
2990**应该做什么：**3068**解决方法：**
2991 3069
2992* 更改为存在的目录，例如您的主目录或项目目录，然后再次运行 `claude`3070* 切换到一个存在的目录，例如您的主目录或项目目录，然后再次运行 `claude`
2993* 如果目录在同一路径被重新创建，您的 shell 仍然持有已删除的目录。运行 `cd "$PWD"` 或离开并重新进入目录，然后再次运行 `claude`3071* 如果该目录已在同一路径下重新创建，您的 shell 仍持有已删除的那个目录。运行 `cd "$PWD"`，或离开后重新进入该目录，然后再次运行 `claude`
2994* 对于 macOS 上的 `EPERM`，使用 Cmd+Q 退出您的终端应用，重新打开它，返回该文件夹，然后运行 `claude`。如果该文件夹中的 `ls` 仍然失败，请打开**系统设置 > 隐私和安全 > 文件和文件夹**，为您的终端应用打开该文件夹，然后重新打开终端3072* 对于 macOS 上的 `EPERM`，请使用 Cmd+Q 退出终端应用，重新打开它，返回该文件夹，然后运行 `claude`。如果在该文件夹中运行 `ls` 仍然失败，请打开 **System Settings > Privacy & Security > Files and Folders**，为您的终端应用启用该文件夹，然后重新打开终端
2995 3073
2996<h3 id="temp-directory-refused-or-cannot-be-created">3074<h3 id="temp-directory-refused-or-cannot-be-created">
2997 临时目录被拒绝或无法创建3075 临时目录被拒绝或无法创建
2998</h3>3076</h3>
2999 3077
3000在 macOS 和 Linux 上，Claude Code 在启动时创建一个私有临时目录 `claude-<uid>`，位于系统临时目录或 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 覆盖下。当目录无法创建，或该路径处的现有条目未通过安全检查时，Claude Code 将失败打印到 stderr 并以代码 1 退出，而不是启动会话：3078在 macOS 和 Linux 上，Claude Code 会在启动时创建一个私有临时目录，即系统临时目录下或 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 覆盖路径下的 `claude-<uid>`。当该目录无法创建，或该路径上已存在的条目未通过安全检查时，Claude Code 会将失败信息打印到 stderr，并以退出码 1 退出，而不是启动会话：
3001 3079
3002```text wrap theme={null}3080```text wrap theme={null}
3003ENOSPC: no space left on device, mkdir '/tmp/claude-501'3081ENOSPC: no space left on device, mkdir '/tmp/claude-501'
3009Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.3087Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.
3010```3088```
3011 3089
3012**应该做什么：**3090**解决方法：**
3013 3091
3014* 对于 `ENOSPC`，释放保存临时目录的卷上的磁盘空间3092* 对于 `ENOSPC`，请释放存放临时目录的卷上的磁盘空间
3015* 对于 `Refusing to use it` 形式，删除命名的条目本身，而不是链接指向的内容，然后再次启动 Claude Code；对于 `owned by uid` 形式，只有管理员或该用户可以删除它3093* 对于 `Refusing to use it` 形式，请删除所指出的条目本身（而不是链接指向的内容），然后再次启动 Claude Code；对于 `owned by uid` 形式，只有管理员或该用户才能删除它
3016* 对于 `is not readable`，在命名目录上运行 `chmod 0700`，或删除它并重新启动3094* 对于 `is not readable`，请对所指出的目录运行 `chmod 0700`，或将其删除后重新启动
3017* 在任何这些情况下，将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为您控制的目录并启动 Claude Code，保留被拒绝的路径不变3095* 在上述任何情况下，都可以将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为您控制的目录，然后再次启动 Claude Code，而不必处理被拒绝的路径
3018 3096
3019<h3 id="directory-couldnt-be-resolved-to-a-real-location">3097<h3 id="directory-couldnt-be-resolved-to-a-real-location">
3020 目录无法解析为真实位置3098 无法将目录解析为真实位置
3021</h3>3099</h3>
3022 3100
3023您为工作目录的子目录运行了 `/add-dir`，Claude Code 无法将目录解析为其真实位置。3101您对工作目录的某个子目录运行了 `/add-dir`，而 Claude Code 无法将该目录解析为其真实位置。
3024 3102
3025您已经可以访问工作目录的子目录，所以 `/add-dir` 只加载其 skills、命令和代理。在加载它们之前，Claude Code 检查目录的真实位置（解析任何符号链接）是否在工作目录内。当 Claude Code 无法解析该位置时，它不加载任何内容并显示此消息：3103您对工作目录的子目录已有文件访问权限，因此 `/add-dir` 只会加载其中的 skill、命令和 Agent。在加载之前，Claude Code 会检查该目录解析所有符号链接后的真实位置是否位于工作目录内。当 Claude Code 无法解析该位置时，它不会加载任何内容，并显示以下消息：
3026 3104
3027```text theme={null}3105```text theme={null}
3028packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.3106packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.
3029```3107```
3030 3108
3031**应该做什么：**3109**解决方法：**
3032 3110
3033* 检查路径是否命名工作目录内的真实目录，然后再次运行 `/add-dir`3111* 检查该路径是否指向工作目录内的真实目录，然后再次运行 `/add-dir`
3034* 消息不会改变您的文件访问权限；它只报告目录的 `.claude/` 内容未被加载3112* 此消息不会改变您的文件访问权限；它只报告该目录的 `.claude/` 内容未被加载
3035 3113
3036在 v2.1.261 之前，当工作目录在 `/net/<host>` 自动挂载上时，此消息也会为每个 `/add-dir <subdirectory>` 出现，Claude Code 按设计拒绝解析路径；目录很好，重试无法帮助。3114在 v2.1.261 之前，当工作目录位于 `/net/<host>` 自动挂载点上时，每次运行 `/add-dir <subdirectory>` 都会出现此消息，因为 Claude Code 在设计上不会解析这类路径；目录本身没有问题，重试也无济于事。
3037 3115
3038<h3 id="workspace-not-trusted-when-starting-remote-control">3116<h3 id="workspace-not-trusted-when-starting-remote-control">
3039 启动远程控制时工作区不受信任3117 启动 Remote Control 时工作区不受信任
3040</h3>3118</h3>
3041 3119
3042您在未信任的目录中使用 `claude remote-control` 或其 `claude rc` 别名启动了[远程控制](/docs/zh-CN/remote-control)服务器模式，命令无法询问您是否信任它。例如，命令的标准输入或标准输出不是终端，因为其中一个被重定向或管道化。命令以代码 1 退出：3120您在一个尚未信任的目录中使用 `claude remote-control` 或其别名 `claude rc` 启动了 [Remote Control](/docs/zh-CN/remote-control) 服务器模式，而该命令无法询问您是否信任该目录。例如，该命令的标准输入或标准输出不是终端，因为其中之一被重定向或通过管道传输。该命令以退出码 1 退出：
3043 3121
3044```text theme={null}3122```text theme={null}
3045Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.3123Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.
3046```3124```
3047 3125
3048两个也以 `Error: Workspace not trusted.` 开头的变体也出现在足够小的终端中，无法显示信任目录会打开什么，或一个没有报告其大小的终端。放大窗口或切换到正常终端窗口，然后再次运行 `claude rc`。3126还有两个同样以 `Error: Workspace not trusted.` 开头的变体，会出现在太小而无法显示信任该目录将启用哪些内容的终端中，或出现在未报告其尺寸的终端中。请放大窗口或切换到普通终端窗口，然后再次运行 `claude rc`。
3049 3127
3050在您的主目录中，消息是不同的，因为工作区信任对话永远不会为主目录保存信任，所以在那里接受它无法满足此检查。在 v2.1.214 之前，主目录显示上面的消息，其建议在那里无法成功。3128在您的主目录中，消息会有所不同，因为工作区信任对话框永远不会为主目录保存信任，所以在那里接受信任无法满足此检查。在 v2.1.214 之前，主目录会显示上面的消息，而其建议在那里无法奏效。
3051 3129
3052```text theme={null}3130```text theme={null}
3053Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).3131Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).
3054```3132```
3055 3133
3056如果您在 [`Trust <directory>?` 问题](/docs/zh-CN/remote-control#requirements)处回答 `n` 或按 Enter，命令会打印一条 `Remote Control did not start` 消息，命名目录并以代码 1 退出。再次运行 `claude rc` 以回答 `y`。3134如果您在 [`Trust <directory>?` 问题](/docs/zh-CN/remote-control#requirements)处回答 `n` 或按 Enter，该命令会打印一条指出该目录的 `Remote Control did not start` 消息，并以退出码 1 退出。再次运行 `claude rc` 即可回答 `y`。
3057 3135
3058**应该做什么：**3136**解决方法：**
3059 3137
3060* 首先从终端信任目录：在那里运行 `claude rc` 并回答 `y`，或运行 `claude` 并接受[工作区信任对话](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，然后再次运行您的原始命令3138* 先从终端信任该目录：在那里运行 `claude rc` 并回答 `y`，或在那里运行 `claude` 并接受[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，然后再次运行您原来的命令
3061* 在您的主目录中，更改为项目目录并在那里启动远程控制3139* 如果在主目录中，请切换到项目目录，并在那里启动 Remote Control
3062 3140
3063在 v2.1.284 之前，命令从不询问，即使在终端中也是如此。3141在 v2.1.284 之前，即使在终端中，该命令也从不询问。
3064 3142
3065<h3 id="not-carried-over-to-the-sessions-remote-control-starts">3143<h3 id="not-carried-over-to-the-sessions-remote-control-starts">
3066 未被远程控制启动的会话继承3144 不会传递到 Remote Control 启动的会话
3067</h3>3145</h3>
3068 3146
3069您使用全局 `claude` 标志在 `remote-control` 动词之前启动了[远程控制](/docs/zh-CN/remote-control)，该标志会限制或配置远程控制启动的会话，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在动词之前的标志永远不会到达这些会话。Claude Code 拒绝启动，命名标志：3147您在 `remote-control` 动词之前使用了一个全局 `claude` 标志来启动 [Remote Control](/docs/zh-CN/remote-control)，而该标志会限制或配置 Remote Control 启动的会话，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在动词之前的标志永远不会传递到这些会话。Claude Code 会拒绝启动，并指出该标志：
3070 3148
3071```text theme={null}3149```text theme={null}
3072Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).3150Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).
3073```3151```
3074 3152
3075Claude Code 不拒绝无害的全局标志，例如 `--verbose`、`--model` 或包装器注入的 `--session-id` 或 `--plugin-dir`：它忽略它们，远程控制启动。3153对于丢弃后无害的全局标志，例如 `--verbose`、`--model`，或由包装器注入的 `--session-id` 或 `--plugin-dir`，Claude Code 不会拒绝：它会忽略这些标志，Remote Control 照常启动。
3076 3154
3077Claude Code 也拒绝启动一个它还不认识为无害的全局标志，所以较新版本中添加的标志可能会出现在此消息中，直到稍后的版本将其标记为无害。3155对于尚未被识别为无害的全局标志，Claude Code 也会拒绝启动，因此较新版本中新增的标志可能会出现在此消息中，直到后续版本将其标记为无害。
3078 3156
3079**应该做什么：**3157**解决方法：**
3080 3158
3081* 从动词之前删除标志，并在其后传递[远程控制自己的选项](/docs/zh-CN/remote-control#start-a-remote-control-session)；`claude remote-control --help` 列出它们3159* 从动词之前移除该标志，并在动词之后传入 [Remote Control 自己的选项](/docs/zh-CN/remote-control#start-a-remote-control-session)；`claude remote-control --help` 会列出这些选项
3082* 当被拒绝的标志是 `--permission-mode` 时，运行 `claude remote-control --permission-mode <mode>` 为远程控制启动的会话设置权限模式3160* 当被拒绝的标志是 `--permission-mode` 时，请运行 `claude remote-control --permission-mode <mode>` 来为 Remote Control 启动的会话设置权限模式
3083 3161
3084在 v2.1.248 之前，当全局标志首先出现时，`claude remote-control` 不接受其自己的标志，命令失败并显示未知选项错误。3162在 v2.1.248 之前，当全局标志在前时，`claude remote-control` 不接受其自身的标志，命令会以 `unknown option` 错误失败。
3085 3163
3086<h3 id="claude-import-is-not-yet-available-in-this-build">3164<h3 id="claude-import-is-not-yet-available-in-this-build">
3087 claude import 在此构建中尚不可用3165 claude import 在此版本中尚不可用
3088</h3>3166</h3>
3089 3167
3090您运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，Claude Code 发现导入流已关闭，所以命令以代码 1 退出，而不是启动导入。在 v2.1.222 之前，关闭导入流的构建将 `import` 视为提示并启动交互会话，而不是打印此消息。3168您运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，而 Claude Code 发现导入流程处于关闭状态，因此该命令以退出码 1 退出，而不是开始导入。在 v2.1.222 之前，关闭了导入流程的版本会将 `import` 视为提示词，并启动交互式会话，而不是打印此消息。
3091 3169
3092```text theme={null}3170```text theme={null}
3093`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.3171`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.
3094```3172```
3095 3173
3096Claude Code 通过从 Anthropic 获取并在磁盘上缓存的功能标志打开 `claude import`。此消息意味着缓存的值已关闭。原因通常是以下之一：3174Claude Code 通过从 Anthropic 获取并缓存在磁盘上的功能标志来启用 `claude import`。此消息表示缓存的值为关闭。原因通常是以下之一：
3097 3175
3098* 您自安装以来还没有启动会话，所以 Claude Code 还没有获取标志。第一个 `claude import` 即使功能对您可用，也可能打印此消息。3176* 安装后您尚未启动过会话，因此 Claude Code 还没有获取该标志。即使该功能对您可用，第一次运行 `claude import` 也可能打印此消息。
3099* 您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform，或通过[Claude 应用网关](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)使用 Claude Code。Claude Code 在这些会话中不获取功能标志，所以 `claude import` 保持不可用。3177* 您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 使用 Claude Code，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations) 使用。Claude Code 在这些会话中不会获取功能标志，因此 `claude import` 始终不可用。
3100* 您设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`DISABLE_GROWTHBOOK` 或 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars)，它们关闭功能标志获取，所以 `claude import` 保持不可用。3178* 您设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`DISABLE_GROWTHBOOK` 或 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars)，这些会关闭功能标志的获取，因此 `claude import` 始终不可用。
3101 3179
3102**应该做什么：**3180**解决方法：**
3103 3181
3104* 在新安装上，启动 `claude`，等待会话加载，退出，然后再次运行 `claude import`3182* 在全新安装中，启动 `claude`，等待会话加载完成后退出，然后再次运行 `claude import`
3105* 在功能标志获取保持关闭的地方，自己设置配置：使用 [`claude mcp add`](/docs/zh-CN/mcp#installing-mcp-servers) 添加 MCP 服务器，并创建您想要继承的 [`CLAUDE.md` 文件](/docs/zh-CN/memory#how-claude-md-files-load)、[skills 和命令](/docs/zh-CN/skills#where-skills-live)以及[子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。消息也命名 `~/.claude/settings.json`。在 `claude import` 继承的配置中，该文件仅保存[权限模式](/docs/zh-CN/settings-reference#permission-settings)；Claude Code 不从中读取 MCP 服务器。3183* 在功能标志获取始终关闭的情况下，请自行进行配置：使用 [`claude mcp add`](/docs/zh-CN/mcp#installing-mcp-servers) 添加 MCP 服务器，并创建您想迁移的 [`CLAUDE.md` 文件](/docs/zh-CN/memory#how-claude-md-files-load)、[skill 和命令](/docs/zh-CN/skills#where-skills-live)以及[子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。消息中还提到了 `~/.claude/settings.json`。在 `claude import` 迁移的配置中，该文件只保存[权限模式](/docs/zh-CN/settings-reference#permission-settings)；Claude Code 不会从中读取 MCP 服务器。
3106 3184
3107<h3 id="could-not-read-claude-code-config">3185<h3 id="could-not-read-claude-code-config">
3108 无法读取 Claude Code 配置3186 无法读取 Claude Code 配置
3109</h3>3187</h3>
3110 3188
3111您在 Claude Code 无法解析 `~/.claude.json` 时运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，这是它存储您的登录和每个项目状态的文件。子命令读取该文件以检查可用性，但不显示交互会话显示的恢复对话，所以它以代码 1 退出。在 v2.1.222 之前，`claude import` 使用不可读的配置文件启动交互会话，其恢复对话处理该文件。3189您运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，而此时 Claude Code 无法解析 `~/.claude.json`，即存储您的登录信息和各项目状态的文件。该子命令会读取此文件以检查可用性，但不会显示交互式会话中的恢复对话框，因此它以退出码 1 退出。在 v2.1.222 之前，配置文件不可读时运行 `claude import` 会启动交互式会话，由其恢复对话框处理该文件。
3112 3190
3113```text theme={null}3191```text theme={null}
3114Could not read Claude Code config — run `claude` with no arguments to recover it.3192Could not read Claude Code config — run `claude` with no arguments to recover it.
3115```3193```
3116 3194
3117**应该做什么：**3195**解决方法：**
3118 3196
3119* 运行不带参数的 `claude`。Claude Code 检测无效文件并提供重置它。然后再次运行 `claude import`。3197* 不带参数运行 `claude`。Claude Code 会检测到无效文件并提供重置选项。然后再次运行 `claude import`。
3120* 要保留您所做的手动编辑，请在编辑器中修复 `~/.claude.json` 中的 JSON 语法，然后重新运行 `claude import`3198* 若要保留您手动进行的编辑，请改为在编辑器中修复 `~/.claude.json` 中的 JSON 语法，然后重新运行 `claude import`
3121 3199
3122<h3 id="could-not-import-a-server-from-claude-desktop">3200<h3 id="could-not-import-a-server-from-claude-desktop">
3123 无法从 Claude Desktop 导入服务器3201 无法从 Claude Desktop 导入服务器
3124</h3>3202</h3>
3125 3203
3126Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器停止了导入。3204Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的某个服务器。该命令仍会导入其他选中的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会中止导入。
3127 3205
3128```text theme={null}3206```text theme={null}
3129Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3207Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
3130```3208```
3131 3209
3132服务器名称后的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符，例如空格和句号，而 `claude mcp` 限制为字母、数字、连字符和下划线。其他原因包括失败验证的服务器配置和被您的组织的 [MCP 策略](/docs/zh-CN/managed-mcp)阻止的服务器。3210服务器名称之后的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中包含空格和句点等字符，而 `claude mcp` 将其限制为字母、数字、连字符和下划线。其他原因包括服务器配置未通过验证，以及服务器被您组织的 [MCP 策略](/docs/zh-CN/managed-mcp)阻止。
3133 3211
3134**应该做什么：**3212**解决方法：**
3135 3213
3136* 在 `claude_desktop_config.json` 中重命名服务器以仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`3214* 在 `claude_desktop_config.json` 中将服务器重命名为仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`
3137* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名称下直接添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。3215* 使用 `claude mcp add` 或 `claude mcp add-json` 以有效名称直接添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。
3138 3216
3139<h3 id="cannot-add-mcp-server-to-the-managed-scope">3217<h3 id="cannot-add-mcp-server-to-the-managed-scope">
3140 无法将 MCP 服务器添加到托管范围3218 无法将 MCP 服务器添加到 managed 作用域
3141</h3>3219</h3>
3142 3220
3143您使用 `--scope managed` 运行了 `claude mcp add` 或 `claude mcp add-json`。该范围保存您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 托管设置提供的服务器。Claude Code 仅从托管设置读取它们，所以命令无法向该范围写入服务器。3221您使用 `--scope managed` 运行了 `claude mcp add` 或 `claude mcp add-json`。该作用域保存的是您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 托管设置提供的服务器。Claude Code 只从托管设置中读取它们，因此该命令无法将服务器写入该作用域。
3144 3222
3145```text theme={null}3223```text theme={null}
3146Cannot add MCP server to scope: managed3224Cannot add MCP server to scope: managed
3147```3225```
3148 3226
3149**应该做什么：**3227**解决方法：**
3228
3229* 将服务器添加到您可以写入的作用域：`local`、`user` 或 `project`。不带 `--scope` 时，该命令使用 `local`。请参阅 [MCP 安装作用域](/docs/zh-CN/mcp#mcp-installation-scopes)
3230* 若要向组织中的每个用户提供该服务器，请将其添加到您部署的托管设置中的 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers)
3150 3231
3151* 将服务器添加到您可以写入的范围：`local`、`user` 或 `project`。不带 `--scope` 时，命令使用 `local`。请参阅 [MCP 安装范围](/docs/zh-CN/mcp#mcp-installation-scopes)3232<h3 id="cannot-add-mcp-server-when-managed-settings-allow-only-plugin-servers">
3152* 要为您的组织中的每个用户提供服务器，请将其添加到您部署的托管设置中的 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers)3233 托管设置仅允许插件服务器时无法添加 MCP 服务器
3234</h3>
3235
3236您运行了 `claude mcp add` 或 `claude mcp add-json`，而您组织的托管设置将 [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) 设为 `true` 或设为包含 `mcp` 的列表。在该设置下，Claude Code 不会从 `~/.claude.json` 或 `.mcp.json` 加载 MCP 服务器，因此该命令以退出码 1 退出，而不是保存一个永远不会加载的服务器：
3237
3238```text theme={null}
3239Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.
3240```
3241
3242`claude mcp add-from-claude-desktop` 会将您选择的每个服务器报告为未导入，并以此消息作为原因。[`/import`](/docs/zh-CN/commands#all-commands) 会为其尝试添加的每个 MCP 服务器报告此消息，但仍会导入它找到的其他项目。
3243
3244在 v2.1.284 之前，这些命令会保存服务器并报告成功，但该服务器永远不会加载。
3245
3246**解决方法：**
3247
3248* 安装一个提供该服务器的[插件](/docs/zh-CN/plugins/install)
3249* 请您的管理员通过[插件](/docs/zh-CN/plugins/org)分发该服务器；如果它是远程 HTTP 或 SSE 服务器，也可以通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 提供
3153 3250
3154<h3 id="cant-read-mcp-json">3251<h3 id="cant-read-mcp-json">
3155 无法读取 .mcp.json3252 无法读取 .mcp.json
3156</h3>3253</h3>
3157 3254
3158读取项目的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope) 的命令，例如 `claude mcp add` 或 `claude mcp add-json` 使用 `--scope project`，或 `claude mcp remove`，发现您当前目录中的文件不是常规文件或大于 2 MiB，所以它以此错误退出，而不是读取文件。3255读取项目 [`.mcp.json`](/docs/zh-CN/mcp#project-scope) 的命令（例如带 `--scope project` 的 `claude mcp add` 或 `claude mcp add-json`，或 `claude mcp remove`）发现当前目录中的该文件不是常规文件或大于 2 MiB，因此以此错误退出，而不是读取该文件。
3159 3256
3160```text theme={null}3257```text theme={null}
3161Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.3258Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.
3162```3259```
3163 3260
3164在 v2.1.257 之前，`.mcp.json` 处的 FIFO 使命令永远等待，没有输出，指向诸如 `/dev/zero` 之类的设备文件的符号链接会增长内存，直到进程被杀死。3261在 v2.1.257 之前，`.mcp.json` 处的 FIFO 会使命令永远等待且没有任何输出，而指向 `/dev/zero` 等设备文件的符号链接会使内存持续增长，直到进程被终止。
3165 3262
3166**应该做什么：**3263**解决方法：**
3167 3264
3168* 检查您当前目录中 `.mcp.json` 处的内容。将其替换为 [project-scope 格式](/docs/zh-CN/mcp#project-scope)中的普通 JSON 文件，或删除它，然后再次运行命令。3265* 检查当前目录中 `.mcp.json` 处是什么内容。将其替换为采用[项目作用域格式](/docs/zh-CN/mcp#project-scope)的普通 JSON 文件，或将其删除，然后再次运行命令。
3169 3266
3170<h3 id="mcp-server-was-not-saved-or-removed">3267<h3 id="mcp-server-was-not-saved-or-removed">
3171 MCP 服务器未被保存或删除3268 MCP 服务器未被保存或移除
3172</h3>3269</h3>
3173 3270
3174您为 `user` 或 `local` [范围](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`。两个范围都存储在 `~/.claude.json` 中，当 Claude Code 在写入后读取该文件时，更改不在该文件中。命令以此错误退出，而不是其成功行。3271您对 `user` 或 `local` [作用域](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`。这两个作用域都存储在 `~/.claude.json` 中，而 Claude Code 在写入后回读该文件时，发现更改并不在其中。该命令以此错误退出，而不是输出成功信息。
3175 3272
3176```text theme={null}3273```text theme={null}
3177MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.3274MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.
3178```3275```
3179 3276
3180删除后，消息读取 `was not removed from` 并以 `then remove the server again` 结尾。对于 `local` 范围服务器，路径后跟项目目录条目所属的，如 `(local scope for /path/to/project)`。3277移除操作之后，消息会显示为 `was not removed from`，并以 `then remove the server again` 结尾。对于 `local` 作用域的服务器，路径之后会跟上该条目所属的项目目录，形式为 `(local scope for /path/to/project)`。
3181 3278
3182在 v2.1.283 之前，`claude mcp add`、`claude mcp add-json` 和 `claude mcp remove` 即使更改没有到达文件也报告成功。3279在 v2.1.283 之前，即使更改未写入文件，`claude mcp add`、`claude mcp add-json` 和 `claude mcp remove` 也会报告成功。
3183 3280
3184**应该做什么：**3281**解决方法：**
3185 3282
3186* 使消息命名的文件可写，或在沙箱外运行命令，然后再次运行相同的添加或删除命令。3283* 使消息中指出的文件可写，或在沙箱之外运行命令，然后再次运行相同的添加或移除命令。
3187 3284
3188<h3 id="mcp-server-may-not-have-been-saved-or-removed">3285<h3 id="mcp-server-may-not-have-been-saved-or-removed">
3189 MCP 服务器可能未被保存或删除3286 MCP 服务器可能未被保存或移除
3190</h3>3287</h3>
3191 3288
3192您为 `user` 或 `local` [范围](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`，Claude Code 无法读取 `~/.claude.json` 回来确认更改。更改可能在磁盘上，也可能不在。括号中的文本是该读取的错误。3289您对 `user` 或 `local` [作用域](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`，而 Claude Code 无法回读 `~/.claude.json` 来确认更改。更改可能已写入磁盘，也可能没有。括号中的文本是该读取操作的错误。
3193 3290
3194```text theme={null}3291```text theme={null}
3195MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.3292MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.
3196```3293```
3197 3294
3198删除后，消息读取 `may not have been removed` 并以 `then remove the server again if it is still listed` 结尾。3295移除操作之后，消息会显示为 `may not have been removed`，并以 `then remove the server again if it is still listed` 结尾。
3199 3296
3200在 v2.1.283 之前，命令即使更改无法确认也报告成功。3297在 v2.1.283 之前，即使无法确认更改，这些命令也会报告成功。
3201 3298
3202**应该做什么：**3299**解决方法：**
3203 3300
3204* 运行 `claude mcp get <name>` 检查更改是否在磁盘上。对于 `local` 范围服务器，从服务器所属的项目目录运行它，因为本地范围是每个项目的。3301* 运行 `claude mcp get <name>` 检查更改是否已写入磁盘。对于 `local` 作用域的服务器，请从该服务器所属的项目目录运行，因为 local 作用域是按项目划分的。
3205* 如果服务器在添加后丢失，或在删除后仍然列出，请再次运行相同的添加或删除命令。3302* 如果添加后服务器缺失，或移除后仍被列出，请再次运行相同的添加或移除命令。
3206 3303
3207<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">3304<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">
3208 服务器是 Anthropic 托管的，不支持本地 OAuth3305 服务器由 Anthropic 托管，不支持本地 OAuth
3209</h3>3306</h3>
3210 3307
3211您为 MCP 服务器启动了登录，其 URL 指向通过第三方身份提供商进行身份验证的 Anthropic 托管连接器主机。这些主机包括 `microsoft365.mcp.claude.com`、`gmail.mcp.claude.com` 和 `gcal.mcp.claude.com`。Claude Code 拒绝为这些主机从 `/mcp` 面板和 `claude mcp login` 启动其本地 OAuth 流，因为[它们的登录仅通过 claude.ai 工作](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。3308您为某个 MCP 服务器发起了登录，而其 URL 指向一个通过第三方身份提供商进行身份验证的 Anthropic 托管连接器主机。这些主机包括 `microsoft365.mcp.claude.com`、`gmail.mcp.claude.com` 和 `gcal.mcp.claude.com`。对于这些主机，Claude Code 在 `/mcp` 面板和 `claude mcp login` 中都会拒绝启动其本地 OAuth 流程，因为[它们的登录只能通过 claude.ai 完成](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。
3212 3309
3213```text theme={null}3310```text theme={null}
3214"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3311"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.
3215```3312```
3216 3313
3217**应该做什么：**3314**解决方法：**
3218 3315
3219* 使用 `claude mcp remove <name>` 删除您的条目，以便它不能隐藏同一 URL 处的 claude.ai 连接器3316* 使用 `claude mcp remove <name>` 移除您的条目，以免它遮蔽同一 URL 上的 claude.ai 连接器
3220* 删除后，在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 连接服务，同时登录到您在 Claude Code 中使用的帐户。连接后，如果您的活跃身份验证方法是 claude.ai 订阅登录，[连接器会自动出现在 Claude Code 中](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)3317* 移除后，在登录您在 Claude Code 中使用的账户的情况下，前往 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 连接该服务。连接完成后，如果您当前的身份验证方式是 claude.ai 订阅登录，[该连接器会自动出现在 Claude Code 中](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)
3221 3318
3222<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">3319<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">
3223 服务器拒绝了由配置的 headersHelper 生成的 Authorization 标头3320 服务器拒绝了由配置的 headersHelper 生成的 Authorization 标头
3224</h3>3321</h3>
3225 3322
3226其 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 提供 `Authorization` 标头的 MCP 服务器以 HTTP 401 或 403 回答连接，所以 Claude Code 将连接报告为失败。因为助手提供 `Authorization` 标头，Claude Code [不会回退到 OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 对于服务器：3323某个由 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 提供 `Authorization` 标头的 MCP 服务器以 HTTP 401 或 403 响应了连接，因此 Claude Code 报告连接失败。由于该辅助程序提供了 `Authorization` 标头，Claude Code 对该服务器[不会回退到 OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)：
3227 3324
3228```text theme={null}3325```text theme={null}
3229Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.3326Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.
3230```3327```
3231 3328
3232Claude Code 在每次连接尝试时重新运行助手，所以在短暂拒绝后重试，例如令牌轮换竞争，可以使用新凭证成功。3329Claude Code 在每次连接尝试时都会重新运行该辅助程序，因此在暂时性拒绝（例如令牌轮换竞争）之后重试，可能会以新的凭据成功连接。
3233 3330
3234**应该做什么：**3331**解决方法：**
3235 3332
3236* 按照 Claude Code 运行它的方式自己运行 `headersHelper` 命令：从 [Claude Code 运行它的目录](/docs/zh-CN/mcp#where-the-helper-runs)，使用 [Claude Code 为其设置的环境变量](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)，以及不使用 [Claude Code 为来自项目 `.mcp.json`、插件或项目代理文件的服务器删除的凭证变量](/docs/zh-CN/mcp#which-variables-a-helper-can-read)。检查它是否打印服务器端点接受的 `Authorization` 值3333* 按照 Claude Code 运行它的方式自行运行 `headersHelper` 命令：在 [Claude Code 运行它的目录](/docs/zh-CN/mcp#where-the-helper-runs)中，使用 [Claude Code 为其设置的环境变量](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)，并且对于来自项目 `.mcp.json`、插件或项目 Agent 文件的服务器，不包含 [Claude Code 移除的凭据变量](/docs/zh-CN/mcp#which-variables-a-helper-can-read)。检查它打印的 `Authorization` 值是否被服务器端点接受
3237* 修复助手或其凭证源后，在 `/mcp` 中选择服务器并选择**重新连接**3334* 修复辅助程序或其凭据来源后，在 `/mcp` 中选择该服务器并选择 **Reconnect**
3238 3335
3239在 v2.1.248 之前，Claude Code 为其助手提供 `Authorization` 标头的服务器运行 OAuth 发现。该发现可能失败，显示 `Incompatible auth server: does not support dynamic client registration` 而不是报告被拒绝的凭证。3336在 v2.1.248 之前，对于由辅助程序提供 `Authorization` 标头的服务器，Claude Code 会运行 OAuth 发现。该发现过程可能以 `Incompatible auth server: does not support dynamic client registration` 失败，而不是报告被拒绝的凭据。
3240 3337
3241<h3 id="mcp-permission-prompt-tool-not-found">3338<h3 id="mcp-permission-prompt-tool-not-found">
3242 未找到 MCP 权限提示工具3339 未找到 MCP 权限提示工具
3243</h3>3340</h3>
3244 3341
3245您传递给 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的工具在运行首次需要权限决定时不在连接的 MCP 工具中，要么因为其服务器从未连接，要么因为没有连接的服务器公开该名称的工具。Claude Code 仍然发送您的提示：[非交互](/docs/zh-CN/headless)运行在第一个工具调用时以此错误和退出代码 1 退出，所以即使请求已发出，它也不会产生答案。在第一个提示之前，Claude Code 等待最多由 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 设置的每个服务器连接超时 30 秒，以便该服务器连接。在 v2.1.206 之前，启动不等待服务器完成连接，所以启动缓慢但健康的服务器也会产生此错误。3342当运行首次需要权限决策时，您传给 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的工具不在已连接的 MCP 工具之中，原因可能是其服务器从未连接，或者没有任何已连接的服务器公开该名称的工具。Claude Code 仍会发送您的提示词：[非交互](/docs/zh-CN/headless)运行会在第一次工具调用时以此错误和退出码 1 退出，因此即使请求已经发出，也不会产生回答。在第一个提示词之前，Claude Code 会等待该服务器连接，最长等待由 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 设置的每服务器连接超时时间 30 秒。在 v2.1.206 之前，启动时不会等待服务器完成连接，因此启动较慢但运行正常的服务器也会产生此错误。
3246 3343
3247```text theme={null}3344```text theme={null}
3248Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3345Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
3249```3346```
3250 3347
3251`Available MCP tools:` 后的列表命名已连接的 MCP 工具。3348`Available MCP tools:` 之后的列表列出了已连接的 MCP 工具。
3252 3349
3253**应该做什么：**3350**解决方法：**
3254 3351
3255* 检查服务器启动并保持连接：在同一目录中运行 `claude mcp list` 并确认服务器列为已连接3352* 检查服务器能否启动并保持连接：在同一目录中运行 `claude mcp list`，并确认该服务器被列为已连接
3256* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称匹配3353* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称一致
3257* 如果服务器需要超过 30 秒才能启动，请提高 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars)3354* 如果服务器需要超过 30 秒才能启动，请调高 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars)
3258 3355
3259<h3 id="oauth-callback-port-is-already-in-use">3356<h3 id="oauth-callback-port-is-already-in-use">
3260 OAuth 回调端口已在使用中3357 OAuth 回调端口已被占用
3261</h3>3358</h3>
3262 3359
3263当您使用 OAuth 登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。如果该侦听器需要的端口被另一个进程持有，登录失败，显示此消息。这主要发生在[固定回调端口](/docs/zh-CN/mcp#use-a-fixed-oauth-callback-port)通过 [`MCP_OAUTH_CALLBACK_PORT`](/docs/zh-CN/env-vars) 变量或 `--callback-port` 设置时，因为没有一个 Claude Code 会选择可用端口。3360当您使用 OAuth 登录远程 MCP 服务器时，Claude Code 会启动一个本地监听器来接收登录回调。如果该监听器所需的端口被另一个进程占用，登录就会以此消息失败。这种情况主要发生在通过 [`MCP_OAUTH_CALLBACK_PORT`](/docs/zh-CN/env-vars) 变量或 `--callback-port` 设置了[固定回调端口](/docs/zh-CN/mcp#use-a-fixed-oauth-callback-port)时，因为如果没有设置，Claude Code 会选择一个可用端口。
3264 3361
3265```text theme={null}3362```text theme={null}
3266OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.3363OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.
3267```3364```
3268 3365
3269在 Windows 上，建议的命令是 `netstat -ano | findstr :<port>`。3366在 Windows 上，建议的命令改为 `netstat -ano | findstr :<port>`。
3270 3367
3271**应该做什么：**3368**解决方法：**
3272 3369
3273* 运行消息中的命令以找到持有端口的进程，并停止它或等待它完成3370* 运行消息中的命令找到占用该端口的进程，然后将其停止或等待其结束
3274* 如果另一个程序永久需要该端口，请向服务器注册不同的重定向 URI，并使用 `MCP_OAUTH_CALLBACK_PORT` 或 `--callback-port` 设置其端口，以及您使用的任何一个3371* 如果其他程序需要永久占用该端口，请向服务器注册一个不同的重定向 URI，并使用 `MCP_OAUTH_CALLBACK_PORT` 或 `--callback-port`（取决于您使用哪一个）设置其端口
3275* 然后再次启动登录，例如通过在 `/mcp` 中选择服务器3372* 然后重新开始登录，例如在 `/mcp` 中选择该服务器
3276 3373
3277<h3 id="no-available-ports-for-oauth-redirect">3374<h3 id="no-available-ports-for-oauth-redirect">
3278 OAuth 重定向没有可用的端口3375 没有可用于 OAuth 重定向的端口
3279</h3>3376</h3>
3280 3377
3281当您使用[OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。当 Claude Code 无法为其绑定本地端口时，登录失败，显示此消息。机器上的某些内容阻止它在 `127.0.0.1` 上侦听，例如安全软件或拒绝本地侦听器的沙箱策略。3378当您使用 [OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 登录远程 MCP 服务器时，Claude Code 会启动一个本地监听器来接收登录回调。当 Claude Code 无法为其绑定本地端口时，登录会以此消息失败。机器上的某些东西阻止了它在 `127.0.0.1` 上监听，例如安全软件或拒绝本地监听器的沙箱策略。
3282 3379
3283```text theme={null}3380```text theme={null}
3284No available ports for OAuth redirect3381No available ports for OAuth redirect
3285```3382```
3286 3383
3287在 v2.1.268 之前，Claude Code 不会回退到操作系统分配的端口，所以消息也会在仅其自选端口无法绑定时出现。这可能发生在 Hyper-V 保留覆盖 Claude Code 选择的端口的端口范围的 Windows 主机上。3384在 v2.1.268 之前，Claude Code 不会回退到由操作系统分配的端口，因此当仅是其自行选择的端口无法绑定时，也会出现此消息。这种情况可能发生在 Hyper-V 预留了覆盖 Claude Code 选择范围的端口区间的 Windows 主机上。
3288 3385
3289**应该做什么：**3386**解决方法：**
3290 3387
3291* 检查安全软件或沙箱策略是否阻止进程在 `127.0.0.1` 上侦听，并允许 Claude Code 绑定本地端口3388* 检查安全软件或沙箱策略是否阻止进程在 `127.0.0.1` 上监听，并允许 Claude Code 绑定本地端口
3292* 然后再次启动登录，例如通过在 `/mcp` 中选择服务器3389* 然后重新开始登录，例如在 `/mcp` 中选择该服务器
3293 3390
3294<h3 id="security-review-fails-without-origin-head">3391<h3 id="security-review-fails-without-origin-head">
3295 /security-review 在没有 origin/HEAD 时失败3392 缺少 origin/HEAD 时 /security-review 失败
3296</h3>3393</h3>
3297 3394
3298[`/security-review`](/docs/zh-CN/commands#all-commands) 通过将您的分支与 `origin/HEAD` 进行比较来构建其审查上下文，这是记录您的 `origin` 远程上哪个分支是默认分支的本地 ref。当该 ref 不存在时，收集差异的 git 命令失败，审查在启动前停止。3395[`/security-review`](/docs/zh-CN/commands#all-commands) 通过将您的分支与 `origin/HEAD` 进行 diff 来构建其审查上下文，`origin/HEAD` 是记录 `origin` 远程上哪个分支为默认分支的本地引用。当该引用不存在时，用于收集 diff 的 git 命令会失败，审查在开始之前就会停止。
3299 3396
3300```text theme={null}3397```text theme={null}
3301Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]3398Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
3304'git <command> [<revision>...] -- [<file>...]'3401'git <command> [<revision>...] -- [<file>...]'
3305```3402```
3306 3403
3307消息可能引用 `git log` 或不同的 `git diff`。Git 仅在远程通告默认分支且您的获取 refspec 覆盖它时创建 `origin/HEAD`，完整的远程克隆带有提交时会这样做。在这些设置中 ref 丢失：3404消息中引用的也可能是 `git log` 或其他 `git diff` 命令。只有当远程公布了默认分支且您的 fetch refspec 覆盖了它时，Git 才会创建 `origin/HEAD`；对包含提交的远程执行完整的 `git clone` 时就是如此。在以下设置中，该引用会缺失：
3308 3405
3309* 单分支或 CI 检出，它获取太窄的 refspec3406* 单分支或 CI 检出，其 fetch 的 refspec 范围过窄
3310* 远程服务器端 HEAD 指向没有人推送的分支3407* 服务器端 HEAD 指向一个从未有人推送过的分支的远程
3311* 没有 `origin` 远程的存储库，或您从未获取的存储库3408* 没有 `origin` 远程的仓库，或您从未执行过 fetch 的仓库
3312 3409
3313Claude Code 为任何 [injects dynamic context](/docs/zh-CN/skills#when-an-injected-command-fails) 的 skill 显示相同的错误，失败的注入命令会中止该 skill 的调用。两个兄弟字符串在命令运行之前就会触发：3410对于任何[注入动态上下文](/docs/zh-CN/skills#when-an-injected-command-fails)的 skill，Claude Code 都会显示相同的错误，注入的命令失败会中止该 skill 的调用。还有两条相关字符串会在命令运行之前就触发：
3314 3411
3315* `Shell command permission check failed for pattern "..."`：命令的权限检查不允许它。[Permission checks on injected commands](/docs/zh-CN/skills#permission-checks-on-injected-commands) 涵盖在每个权限模式中哪些结果会中止，以及如何使用 `allowed-tools` 预先批准命令3412* `Shell command permission check failed for pattern "..."`：该命令的权限检查未允许它运行。[注入命令的权限检查](/docs/zh-CN/skills#permission-checks-on-injected-commands)介绍了在每种权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令
3316* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：skill 的 frontmatter 在没有它的机器上要求 bash。安装 Git for Windows 或将 frontmatter 更改为 `shell: powershell`。请参阅[注入命令如何运行](/docs/zh-CN/skills#how-injected-commands-run)3413* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求使用 bash，但机器上没有 bash。请安装 Git for Windows，或将 frontmatter 改为 `shell: powershell`。请参阅[注入命令的运行方式](/docs/zh-CN/skills#how-injected-commands-run)
3317 3414
3318**应该做什么：**3415**解决方法：**
3319 3416
3320* 通过命名您的远程默认分支创建 ref：`git remote set-head origin <default-branch>`。只要本地跟踪 ref `origin/<default-branch>` 存在，这就有效。如果它不存在，如在单分支克隆中，首先获取分支：运行 `git remote set-branches --add origin <branch>`，然后 `git fetch origin`，然后重新运行 set-head 命令。重新运行 `/security-review`。3417* 通过指定远程的默认分支来创建该引用：`git remote set-head origin <default-branch>`。只要本地跟踪引用 `origin/<default-branch>` 存在，此方法就有效。如果它不存在（例如在单分支克隆中），请先 fetch 该分支：运行 `git remote set-branches --add origin <branch>`，然后运行 `git fetch origin`，再重新运行 set-head 命令。然后重新运行 `/security-review`。
3321* 如果您不想命名分支，运行 `git fetch origin` 然后 `git remote set-head origin --auto`，它询问远程其默认分支是什么。当远程不通告默认分支时它失败，显示 `error: Cannot determine remote HEAD`，因为它是空的或其 HEAD 指向没有人推送的分支；改为显式命名分支。当您的克隆不获取该分支时它失败，显示 `error: Not a valid ref`；首先按上面的方式扩大 refspec。3418* 如果您不想指定分支名，请运行 `git fetch origin`，然后运行 `git remote set-head origin --auto`，它会向远程询问哪个分支是默认分支。当远程未公布默认分支时（因为远程为空或其 HEAD 指向从未有人推送过的分支），它会以 `error: Cannot determine remote HEAD` 失败；此时请显式指定分支名。当您的克隆不 fetch 该分支时，它会以 `error: Not a valid ref` 失败；请先按上述方法扩大 refspec。
3322* 如果存储库没有远程，使用 `git remote add origin <url>` 添加一个并在创建 ref 之前获取。如果远程是空的，首先使用 `git push -u origin HEAD` 推送您的分支，并在 set-head 命令中命名该分支；`origin/HEAD` 然后指向您刚推送的分支，所以 `/security-review` 看到空差异，直到分支与其分歧。3419* 如果仓库没有远程，请使用 `git remote add origin <url>` 添加一个，并在创建引用之前执行 fetch。如果远程为空，请先使用 `git push -u origin HEAD` 推送您的分支，并在 set-head 命令中指定该分支；此后 `origin/HEAD` 指向您刚推送的分支，因此在该分支与其产生分歧之前，`/security-review` 看到的 diff 为空。
3323 3420
3324<h3 id="input-must-be-provided-when-using-print">3421<h3 id="input-must-be-provided-when-using-print">
3325 使用 `--print` 时必须提供输入3422 使用 `--print` 时必须提供输入
3326</h3>3423</h3>
3327 3424
3328裸 `claude` 需要 stdout 是终端才能启动交互 UI。当 stdout 被重定向，或控制台不是真实终端时，例如 PowerShell ISE 和某些 IDE 输出窗格，`claude` 改为以[非交互](/docs/zh-CN/headless)模式运行。这与 `claude -p` 相同，它需要提示，所以消息命名 `--print`，即使您没有传递标志。在任何地方传递 `-p`/`--print` 而不带提示且 stdin 上没有任何内容会产生相同的错误。3425不带参数的 `claude` 需要 stdout 是终端才能启动交互式 UI。当 stdout 被重定向，或控制台不是真正的终端（例如 PowerShell ISE 和某些 IDE 输出窗格）时，`claude` 会改为以[非交互方式](/docs/zh-CN/headless)运行。这与 `claude -p` 是同一种模式，而该模式需要提示词，因此即使您没有传入该标志，消息中也会提到 `--print`。在任何环境中，传入 `-p`/`--print` 却没有提示词、也没有通过 stdin 管道传入内容，都会产生相同的错误。
3329 3426
3330```text theme={null}3427```text theme={null}
3331Error: Input must be provided either through stdin or as a prompt argument when using --print3428Error: Input must be provided either through stdin or as a prompt argument when using --print
3332```3429```
3333 3430
3334**应该做什么：**3431**解决方法：**
3335 3432
3336* 对于交互使用，在真实终端中运行 `claude`：Windows Terminal 或 PowerShell 控制台而不是 ISE，以及您的 IDE 的集成终端而不是输出窗格3433* 对于交互式使用，请在真正的终端中运行 `claude`：使用 Windows Terminal 或 PowerShell 控制台而非 ISE，使用 IDE 的集成终端而非输出窗格
3337* 对于一次性使用，传递提示：`claude -p "your question"`，或使用 `echo "your question" | claude -p` 管道它3434* 对于一次性使用，请传入提示词：`claude -p "your question"`，或通过管道传入：`echo "your question" | claude -p`
3435
3436<h3 id="claude-code-cant-read-the-keyboard-here">
3437 Claude Code 在此处无法读取键盘输入
3438</h3>
3439
3440您在没有 [`-p`](/docs/zh-CN/headless) 的情况下运行了 `claude`，这会启动一个[交互式会话](/docs/zh-CN/interactive-mode)，但其标准输入不是终端。可能是某些东西通过管道传输或重定向了它，或者启动 `claude` 的程序提供了自己的输入流。
3441
3442交互式会话需要一个终端来读取您的按键，而在没有终端时 Claude Code 的行为取决于您的平台：
3443
3444* **Windows**：Claude Code 将消息打印到 stderr，并以退出码 1 退出，而不是启动界面
3445* **macOS 和 Linux**：Claude Code 从 `/dev/tty` 读取您的按键并启动会话，任何通过管道传入的文本都会作为您的第一个提示词。当 `/dev/tty` 无法打开时，您会看到此消息，其第一行会提到 `/dev/tty`，而不是 Windows 的措辞。
3446
3447在 Windows 上，消息如下：
3448
3449```text theme={null}
3450Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet.
3451Run claude directly in Windows Terminal, PowerShell, or Command Prompt, without piping or redirecting its input.
3452To send text as a prompt and print the reply instead, add -p; it also works with --continue and --resume <session-id> (for example: type notes.md | claude -p --continue).
3453```
3454
3455**解决方法：**
3456
3457* 若要以交互方式工作，请直接在终端中运行 `claude`，不要通过管道传输或重定向其输入
3458* 若要在不使用交互式界面的情况下获取回复（例如从脚本中），请添加 `-p`，并以参数或 stdin 的方式提供提示词，例如 `claude -p "your question"` 或 `echo "your question" | claude -p`。这同样适用于 `--continue` 和 `--resume <session-id>`。
3459
3460在 v2.1.287 之前，Claude Code 会启动界面而不是打印此消息，然后要么屏幕上什么都不显示，要么以包含 `Raw mode is not supported` 的错误失败。
3461
3462如果您是在 `claude install` 期间看到 `Raw mode is not supported`，请参阅[安装期间出现 `Raw mode is not supported`](/docs/zh-CN/troubleshoot-install#raw-mode-is-not-supported-during-install)。
3338 3463
3339<h3 id="input-contained-only-whitespace">3464<h3 id="input-contained-only-whitespace">
3340 输入仅包含空格3465 输入仅包含空白字符
3341</h3>3466</h3>
3342 3467
3343在[非交互模式](/docs/zh-CN/headless)中，Claude Code 拒绝完全由空格、制表符或换行符组成的提示，而不是发送它，因为 API 拒绝没有可见文本的消息。您看到的消息取决于空白提示来自何处：3468在[非交互模式](/docs/zh-CN/headless)下，Claude Code 会拒绝完全由空格、制表符或换行符组成的提示词，而不是发送它，因为 API 会拒绝没有可见文本的消息。您看到哪条消息取决于空白提示词的来源：
3344 3469
3345* **`claude -p` 的提示参数或管道 stdin**：`claude` 以 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print` 退出3470* **`claude -p` 的提示词参数或通过管道传入的 stdin**：`claude` 以 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print` 退出
3346* **提交给运行 `--input-format stream-json` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话的消息**：Claude Code 在不调用模型的情况下结束轮次，会话保持可用。拒绝作为信息消息和轮次的结果文本到达：`Blank prompt — the message was only whitespace, so nothing was sent to the model.`3471* **提交到正在运行的 `--input-format stream-json` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话的消息**：Claude Code 会在不调用模型的情况下结束该轮次，会话仍可继续使用。拒绝信息会以一条提示性消息以及该轮次的结果文本的形式送达：`Blank prompt — the message was only whitespace, so nothing was sent to the model.`
3347 3472
3348在 v2.1.229 之前，Claude Code 将仅空格消息发送到 API，API 以 400 错误拒绝请求。3473在 v2.1.229 之前，Claude Code 会将仅含空白字符的消息发送给 API，API 会以 400 错误拒绝该请求。
3349 3474
3350**应该做什么：**3475**解决方法：**
3351 3476
3352* 在提示中包含可见文本。如果脚本从变量或文件构建提示，请在调用 Claude Code 之前检查源是否不为空。3477* 在提示词中包含可见文本。如果脚本从变量或文件构建提示词，请在调用 Claude Code 之前检查来源是否为空。
3353 3478
3354<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">3479<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">
3355 stream-json 输入在没有换行符的情况下超过 256M 个字符3480 stream-json 输入包含超过 256M 个字符且没有换行符
3356</h3>3481</h3>
3357 3482
3358您的程序在没有换行符的情况下在 stdin 上发送了超过 268,435,456 个字符到 `claude -p --input-format stream-json` 运行，所以 Claude Code 将此错误打印到 stderr 并以代码 1 退出，而不是缓冲更多输入。消息将该预算表示为 `256M`。在 v2.1.257 之前，Claude Code 无限制地缓冲此类输入，增长内存直到进程崩溃或被杀死。3483您的程序在没有换行符的情况下，向 `claude -p --input-format stream-json` 运行的 stdin 发送了超过 268,435,456 个字符，因此 Claude Code 将此错误打印到 stderr 并以退出码 1 退出，而不是继续缓冲更多输入。消息将该上限表述为 `256M`。在 v2.1.257 之前，Claude Code 会无限制地缓冲此类输入，使内存不断增长，直到进程崩溃或被终止。
3359 3484
3360```text theme={null}3485```text theme={null}
3361Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.3486Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.
3362```3487```
3363 3488
3364没有换行符的这么长的输入通常意味着生产者根本不是 stream-json 生产者，例如二进制文件或意外管道的纯日志输出。超过预算的单个消息失败相同的检查。3489如此长且没有换行符的输入，通常意味着生产方根本不是 stream-json 生产方，例如误通过管道传入的二进制文件或纯日志输出。单条消息超过上限也会导致同样的检查失败。
3365 3490
3366**应该做什么：**3491**解决方法：**
3367 3492
3368* 检查什么被管道到 stdin。使用 [`--input-format stream-json`](/docs/zh-CN/cli-reference#cli-flags)，每条消息必须是一个换行符终止的 JSON 行3493* 检查通过管道传入 stdin 的内容。使用 [`--input-format stream-json`](/docs/zh-CN/cli-reference#cli-flags) 时，每条消息都必须是以换行符结尾的单行 JSON
3369* 要改为发送纯文本，请删除 `--input-format stream-json`；`claude -p` 默认从 stdin 读取纯文本提示3494* 若要改为发送纯文本，请去掉 `--input-format stream-json`；`claude -p` 默认从 stdin 读取纯文本提示词
3370 3495
3371<h3 id="unknown-command">3496<h3 id="unknown-command">
3372 未知命令3497 Unknown command
3373</h3>3498</h3>
3374 3499
3375在交互终端会话中，您提交了一个 `/` 名称，它与此会话中的任何命令都不匹配，所以 Claude Code 报告该名称而不是运行任何内容：3500在交互式终端会话中，您提交的 `/` 名称与此会话中的任何命令都不匹配，因此 Claude Code 会报告该名称，而不运行任何内容：
3376 3501
3377```text theme={null}3502```text theme={null}
3378Unknown command: /hepl. Did you mean /help?3503Unknown command: /hepl. Did you mean /help?
3379```3504```
3380 3505
3381Claude Code 建议此会话中菜单列出的最接近的命令名称或别名。当没有接近的时候，消息在名称后结束。原因通常是以下之一：3506Claude Code 会建议菜单在此会话中列出的最接近的命令名称或别名。如果没有接近的名称，消息会在该名称之后结束。原因通常是以下之一：
3382 3507
3383* 打字错误，例如 `/hepl` 代替 `/help`。[How the command menu matches what you type](/docs/zh-CN/commands#how-the-command-menu-matches-what-you-type) 涵盖在提交前选择接近的匹配3508* 拼写错误，例如将 `/help` 输成 `/hepl`。[命令菜单如何匹配您输入的内容](/docs/zh-CN/commands#how-the-command-menu-matches-what-you-type)介绍了如何在提交前选择一个接近的匹配项
3384* 存在但在此会话中不可用的命令，因为不满足要求，例如您的平台、计划或身份验证方法。[`/web-setup`](/docs/zh-CN/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 和 [`/schedule`](/docs/zh-CN/routines#schedule-returns-unknown-command) 的故障排除条目演示两个常见情况。某些命令在您的组织的策略禁用它们时用自己的消息回答，例如 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)3509* 命令存在，但由于未满足某项要求（例如您的平台、套餐或身份验证方式）而在此会话中不可用。[`/web-setup`](/docs/zh-CN/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 和 [`/schedule`](/docs/zh-CN/routines#schedule-returns-unknown-command) 的故障排除条目介绍了两种常见情况。某些命令在被您组织的策略禁用时会以自己的消息回复，例如 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)
3385* 来自[插件](/docs/zh-CN/plugins/overview)或[MCP 服务器](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)的命令，在此会话中未安装或连接3510* 来自[插件](/docs/zh-CN/plugins/overview)或 [MCP 服务器](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)的命令，而该插件或服务器在此会话中未安装或未连接
3386 3511
3387Claude Code 仅在交互终端会话中以这种方式回答不匹配的 `/` 名称。在所有其他会话中，它将提示作为正常消息发送给 Claude，并注意命令未运行以及 Claude 可以在会话中运行的命令列表。这些会话包括：3512只有在交互式终端会话中，Claude Code 才会以这种方式回复未匹配的 `/` 名称。在其他所有会话中，它会将该提示词作为普通消息发送给 Claude，并附上一条说明，指出该命令未运行，以及 Claude 在此会话中可以运行的命令列表。这些会话包括：
3388 3513
3389* `-p` 运行3514* `-p` 运行
3390* [Agent SDK](/docs/zh-CN/agent-sdk/overview) 应用程序3515* [Agent SDK](/docs/zh-CN/agent-sdk/overview) 应用程序
3391* [Desktop 应用](/docs/zh-CN/desktop)的代码选项卡3516* [桌面应用](/docs/zh-CN/desktop)的 Code 标签页
3392* [VS Code 扩展](/docs/zh-CN/vs-code)的聊天面板3517* [VS Code 扩展](/docs/zh-CN/vs-code)的聊天面板
3393* [云会话](/docs/zh-CN/claude-code-on-the-web)和[例程](/docs/zh-CN/routines)3518* [云端会话](/docs/zh-CN/claude-code-on-the-web)和 [Routine](/docs/zh-CN/routines)
3394 3519
3395对于无法在这些会话之一中运行的内置命令，Claude Code 仍然回答命令不可用，而不是将其发送给 Claude。在 v2.1.274 之前，仅云会话和例程将不匹配的名称发送给 Claude。在 v2.1.273 之前，它们也回答 `Unknown command`。3520对于无法在上述会话之一中运行的内置命令，Claude Code 仍会回复该命令不可用，而不是将其发送给 Claude。在 v2.1.274 之前，只有云端会话和 Routine 会将未匹配的名称发送给 Claude。在 v2.1.273 之前，它们也会回复 `Unknown command`。
3396 3521
3397Claude Code 不将每个以 `/` 开头的提示视为命令。当 `/` 后的第一个单词以标点符号开头时，它将提示作为正常消息发送给 Claude，例如打开 Lean doc 注释的 `/--`，或是路径，例如 `/var/log/syslog`。3522Claude Code 不会将每个以 `/` 开头的提示词都视为命令。当 `/` 之后的第一个词以标点开头（例如开启 Lean 文档注释的 `/--`），或者是一个路径（例如 `/var/log/syslog`）时，它会将该提示词作为普通消息发送给 Claude。
3398 3523
3399在 v2.1.236 之前，如果您在命令菜单列出您键入的名称的接近匹配时按 `Enter`，Claude Code 会运行该匹配，所以 `/hepl` 之类的打字错误会运行 `/help` 而不是产生此消息。3524在 v2.1.236 之前，如果在命令菜单列出与您输入的名称相近的匹配项时按下 `Enter`，Claude Code 会运行该匹配项，因此像 `/hepl` 这样的拼写错误会运行 `/help`，而不是产生此消息。
3400 3525
3401**应该做什么：**3526**解决方法：**
3402 3527
3403* 运行建议的名称，或键入 `/` 后跟名称的一部分以查看此会话中可用的内容3528* 运行建议的名称，或输入 `/` 后跟名称的一部分，以查看此会话中可用的命令
3404* 如果 Claude Code 将记录的命令报告为未知，请检查[命令参考](/docs/zh-CN/commands)中的其行以了解它命名的要求3529* 如果 Claude Code 将文档中记载的命令报告为未知，请在[命令参考](/docs/zh-CN/commands)中查看其所在行列出的要求
3405 3530
3406<h3 id="diff-is-too-large-for-ultrareview">3531<h3 id="diff-is-too-large-for-ultrareview">
3407 Diff 对于 ultrareview 来说太大了3532 diff 过大，无法进行 ultrareview
3408</h3>3533</h3>
3409 3534
3410您的分支和基础分支之间的差异，包括未提交和暂存的更改，超过了 [ultrareview](/docs/zh-CN/ultrareview) 的大小限制，所以 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。被拒绝的审查不使用免费运行，也不计费使用信用。消息命名有效的限制、您的差异大小以及贡献最多更改行的文件。在 v2.1.216 之前，消息仅显示原始差异统计。3535您的分支与基础分支之间的 diff（包括未提交和已暂存的更改）超出了 [ultrareview](/docs/zh-CN/ultrareview) 的大小限制，因此 `/code-review ultra` 和 `claude ultrareview` 子命令会在云端会话启动前拒绝审查。被拒绝的审查不会消耗免费次数，也不会计费使用额度。消息会指出生效的限制、您的 diff 大小，以及贡献最多更改行数的文件。在 v2.1.216 之前，消息只显示原始的 diff 统计信息。
3411 3536
3412```text theme={null}3537```text theme={null}
3413Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.3538Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.
3414```3539```
3415 3540
3416审查拉取请求应用相同的限制；该形式的消息以 `PR #<N> is too large for ultrareview` 开头，并命名 PR 的文件和行数。3541审查 Pull Request 时适用相同的限制；该形式的消息以 `PR #<N> is too large for ultrareview` 开头，并指出该 PR 的文件数和行数。
3417 3542
3418**应该做什么：**3543**解决方法：**
3419 3544
3420* 传递更接近您的工作的基础分支，例如 `/code-review ultra develop`，以便审查仅涵盖与该分支的差异3545* 传入一个更接近您工作的基础分支，例如 `/code-review ultra develop`，使审查仅覆盖相对于该分支的 diff
3421* 将更改分成较小的分支并审查每一个。消息命名的文件贡献最多更改行，所以首先将这些移到它们自己的分支。3546* 将更改拆分为更小的分支并分别审查。消息中指出的文件贡献了最多的更改行数，因此可以先将它们移到单独的分支中。
3422 3547
3423<h3 id="could-not-find-merge-base-with-the-base-branch">3548<h3 id="could-not-find-merge-base-with-the-base-branch">
3424 无法找到与基础分支的合并基础3549 无法找到与基础分支的 merge-base
3425</h3>3550</h3>
3426 3551
3427`/code-review ultra` 和 `claude ultrareview` 子命令审查您的分支和基础分支之间的差异，这需要两者共享的提交。当 `git merge-base` 找不到时，Claude Code 在云会话启动前拒绝审查。在 Claude Code 可以验证完整的克隆上，至少有一个分支，它改为回退到[审查每个跟踪文件](/docs/zh-CN/ultrareview#diff-limits-and-fallbacks)而不是拒绝。您在基础分支根本找不到时、Claude Code 无法验证您的克隆完整时，或在罕见的存储库中看到此拒绝，其中整个树差异不可能，例如 SHA-256 对象格式。3552`/code-review ultra` 和 `claude ultrareview` 子命令审查的是您的分支与基础分支之间的 diff，这需要两者共享一个提交。当 `git merge-base` 找不到共享提交时，Claude Code 会在云端会话启动前拒绝审查。在 Claude Code 能够验证是完整的、且至少有一个分支的克隆上，它会回退到[审查每个被跟踪的文件](/docs/zh-CN/ultrareview#diff-limits-and-fallbacks)，而不是拒绝。当根本找不到基础分支、Claude Code 无法验证您的克隆是否完整，或者在无法进行整棵树 diff 的少数仓库中（例如使用 SHA-256 对象格式的仓库），您会看到此拒绝信息。
3428 3553
3429```text theme={null}3554```text theme={null}
3430Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.3555Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.
3431```3556```
3432 3557
3433第一句后的提示取决于 Claude Code 观察到的内容：3558第一句之后的提示取决于 Claude Code 观察到的情况：
3434 3559
3435* **您没有传递基础分支**：Claude Code 与存储库的默认分支进行了比较，并建议显式传递您的基础，如上面的示例3560* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示
3436* **您传递的基础分支已在您的克隆中**：提示读取 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3561* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``
3437* **您传递的基础分支不在您的克隆中**：Claude Code 在比较前从 origin 获取了它。提示读取 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否浅时，它改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，提示为每个获取的基础分支建议 `git fetch --unshallow origin`，在完整克隆上该命令失败，显示 `fatal: --unshallow on a complete repository does not make sense`。3562* **您传入的基础分支不在您的克隆中**：Claude Code 在比较前已从 origin fetch 了该分支。提示为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个被 fetch 的基础分支，提示都会建议 `git fetch --unshallow origin`，而在完整克隆上，该命令会以 `fatal: --unshallow on a complete repository does not make sense` 失败。
3438 3563
3439**应该做什么：**3564**解决方法：**
3440 3565
3441* 如果另一个分支是您的真实基础，显式传递它：`/code-review ultra <branch>`3566* 如果您真正的基础分支是另一个分支，请显式传入：`/code-review ultra <branch>`
3442* 如果您的克隆可能没有完整历史，运行 `git fetch --unshallow origin` 并重新运行审查3567* 如果您的克隆可能没有完整历史，请运行 `git fetch --unshallow origin` 并重新运行审查
3443 3568
3444<h3 id="your-checkout-has-no-branches">3569<h3 id="your-checkout-has-no-branches">
3445 您的检出没有分支3570 您的检出没有任何分支
3446</h3>3571</h3>
3447 3572
3448检出可以有提交但没有分支：如果您运行 `git init` 后跟 `git fetch <url>` 和 `git checkout FETCH_HEAD`，您会得到一个分离的 HEAD，没有 refs。Claude Code 将您的存储库打包为 git 包以上传它进行 [ultrareview](/docs/zh-CN/ultrareview)，它无法打包没有分支或其他 refs 的存储库，所以 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。3573检出可能有提交却没有分支：如果您运行 `git init`，然后运行 `git fetch <url>` 和 `git checkout FETCH_HEAD`，就会得到一个没有任何引用的分离 HEAD。Claude Code 会将您的仓库打包为 git bundle 以上传用于 [ultrareview](/docs/zh-CN/ultrareview)，而它无法打包没有分支或其他引用的仓库，因此 `/code-review ultra` 和 `claude ultrareview` 子命令会在云端会话启动前拒绝审查。
3449 3574
3450```text theme={null}3575```text theme={null}
3451Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.3576Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.
3452```3577```
3453 3578
3454在 v2.1.221 之前，Claude Code 尝试审查此检出中的每个跟踪文件，上传失败。3579在 v2.1.221 之前，Claude Code 会尝试审查此检出中的每个被跟踪的文件，然后上传失败。
3455 3580
3456**应该做什么：**3581**解决方法：**
3457 3582
3458* 使用 `git checkout -b <name>` 在您当前的提交处创建分支，然后重新运行审查3583* 使用 `git checkout -b <name>` 在当前提交处创建一个分支，然后重新运行审查
3459 3584
3460<h3 id="no-github-account-is-connected-to-your-claude-account">3585<h3 id="no-github-account-is-connected-to-your-claude-account">
3461 没有 GitHub 帐户连接到您的 Claude 帐户3586 您的 Claude 账户未连接 GitHub 账户
3462</h3>3587</h3>
3463 3588
3464您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，在创建云会话前 Claude Code 询问服务器[连接到您的 Claude 帐户的 GitHub 帐户](/docs/zh-CN/ultrareview#review-a-pull-request)是否可以到达 PR 的存储库。没有帐户连接，或连接已过期，所以云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。3589您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，在创建云端会话之前，Claude Code 会询问服务器[连接到您 Claude 账户的 GitHub 账户](/docs/zh-CN/ultrareview#review-a-pull-request)是否能访问该 PR 的仓库。由于没有连接账户，或连接已过期，云端克隆将会失败，因此 Claude Code 拒绝启动。对于被拒绝的启动，Claude Code 不会消耗免费次数，也不会计费使用额度。
3465 3590
3466```text theme={null}3591```text theme={null}
3467Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).3592Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).
3468```3593```
3469 3594
3470当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息仅命名 claude.ai 链接。3595当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息只会给出 claude.ai 链接。
3471 3596
3472**应该做什么：**3597**解决方法：**
3473 3598
3474* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接帐户3599* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 账户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接一个账户
3475* 连接后一分钟重新运行审查3600* 连接后等待一分钟再重新运行审查
3476 3601
3477在 v2.1.248 之前，Claude Code 在启动前不检查这个。3602在 v2.1.248 之前，Claude Code 不会在启动前进行此检查。
3478 3603
3479<h3 id="your-connected-github-account-cant-see-the-repository">3604<h3 id="your-connected-github-account-cant-see-the-repository">
3480 您连接的 GitHub 帐户看不到存储库3605 您连接的 GitHub 账户无法访问该仓库
3481</h3>3606</h3>
3482 3607
3483您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，[连接到您的 Claude 帐户的 GitHub 帐户](/docs/zh-CN/ultrareview#review-a-pull-request)无法读取 PR 的存储库，所以云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。3608您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，而[连接到您 Claude 账户的 GitHub 账户](/docs/zh-CN/ultrareview#review-a-pull-request)无法读取该 PR 的仓库，因此云端克隆将会失败，Claude Code 拒绝启动。对于被拒绝的启动，Claude Code 不会消耗免费次数，也不会计费使用额度。
3484 3609
3485```text theme={null}3610```text theme={null}
3486Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.3611Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.
3487```3612```
3488 3613
3489当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息仅命名应用安装。3614当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息只会给出应用安装方式。
3490 3615
3491**应该做什么：**3616**解决方法：**
3492 3617
3493* 如果您的本地 `gh` CLI 可以读取存储库，运行 `/web-setup` 将该登录连接到您的 Claude 帐户3618* 如果您本地的 `gh` CLI 可以读取该仓库，请运行 `/web-setup` 将该登录连接到您的 Claude 账户
3494* 更改后重新运行审查3619* 更改后重新运行审查
3495 3620
3496在 v2.1.248 之前，Claude Code 在启动前不检查这个。3621在 v2.1.248 之前，Claude Code 不会在启动前进行此检查。
3497 3622
3498<h3 id="the-github-app-preflight-failed-transiently">3623<h3 id="the-github-app-preflight-failed-transiently">
3499 GitHub App 预检暂时失败3624 GitHub App 预检暂时失败
3500</h3>3625</h3>
3501 3626
3502您从本地存储库启动了[云会话](/docs/zh-CN/claude-code-on-the-web)，两个步骤一起失败了。Claude Code 无法构建或上传您的存储库包。在上传之前，它检查了云服务是否可以从 GitHub 克隆存储库，而不是明确的答案，该检查以重试可能清除的错误结束，例如网络错误、超时或临时服务器错误。完整消息以停止包的内容开头，例如 `Could not upload repo bundle (<error>)`，并以预检句子结尾：3627您从本地仓库启动了一个[云端会话](/docs/zh-CN/claude-code-on-the-web)，而有两个步骤同时失败。Claude Code 无法构建或上传您仓库的 bundle。在上传之前，它检查了云服务能否从 GitHub 克隆该仓库，而该检查没有得到明确答复，而是以一个可通过重试消除的错误结束，例如网络错误、超时或临时服务器错误。完整消息以导致 bundle 失败的原因开头，例如 `Could not upload repo bundle (<error>)`，并以预检相关的句子结尾：
3503 3628
3504```text theme={null}3629```text theme={null}
3505Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead3630Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead
3506```3631```
3507 3632
3508**应该做什么：**3633**解决方法：**
3509 3634
3510* 片刻后重新运行命令。当 GitHub 检查通过时，Claude Code 可以从 GitHub 克隆启动会话，所以失败的上传不再阻止启动3635* 稍后重新运行该命令。当 GitHub 检查通过时，Claude Code 可以从 GitHub 克隆启动会话，因此失败的上传不再阻止启动
3511* 如果重试继续失败，消息的开头命名停止上传的内容。当该原因是您可以修复的内容时，修复它以便会话可以从您的本地存储库启动3636* 如果重试持续失败，消息开头会指出导致上传失败的原因。如果该原因是您可以修复的，请修复它，使会话可以改为从您的本地仓库启动
3512 3637
3513在 v2.1.251 之前，Claude Code 以 `Please set up GitHub on https://claude.ai/code` 结束消息，即使 GitHub 检查仅暂时失败，设置建议无法清除暂时失败。3638在 v2.1.251 之前，即使 GitHub 检查只是暂时失败，Claude Code 也会以 `Please set up GitHub on https://claude.ai/code` 结束消息，而设置建议无法消除暂时性故障。
3514 3639
3515<h3 id="the-repository-upload-cant-follow-a-git-setting">3640<h3 id="the-repository-upload-cant-follow-a-git-setting">
3516 存储库上传无法遵循 git 设置3641 仓库上传无法遵循某个 git 设置
3517</h3>3642</h3>
3518 3643
3519您启动了[上传您的本地存储库的云会话](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)，或分支的 [ultrareview](/docs/zh-CN/ultrareview)，上传无法遵循决定哪个属性规则适用于您的文件的 git 设置之一。如果上传继续并错过了规则，git 在存储它之前转换的文件，例如清理过滤器加密的文件，可能会到达云端，因为它在磁盘上。Claude Code 拒绝上传，什么都不上传：3644您启动了一个[上传本地仓库的云端会话](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)，或对某个分支进行 [ultrareview](/docs/zh-CN/ultrareview)，而上传无法遵循用于决定哪些属性规则适用于您文件的某个 git 设置。如果上传继续进行并遗漏了某条规则，那么 git 在存储前会转换的文件（例如由 clean 过滤器加密的文件）可能会以其在磁盘上的原样上传到云端。因此 Claude Code 会拒绝上传，不会上传任何内容：
3520 3645
3521```text theme={null}3646```text theme={null}
3522Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository's .git/config or directly into your ~/.gitconfig, then retry.3647Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.
3523```3648```
3524 3649
3525消息命名设置和它的设置位置，并以该情况的修复结尾。相同的拒绝出现在 `core.attributesFile` 和 `attr.tree`，每个都有自己的修复。3650消息会指出该设置及其所在位置，并以适用于您所遇情况的解决方法结尾。对于 `core.attributesFile` 和 `attr.tree`，也会出现相同的拒绝信息，各自附带其对应的解决方法。
3526 3651
3527消息可以命名您的 git 配置通过 `include` 或 `includeIf` 指令拉入的配置文件，即使该指令的条件不适用于此存储库。3652消息中指出的可能是您的 git 配置通过 `include` 或 `includeIf` 指令引入的配置文件，即使该指令的条件并不适用于此仓库。
3528 3653
3529**应该做什么：**3654**解决方法：**
3530 3655
3531* 应用消息最后一句中的修复3656* 按照消息最后一句中的解决方法操作
3532 3657
3533<h3 id="github-isnt-connected-to-your-claude-account">3658<h3 id="github-isnt-connected-to-your-claude-account">
3534 GitHub 未连接到您的 Claude 帐户3659 GitHub 未连接到您的 Claude 账户
3535</h3>3660</h3>
3536 3661
3537您从本地存储库启动了[云会话](/docs/zh-CN/claude-code-on-the-web)，例如使用 `/autofix-pr`。没有 GitHub 帐户连接到您的 Claude 帐户，或连接已过期，所以 Claude Code 拒绝启动：3662您从本地仓库启动了一个[云端会话](/docs/zh-CN/claude-code-on-the-web)，例如使用 `/autofix-pr`。您的 Claude 账户没有连接 GitHub 账户，或连接已过期，因此 Claude Code 拒绝启动：
3538 3663
3539```text theme={null}3664```text theme={null}
3540GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github3665GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github
3541```3666```
3542 3667
3543当您使用 [`/schedule`](/docs/zh-CN/routines) 创建例程时，相同的消息作为命名存储库的设置注释出现；注释不会阻止创建例程。3668当您使用 [`/schedule`](/docs/zh-CN/routines) 创建 Routine 时，同样的消息会以指出该仓库的设置说明形式出现；该说明不会阻止创建 Routine。
3544 3669
3545**应该做什么：**3670**解决方法：**
3671
3672* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 账户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接一个账户。有关两者的区别，请参阅 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)。
3673* 连接后等待一分钟再重新运行该命令
3674
3675在 v2.1.268 之前，Claude Code 会将此报告为 Claude GitHub App 检查的暂时性失败，并建议重试或安装该应用；但这两种做法都不会连接 GitHub 账户。
3546 3676
3547* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接帐户。请参阅[GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)了解两者的区别。3677<h3 id="a-github-organization-policy-is-blocking-claude">
3548* 连接后一分钟重新运行命令3678 GitHub 组织策略阻止了 Claude
3679</h3>
3680
3681您在 Claude Code 提示符下运行了一个会启动云端会话的命令，例如 [`/autofix-pr`](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests)。在创建会话之前，Claude Code 会检查 Claude 对 GitHub 上该仓库的访问权限，而 GitHub 拒绝了访问，因为您的 GitHub 组织有一项阻止 Claude 的策略。Claude Code 会就此停止，并显示一条指明该策略的消息。
3682
3683当阻止访问的是 IP 允许列表时，消息内容为：
3684
3685```text theme={null}
3686Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.
3687```
3549 3688
3550在 v2.1.268 之前，Claude Code 将此报告为 Claude GitHub App 检查的临时失败，并建议重试或安装应用；两者都不连接 GitHub 帐户。3689当阻止访问的是单点登录时，消息内容为：
3690
3691```text theme={null}
3692Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.
3693```
3694
3695当阻止访问的是 Microsoft Entra ID 条件访问策略时，消息内容为：
3696
3697```text theme={null}
3698Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.
3699```
3700
3701**解决方法：**
3702
3703* **IP 允许列表**：请您的 GitHub 组织或企业的所有者放行 Anthropic 的出站 IP 地址。有关这些地址以及需要更改的 GitHub 设置，请参阅 [GitHub 允许列表和防火墙](/docs/zh-CN/network-config#github-allow-lists-and-firewalls)。
3704* **单点登录**：在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 断开 GitHub 连接，然后重新连接。当 GitHub 询问时，点击您的组织旁边的 **Authorize**，使新连接获得该组织单点登录的授权。
3705* **条件访问策略**：请您的 GitHub Enterprise 或 Microsoft Entra ID 管理员在该策略中放行 Claude
3706* 完成更改后，再次运行该命令
3551 3707
3552<h3 id="single-sign-on-authorization-needed">3708<h3 id="single-sign-on-authorization-needed">
3553 需要单点登录授权3709 需要单点登录授权
3554</h3>3710</h3>
3555 3711
3556您运行了 [`/install-github-app`](/docs/zh-CN/github-actions#quick-setup)，并选择了其组织强制执行 SAML 单点登录的存储库。在设置之前，Claude Code 使用 GitHub CLI 检查您对存储库的访问权限，GitHub 拒绝了该检查，因为您的 `gh` 令牌还没有为组织授权。向导显示警告和授权步骤：3712您运行了 [`/install-github-app`](/docs/zh-CN/github-actions#quick-setup)，并选择了一个所属组织强制执行 SAML 单点登录的仓库。在设置之前，Claude Code 会使用 GitHub CLI 检查您对该仓库的访问权限，而 GitHub 拒绝了该检查，因为您的 `gh` 令牌尚未获得该组织的授权。向导会显示警告以及授权步骤：
3557 3713
3558```text theme={null}3714```text theme={null}
3559Single sign-on authorization needed3715Single sign-on authorization needed
3560<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.3716<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.
3561```3717```
3562 3718
3563**应该做什么：**3719**解决方法：**
3564 3720
3565* 通过运行 `gh auth refresh -h github.com -s repo,workflow` 使用 `repo` 和 `workflow` 范围重新授权您的 GitHub CLI 登录，并在 GitHub 提示单点登录时授权组织3721* 运行 `gh auth refresh -h github.com -s repo,workflow`，以 `repo` 和 `workflow` 作用域重新授权您的 GitHub CLI 登录，并在 GitHub 提示单点登录时授权该组织
3566* 如果您使用 `GH_TOKEN` 中的个人访问令牌进行身份验证，请打开 [github.com/settings/tokens](https://github.com/settings/tokens)，在令牌上选择**配置 SSO**，并授权组织3722* 如果您使用 `GH_TOKEN` 中的个人访问令牌进行身份验证，请打开 [github.com/settings/tokens](https://github.com/settings/tokens)，在该令牌上选择 **Configure SSO**，然后授权该组织
3567* 再次运行 `/install-github-app`3723* 再次运行 `/install-github-app`
3568 3724
3569在 v2.1.273 之前，Claude Code 为此条件显示 `Admin permissions required` 警告。3725在 v2.1.273 之前，Claude Code 在这种情况下显示的是 `Admin permissions required` 警告。
3570 3726
3571<h3 id="failed-to-resume-the-conversation">3727<h3 id="failed-to-resume-the-conversation">
3572 无法恢复对话3728 无法恢复对话
3573</h3>3729</h3>
3574 3730
3575Claude Code 无法读取或处理您从 [`claude --resume` 选择器](/docs/zh-CN/sessions#use-the-session-picker)选择的会话的保存成绩单，所以它结束进程而不是在部分加载状态下继续。消息包括重试的命令：3731Claude Code 无法读取或处理您从 [`claude --resume` 选择器](/docs/zh-CN/sessions#use-the-session-picker)中选择的会话的已保存会话记录，因此它会结束进程，而不是在部分加载的状态下继续运行。消息中包含用于重试的命令：
3576 3732
3577```text theme={null}3733```text theme={null}
3578Failed to resume the conversation.3734Failed to resume the conversation.
3579Run claude --resume <session-id> to retry, or claude to start a new session.3735Run claude --resume <session-id> to retry, or claude to start a new session.
3580```3736```
3581 3737
3582Claude Code 显示消息后以代码 1 退出。运行会话内的 `/resume` 选择器报告对话中的 `Failed to resume conversation`，您当前的会话保持运行。在 v2.1.216 之前，来自 `claude --resume` 选择器的失败恢复在 `Resuming conversation…` 微调器上无限期停留，而不是显示此消息。3738显示该消息后，Claude Code 以退出码 1 退出。而在运行中的会话内使用 `/resume` 选择器时，则会在对话中报告 `Failed to resume conversation`，您当前的会话会继续运行。在 v2.1.216 之前，从 `claude --resume` 选择器恢复失败时，会一直停留在 `Resuming conversation…` 加载动画上，而不是显示此消息。
3583 3739
3584**应该做什么：**3740**解决方法：**
3585 3741
3586* 使用消息中的会话 ID 运行 `claude --resume <session-id>` 重试3742* 使用消息中的会话 ID 运行 `claude --resume <session-id>` 进行重试
3587* 如果每次重试都以相同的方式失败，运行 `claude update` 并再次恢复。v2.1.275 之前的版本在保存的成绩单包含它们无法读取的条目时恢复失败。3743* 在 v2.1.285 之前的版本中，如果重试以同样的方式失败，请运行 `claude update` 后再次恢复。当已保存的会话记录包含这些版本无法读取的条目时，这些版本会恢复失败。
3588* 如果重试再次失败，运行 `claude` 启动新会话3744* 如果重试再次失败，请运行 `claude` 开始新会话
3589 3745
3590<h3 id="no-conversation-found-with-the-session-id">3746<h3 id="no-conversation-found-with-the-session-id">
3591 未找到具有会话 ID 的对话3747 未找到具有该会话 ID 的对话
3592</h3>3748</h3>
3593 3749
3594您将会话 ID 传递给 `claude --resume <session-id>`，没有保存的成绩单与其匹配：3750您向 `claude --resume <session-id>` 传入了一个会话 ID，但没有匹配的已保存会话记录：
3595 3751
3596```text theme={null}3752```text theme={null}
3597No conversation found with session ID: <session-id>3753No conversation found with session ID: <session-id>
3598```3754```
3599 3755
3600Claude Code 显示消息后以代码 1 退出。Claude Code [首先搜索当前项目，然后搜索此机器上的所有其他项目](/docs/zh-CN/sessions#resume-a-session)以查找 ID。在 v2.1.223 之前，查找停止在当前项目目录及其 git worktrees，所以从会话最后工作的目录恢复。3756显示该消息后，Claude Code 以退出码 1 退出。Claude Code 会[先搜索当前项目，然后搜索这台机器上的所有其他项目](/docs/zh-CN/sessions#resume-a-session)来查找该 ID。在 v2.1.223 之前，查找仅限于当前项目目录及其 git worktree，因此需要从该会话最后工作的目录中进行恢复。
3601 3757
3602常见原因：3758常见原因：
3603 3759
3604* **打字错误的 ID**：对于非交互运行，ID 是 [`--output-format json` 输出](/docs/zh-CN/headless#get-structured-output)的 `session_id` 字段3760* **ID 输入错误**：对于非交互式运行，ID 是 [`--output-format json` 输出](/docs/zh-CN/headless#get-structured-output)中的 `session_id` 字段
3605* **删除的成绩单**：Claude Code 在[保留期](/docs/zh-CN/sessions#where-transcripts-are-stored)后删除成绩单，默认 30 天，遵循[保留扫描规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)3761* **会话记录已删除**：Claude Code 会在[保留期](/docs/zh-CN/sessions#where-transcripts-are-stored)（默认 30 天）结束后按照[保留清理规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)删除会话记录
3606* **不同的机器**：Claude Code 在本地存储成绩单，所以在运行它的机器上恢复会话3762* **不同的机器**：Claude Code 将会话记录存储在本地，因此请在运行该会话的机器上恢复它
3607* **重复副本**：如果您在 `~/.claude/projects` 下复制了项目目录，所以两个成绩单携带相同的 ID，Claude Code 报告此消息而不是任意恢复一个副本3763* **重复副本**：如果您在 `~/.claude/projects` 下复制了项目目录，导致两份会话记录带有相同的 ID，Claude Code 会报告此消息，而不是任意恢复其中一份
3608 3764
3609**应该做什么：**3765**解决方法：**
3610 3766
3611* 对于交互会话，使用 `claude --resume` 打开[会话选择器](/docs/zh-CN/sessions#use-the-session-picker)，按 `Ctrl+A` 将其扩展到此机器上的每个项目，然后选择会话3767* 对于交互式会话，使用 `claude --resume` 打开[会话选择器](/docs/zh-CN/sessions#use-the-session-picker)，按 `Ctrl+A` 将其范围扩大到这台机器上的所有项目，然后选择该会话
3612* 使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话不会出现在选择器中，所以重新检查 ID 与您的原始运行打印的 `session_id`3768* 使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话不会出现在选择器中，因此请对照您最初运行时输出的 `session_id` 重新检查 ID
3613 3769
3614<h3 id="windows-reported-an-error-ebadf">3770<h3 id="windows-reported-an-error-ebadf">
3615 Windows 在 Claude Code 读取此会话的成绩单文件时报告了错误 (EBADF)3771 Windows reported an error (EBADF) when Claude Code read this session's transcript file
3616</h3>3772</h3>
3617 3773
3618您在 Windows 上恢复了会话，其保存的[成绩单文件](/docs/zh-CN/sessions#where-transcripts-are-stored)正常打开，读取它然后失败，显示系统错误 EBADF。系统错误没有说读取失败的原因，所以消息建议可能的原因和要尝试的内容：3774您在 Windows 上恢复了一个会话，其已保存的[会话记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)正常打开，但随后读取时因系统错误 EBADF 而失败。该系统错误并未说明读取失败的原因，因此消息会提示可能的原因以及可以尝试的操作：
3619 3775
3620```text theme={null}3776```text theme={null}
3621Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.3777Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.
3622```3778```
3623 3779
3624消息遵循命令自己的失败行，例如 `Failed to resume session <session-id>`。`claude --resume` 或 [`claude -p`](/docs/zh-CN/headless) 命令显示它后以代码 1 退出。在会话内的 `/resume` 后，您当前的会话保持运行。3780该消息跟在命令自身的失败行之后，例如 `Failed to resume session <session-id>`。`claude --resume` 或 [`claude -p`](/docs/zh-CN/headless) 命令在显示该消息后以退出码 1 退出。在会话内使用 `/resume` 后，您当前的会话会继续运行。
3625 3781
3626**应该做什么：**3782**解决方法：**
3627 3783
3628* 从扫描或拦截文件读取的软件（例如安全、加密或端点管理工具）中排除保存会话成绩单的文件夹。成绩单默认位于 `%USERPROFILE%\.claude\projects` 下，或位于 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 命名的目录下3784* 在扫描或拦截文件读取的软件（例如安全、加密或终端管理工具）中排除存放会话记录的文件夹。会话记录默认位于 `%USERPROFILE%\.claude\projects` 下，或位于 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 指定的目录下
3629* 如果您无法添加排除，请改为将 Claude Code 添加到该软件的允许应用程序3785* 如果无法添加排除项，请改为将 Claude Code 添加到该软件的允许应用程序中
3630* 再次恢复会话3786* 再次恢复该会话
3631 3787
3632在 v2.1.282 之前，失败没有解释：`claude --resume <session-id>` 在 `Failed to resume session <session-id>` 处结束，`-p` 运行仅打印系统错误文本，例如 `Failed to resume session: EBADF: bad file descriptor, read`。3788在 v2.1.282 之前，失败时没有任何说明：`claude --resume <session-id>` 以 `Failed to resume session <session-id>` 结束，而 `-p` 运行只输出系统错误文本，例如 `Failed to resume session: EBADF: bad file descriptor, read`。
3633 3789
3634<h3 id="cannot-switch-renderers-in-this-session">3790<h3 id="cannot-switch-renderers-in-this-session">
3635 无法在此会话中切换渲染器3791 无法在此会话中切换渲染器
3636</h3>3792</h3>
3637 3793
3638当您切换渲染器时，Claude Code 重新启动其进程。您在 Claude Code 拒绝重新启动的会话中运行了 [`/tui`](/docs/zh-CN/fullscreen#enable-fullscreen-rendering)，所以它不切换并保存任何内容。您看到的消息告诉您原因：3794切换渲染器时，Claude Code 会重启其进程。您在一个 Claude Code 拒绝重启的会话中运行了 [`/tui`](/docs/zh-CN/fullscreen#enable-fullscreen-rendering)，因此它不会切换，也不会保存任何内容。您看到的消息会指明原因：
3639 3795
3640* `Cannot switch renderers while work is running in the background`：您有在后台运行的工作，重新启动会放弃，例如后台 shell 或子代理。等待工作完成或使用 [`/tasks`](/docs/zh-CN/commands) 停止它，然后再次运行 `/tui fullscreen` 或 `/tui default`3796* `Cannot switch renderers while work is running in the background`：您有正在后台运行的工作，重启会使其被放弃，例如后台 shell 或子代理。请等待工作完成或使用 [`/tasks`](/docs/zh-CN/commands) 停止它，然后再次运行 `/tui fullscreen` 或 `/tui default`
3641* `Cannot switch renderers in this session`：会话有 Claude Code 无法传递给重新启动的进程的限制。在 v2.1.234 之前，Claude Code 无论如何都会重新启动，重新启动的会话运行时没有它们3797* `Cannot switch renderers in this session`：该会话带有 Claude Code 无法传递给重启后进程的限制。在 v2.1.234 之前，Claude Code 仍会重启，而重新启动的会话将不带这些限制运行
3642 3798
3643在限制消息中，括号中的部分命名 Claude Code 找到的限制：3799在限制消息中，括号内的部分指明了 Claude Code 发现的限制：
3644 3800
3645```text theme={null}3801```text theme={null}
3646Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.3802Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.
3647```3803```
3648 3804
3649消息可以在括号中显示的每个原因：3805消息括号中可能显示的各项原因：
3650 3806
3651* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`：您使用 Claude Code 不传递回重新启动的进程的标志启动了会话。这些标志包括 [`--system-prompt`](/docs/zh-CN/cli-reference#cli-flags)、`--system-prompt-file`、`--append-system-prompt-file`、[`--tools`](/docs/zh-CN/cli-reference#cli-flags) 允许列表、[`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 和 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)3807* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`：您启动会话时使用了 Claude Code 不会传回给重启后进程的标志。这些标志包括 [`--system-prompt`](/docs/zh-CN/cli-reference#cli-flags)、`--system-prompt-file`、`--append-system-prompt-file`、[`--tools`](/docs/zh-CN/cli-reference#cli-flags) 允许列表、[`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 和 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)
3652* `permission rules set for this session only`：来自钩子或 SDK 调用者的[权限更新](/docs/zh-CN/hooks#permission-update-entries)添加了带有 `session` 目标的拒绝或询问规则。会话范围的允许规则不会触发拒绝。重新启动会删除它们，Claude Code 改为再次提示3808* `permission rules set for this session only`：来自 hook 或 SDK 调用方的[权限更新](/docs/zh-CN/hooks#permission-update-entries)添加了目标为 `session` 的拒绝或询问规则。会话作用域的允许规则不会触发拒绝。重启会丢弃这些规则，Claude Code 会改为再次提示
3653* `ask-before-running rules with no command-line form`：来自钩子或 SDK 调用者的权限更新添加了询问规则以及 Claude Code 作为 `--allowed-tools` 和 `--disallowed-tools` 传递回的规则。不存在询问规则的标志3809* `ask-before-running rules with no command-line form`：来自 hook 或 SDK 调用方的权限更新在 Claude Code 以 `--allowed-tools` 和 `--disallowed-tools` 传回的规则之外，还添加了询问规则。询问规则没有对应的标志
3654* `permission rules a command line cannot carry intact` 和 `added directories a command line cannot carry intact`：权限更新在会话中期添加了规则或目录路径。重新启动的进程的命令行无法将其文本作为相同的值继承3810* `permission rules a command line cannot carry intact` 和 `added directories a command line cannot carry intact`：权限更新在会话中途添加了规则或目录路径。重启后进程的命令行无法将其文本作为相同的值传递
3655 3811
3656**应该做什么：**3812**解决方法：**
3657 3813
3658* 在没有这些限制的会话中，运行 `/tui fullscreen`，或 `/tui default` 切换回。Claude Code 在那里保存 [`tui` 设置](/docs/zh-CN/settings-reference#tui)3814* 在不带这些限制启动的会话中运行 `/tui fullscreen`，或运行 `/tui default` 切换回来。Claude Code 会在那里保存 [`tui` 设置](/docs/zh-CN/settings-reference#tui)
3659 3815
3660<h3 id="couldnt-open-claude-desktop">3816<h3 id="couldnt-open-claude-desktop">
3661 无法打开 Claude Desktop3817 无法打开 Claude Desktop
3662</h3>3818</h3>
3663 3819
3664您在会话中运行了 [`/desktop`](/docs/zh-CN/desktop#coming-from-the-cli) 或其别名 `/app`，或在您的 shell 中运行了 [`claude --desktop`](/docs/zh-CN/cli-reference#cli-flags)，Claude Code 用来打开 Claude Desktop 的系统命令失败了。在 `/desktop` 后，会话保持在终端中；`claude --desktop` 打印消息而不带 `Error:` 前缀，并以状态 1 退出。3820您在会话中运行了 [`/desktop`](/docs/zh-CN/desktop#coming-from-the-cli) 或其别名 `/app`，或在 shell 中运行了 [`claude --desktop`](/docs/zh-CN/cli-reference#cli-flags)，而 Claude Code 用于打开 Claude Desktop 的系统命令失败了。运行 `/desktop` 后，会话会留在终端中；`claude --desktop` 会输出不带 `Error:` 前缀的消息，并以状态 1 退出。
3665 3821
3666括号中的文本命名失败的命令，带有其退出状态和其错误输出的第一行（如果它产生了）。在 macOS 上该命令是 `open`，如本例所示；在 Windows 上它是 `rundll32`：3822括号中的文本指明了失败的命令，如果该命令产生了退出状态和错误输出，还会附上其退出状态和错误输出的第一行。在 macOS 上该命令是 `open`，如下例所示；在 Windows 上是 `rundll32`：
3667 3823
3668```text theme={null}3824```text theme={null}
3669Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.3825Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.
3670```3826```
3671 3827
3672**应该做什么：**3828**解决方法：**
3673 3829
3674* 自己打开 Claude Desktop，然后再次运行 `/desktop` 或 `claude --desktop`3830* 手动打开 Claude Desktop，然后再次运行 `/desktop` 或 `claude --desktop`
3675* 要读取失败命令的完整错误输出，使用 `/debug` 打开调试日志并再次运行 `/desktop`，或运行 `claude --desktop --debug-file <path>`，然后检查调试日志3831* 要查看失败命令的完整错误输出，请使用 `/debug` 启用调试日志并再次运行 `/desktop`，或运行 `claude --desktop --debug-file <path>`，然后查看调试日志
3676 3832
3677在 v2.1.285 之前，消息以 `Open Claude Desktop and run /desktop again.` 结尾。在 v2.1.275 之前，它是 `Failed to open Claude Desktop. Please try opening it manually.`，没有说什么失败了。3833在 v2.1.285 之前，消息以 `Open Claude Desktop and run /desktop again.` 结尾。在 v2.1.275 之前，消息为 `Failed to open Claude Desktop. Please try opening it manually.`，且不会说明失败的内容。
3678 3834
3679<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3835<h3 id="terminal-setup-left-your-zed-keymap-unchanged">
3680 /terminal-setup 保持您的 Zed 快捷键不变3836 /terminal-setup 未更改您的 Zed 键位映射
3681</h3>3837</h3>
3682 3838
3683您在 Zed 中运行了 [`/terminal-setup`](/docs/zh-CN/terminal-config#enter-multiline-prompts)，Claude Code 无法完成对您的 Zed `keymap.json` 的更新，所以它保持文件不变。3839您在 Zed 中运行了 [`/terminal-setup`](/docs/zh-CN/terminal-config#enter-multiline-prompts)，而 Claude Code 无法完成对您的 Zed `keymap.json` 的更新，因此保持该文件原样不变。
3684 3840
3685每条消息命名您的快捷键的路径，并以您自己添加的快捷键块结尾：3841每条消息都会指明您的键位映射文件路径，并在末尾附上需要您自行添加的快捷键块：
3686 3842
3687```text theme={null}3843```text theme={null}
3688Couldn't update your Zed keymap, so it was left unchanged.3844Couldn't update your Zed keymap, so it was left unchanged.
3690{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }3846{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }
3691```3847```
3692 3848
3693消息的第一行命名原因：3849消息的第一行指明了原因：
3694 3850
3695* `Couldn't read your Zed keymap, so it was left unchanged.`：Claude Code 无法读取文件，例如由于文件权限3851* `Couldn't read your Zed keymap, so it was left unchanged.`：Claude Code 无法读取该文件，例如由于文件权限问题
3696* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`：文件读取正常但不解析为快捷键块数组，即使允许 `//` 注释和尾随逗号3852* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`：文件可以正常读取，但即使允许 `//` 注释和尾随逗号，也无法解析为快捷键块数组
3697* `Couldn't back up your Zed keymap; not modifying it.`：Claude Code 无法将文件复制到其旁边的 `.bak` 备份，所以它没有更改任何内容3853* `Couldn't back up your Zed keymap; not modifying it.`：Claude Code 无法将该文件复制为其旁边的 `.bak` 备份，因此未做任何更改
3698* `Couldn't update your Zed keymap, so it was left unchanged.`：合并的结果没有验证为携带绑定的有效快捷键，所以 Claude Code 丢弃它而不是写入。具有重复键的快捷键块可能导致这种情况3854* `Couldn't update your Zed keymap, so it was left unchanged.`：合并后的结果未能验证为包含该快捷键的有效键位映射，因此 Claude Code 将其丢弃而未写入。包含重复键的快捷键块可能导致这种情况
3699 3855
3700**应该做什么：**3856**解决方法：**
3701 3857
3702* 将消息中的块复制到消息命名的路径处 `keymap.json` 中的顶级数组3858* 将消息中的块复制到消息所指明路径下 `keymap.json` 的顶层数组中
3703* 对于 `isn't a readable list of keybindings`，修复语法错误，或使文件的顶级值成为数组，然后再次运行 `/terminal-setup`3859* 对于 `isn't a readable list of keybindings`，请修复语法错误，或将文件的顶层值改为数组，然后再次运行 `/terminal-setup`
3704 3860
3705在 v2.1.247 之前，`/terminal-setup` 无法解析使用 `//` 注释或尾随逗号的 Zed 快捷键，它用仅其自己的绑定替换整个文件，同时报告绑定已安装。要恢复较早版本替换的快捷键，请使用[输入多行提示](/docs/zh-CN/terminal-config#enter-multiline-prompts)下描述的 `.bak` 备份文件。3861在 v2.1.247 之前，`/terminal-setup` 无法解析使用了 `//` 注释或尾随逗号的 Zed 键位映射，它会用仅包含自身快捷键的内容替换整个文件，同时报告快捷键已安装。要恢复被早期版本替换的键位映射，请使用[输入多行提示词](/docs/zh-CN/terminal-config#enter-multiline-prompts)中所述的 `.bak` 备份文件。
3706 3862
3707<h3 id="skill-usage-reports-are-not-available-on-this-connection">3863<h3 id="skill-usage-reports-are-not-available-on-this-connection">
3708 Skill 使用报告在此连接上不可用3864 此连接不支持 skill 使用情况报告
3709</h3>3865</h3>
3710 3866
3711您在[远程控制](/docs/zh-CN/remote-control)上、从您的手机或浏览器运行了 [`/skill-doctor`](/docs/zh-CN/skills#find-unused-skills)。Claude Code 不通过远程控制发送 skill 使用报告，改为用此消息回复：3867您通过 [Remote Control](/docs/zh-CN/remote-control) 从手机或浏览器运行了 [`/skill-doctor`](/docs/zh-CN/skills#find-unused-skills)。Claude Code 不会通过 Remote Control 发送 skill 使用情况报告，而是回复以下消息：
3712 3868
3713```text theme={null}3869```text theme={null}
3714Skill usage reports are not available on this connection.3870Skill usage reports are not available on this connection.
3715```3871```
3716 3872
3717**应该做什么：**3873**解决方法：**
3718 3874
3719* 在会话运行的机器上的终端中运行 `/skill-doctor`，或在那里运行 `claude -p "/skill-doctor"`3875* 在运行该会话的机器的终端中运行 `/skill-doctor`，或在该机器上运行 `claude -p "/skill-doctor"`
3720 3876
3721<h3 id="custom-output-styles-cant-be-selected-over-remote-control">3877<h3 id="custom-output-styles-cant-be-selected-over-remote-control">
3722 无法通过远程控制选择自定义输出样式3878 无法通过 Remote Control 选择自定义输出样式
3723</h3>3879</h3>
3724 3880
3725您从移动应用或网络通过[远程控制](/docs/zh-CN/remote-control)运行了 [`/output-style`](/docs/zh-CN/output-styles#change-your-output-style)，或命令在中继到会话的消息中到达。因为此类轮次可能不来自帐户所有者，Claude Code 仅在其上列出并选择[内置样式](/docs/zh-CN/output-styles#built-in-output-styles)，并在命令列出样式或不识别您给出的名称时添加此通知。[自定义样式](/docs/zh-CN/output-styles#create-a-custom-output-style)名称获得与不存在的名称相同的回复：3881您通过 [Remote Control](/docs/zh-CN/remote-control) 从移动应用或网页运行了 [`/output-style`](/docs/zh-CN/output-styles#change-your-output-style)，或者该命令出现在转发到会话中的消息里。由于这样的轮次可能并非来自账户所有者，Claude Code 在其中只会列出和选择[内置样式](/docs/zh-CN/output-styles#built-in-output-styles)，并且每当该命令列出样式或无法识别您提供的名称时，都会附加此通知。[自定义样式](/docs/zh-CN/output-styles#create-a-custom-output-style)名称得到的回复与不存在的名称相同：
3726 3882
3727```text theme={null}3883```text theme={null}
3728Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.3884Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.
3729```3885```
3730 3886
3731**应该做什么：**3887**解决方法：**
3732 3888
3733* 选择内置样式，例如 `/output-style concise`3889* 选择一个内置样式，例如 `/output-style concise`
3734* 要使用自定义样式，在项目的 `.claude/settings.local.json` 中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle)，或在会话自己的终端中运行 `/output-style <style>`（如果它有的话）3890* 要使用自定义样式，请在项目的 `.claude/settings.local.json` 中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle)，或者如果会话有自己的终端，请在该终端中运行 `/output-style <style>`
3735 3891
3736<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">3892<h3 id="output-styles-are-saved-to-local-settings-which-this-session-doesnt-load">
3737 输出样式保存到此会话不加载的本地设置3893 输出样式保存在此会话不加载的本地设置中
3738</h3>3894</h3>
3739 3895
3740您尝试在其设置源排除 `local` 的会话中使用 `/output-style <style>` 或 `/config outputStyle=<style>` 切换[输出样式](/docs/zh-CN/output-styles)。示例是 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#options) 留出 `"local"` 的 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) 会话，以及使用 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 值启动的 CLI 会话，该值留出 `local`。两个命令都将样式保存到 `.claude/settings.local.json`，此类会话从不读取回的文件，所以 Claude Code 拒绝而不是写入无效的设置：3896您在一个设置来源不包含 `local` 的会话中尝试使用 `/output-style <style>` 或 `/config outputStyle=<style>` 切换[输出样式](/docs/zh-CN/output-styles)。例如，[`settingSources`](/docs/zh-CN/agent-sdk/typescript#options) 省略了 `"local"` 的 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) 会话，以及使用省略了 `local` 的 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 值启动的 CLI 会话。这两个命令都会将样式保存到 `.claude/settings.local.json`，而这类会话永远不会读回该文件，因此 Claude Code 会拒绝操作，而不是写入一个不会生效的设置：
3741 3897
3742```text theme={null}3898```text theme={null}
3743Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.3899Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.
3744```3900```
3745 3901
3746**应该做什么：**3902**解决方法：**
3747 3903
3748* 将 `local` 添加到会话的设置源并再次切换3904* 将 `local` 添加到会话的设置来源中，然后再次切换
3749* 在会话确实加载的设置文件中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle) 键，例如项目中的 `.claude/settings.json` 或 `~/.claude/settings.json`。在 TypeScript SDK 中，改为在内联 `settings` 对象内设置 `outputStyle`；请参阅[激活输出样式](/docs/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style)3905* 在会话确实会加载的设置文件中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle) 键，例如项目中的 `.claude/settings.json` 或 `~/.claude/settings.json`。在 TypeScript SDK 中，请改为在内联 `settings` 对象中设置 `outputStyle`；请参阅[激活输出样式](/docs/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style)
3906
3907<h3 id="recap-only-runs-when-you-ask-for-it-yourself">
3908 /recap 仅在您亲自请求时运行
3909</h3>
3910
3911该 [`/recap`](/docs/zh-CN/interactive-mode#session-recap) 请求并非来自您自己的输入。它出现在从 Slack、Teams 或[项目](/docs/zh-CN/claude-projects)线程转发到会话中的消息里，或出现在 [Routine](/docs/zh-CN/routines) 或其他程序发送的提示词中。
3912
3913即使转发的消息是您本人撰写的，也会收到此通知。Claude Code 无法判断转发或自动化的消息是否来自运行该会话的账户所有者，因此会以此通知代替摘要进行回复：
3914
3915```text theme={null}
3916/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.
3917```
3918
3919传给 `claude -p` 的 `/recap`，或您自己的 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 应用程序向其启动的会话发送的 `/recap`，都算作您自己的输入。
3920
3921**解决方法：**
3922
3923* 亲自打开该会话并在其中运行 `/recap`：在其终端中、在 [Desktop 应用](/docs/zh-CN/desktop)或[移动应用](/docs/zh-CN/mobile)中、在 [claude.ai/code](https://claude.ai/code) 上，或通过 [Remote Control](/docs/zh-CN/remote-control)
3924* 如果是 Routine 或其他程序发送的，请从该提示词中删除 `/recap`
3750 3925
3751<h2 id="plugin-errors">3926<h2 id="plugin-errors">
3752 插件错误3927 插件错误
4067 工具错误4242 工具错误
4068</h2>4243</h2>
4069 4244
4070这些错误来自 Claude 的内置工具。Claude 通常会自动纠正大多数工具错误。当需要你进行更改时，该错误的**应该做什么**列表会说明需要更改的内容。4245这些错误来自 Claude 的工具调用。Claude 通常会自动纠正大多数工具错误。当需要您进行更改时，该错误的**应该做什么**列表会说明需要更改的内容。
4246
4247<h3 id="no-such-tool-available">
4248 没有此类工具可用
4249</h3>
4250
4251Claude 按名称调用了一个不在会话工具列表中的工具。Claude Code 将该错误作为工具调用的结果返回给 Claude，轮次继续。当 Claude Code 能够判断工具缺失的原因时，它会在工具名称后添加一句话，说明原因或指出应改为调用的工具，如第二行所示：
4252
4253```text theme={null}
4254Error: No such tool available: <tool name>
4255Error: No such tool available: read. Tool names are case-sensitive: call Read instead.
4256```
4257
4258在您恢复会话后不久，当 Claude 调用某个 MCP 服务器的工具时，该服务器可能仍在进行首次连接尝试。此时 Claude Code 会[等待该服务器](/docs/zh-CN/mcp#tool-availability)，如果等待结束时该工具仍不可用，则返回此错误。在 v2.1.284 之前，此类调用会立即失败，而不会等待。
4259
4260工具名称被 Claude Code [截断为 200 个字符](#tool-use-name-over-200-characters)的调用也会以此错误失败。
4261
4262**应该做什么：**
4263
4264* 如果只出现一次，无需执行任何操作。Claude 会读取该错误，轮次继续。
4265* 如果对某个 MCP 服务器工具的调用持续以此错误失败，请在会话中运行 `/mcp` 或在 shell 中运行 `claude mcp list` 来检查该服务器的[状态](/docs/zh-CN/mcp#server-status)，并从 `/mcp` 重新连接失败的服务器。在 Agent SDK 中，请参阅[错误处理](/docs/zh-CN/agent-sdk/mcp#error-handling)。
4071 4266
4072<h3 id="agent-would-be-spawned-with-zero-tools">4267<h3 id="agent-would-be-spawned-with-zero-tools">
4073 Agent 将以零个工具生成4268 Agent 将以零个工具生成
4074</h3>4269</h3>
4075 4270
4076子代理的 [`tools` 列表](/docs/zh-CN/sub-agents#supported-frontmatter-fields)中的每个条目都无法匹配可用工具，因此 Claude Code 拒绝启动子代理：没有工具，它无法行动。该消息按出错原因对你的条目进行分组：4271子代理的 [`tools` 列表](/docs/zh-CN/sub-agents#supported-frontmatter-fields)中的每个条目都无法匹配可用工具，因此 Claude Code 拒绝启动子代理：没有工具，它无法行动。该消息按出错原因对您的条目进行分组：
4077 4272
4078* **无法识别**：该条目与任何工具名称都不匹配，通常是拼写错误，例如 `Grpe` 代替 `Grep`。4273* **无法识别**：该条目与任何工具名称都不匹配，通常是拼写错误，例如 `Grpe` 代替 `Grep`。
4079* **子代理不可用**：该条目命名了一个真实工具，但[子代理无法使用](/docs/zh-CN/sub-agents#available-tools)。后台子代理保持较小的内置工具集，因此当子代理在后台运行时（这是默认设置），只有前台子代理才能使用的条目会出现在这里。如果你列出 `Agent`，该消息会改为在下一组中报告它。4274* **子代理不可用**：该条目命名了一个真实工具，但[子代理无法使用](/docs/zh-CN/sub-agents#available-tools)。后台子代理保持较小的内置工具集，因此当子代理在后台运行时（这是默认设置），只有前台子代理才能使用的条目会出现在这里。如果您列出 `Agent`，该消息会改为在下一组中报告它。
4080* **在此会话中未匹配任何工具**：该条目有效，但当前会话中没有工具与其匹配，例如没有连接 GitHub MCP 服务器的 `mcp__github__*`，或子代理处于[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)的 `Agent`。4275* **在此会话中未匹配任何工具**：该条目有效，但当前会话中没有工具与其匹配，例如没有连接 GitHub MCP 服务器的 `mcp__github__*`，或子代理处于[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)的 `Agent`。
4081 4276
4082省略 `tools` 字段永远不会触发此拒绝。如果你将 `tools` 列表留空，或 `disallowedTools` 删除其中的每个条目，Claude Code 也会跳过拒绝并启动没有工具的子代理。4277省略 `tools` 字段永远不会触发此拒绝。如果您将 `tools` 列表留空，或 `disallowedTools` 删除其中的每个条目，Claude Code 也会跳过拒绝并启动没有工具的子代理。
4083 4278
4084在 v2.1.208 之前，子代理以零个工具启动，可能返回空结果或令人困惑的结果。4279在 v2.1.208 之前，子代理以零个工具启动，可能返回空结果或令人困惑的结果。
4085 4280
4093* 删除会话没有的工具条目，例如来自未连接的服务器的 MCP 工具4288* 删除会话没有的工具条目，例如来自未连接的服务器的 MCP 工具
4094* 对于[后台子代理删除](/docs/zh-CN/sub-agents#available-tools)的工具（例如 `CronCreate`），删除该条目。要保留该工具，[关闭 fork 模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)并要求 Claude 在前台运行子代理4289* 对于[后台子代理删除](/docs/zh-CN/sub-agents#available-tools)的工具（例如 `CronCreate`），删除该条目。要保留该工具，[关闭 fork 模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)并要求 Claude 在前台运行子代理
4095* 删除 `tools` 字段而不是列出工具，以给子代理每个[子代理可用的工具](/docs/zh-CN/sub-agents#available-tools)4290* 删除 `tools` 字段而不是列出工具，以给子代理每个[子代理可用的工具](/docs/zh-CN/sub-agents#available-tools)
4096* 对于仅包含 `Agent` 的 `tools` 列表，提高[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)或给代理至少一个其他工具：Claude Code 在该限制处保留 `Agent`，因此列表中没有其他内容会解析为零个工具4291* 对于仅包含 `Agent` 的 `tools` 列表，提高[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)或给该 Agent 至少一个其他工具：Claude Code 在该限制处保留 `Agent`，因此列表中没有其他内容会解析为零个工具
4097 4292
4098<h3 id="file-is-covered-by-a-read-deny-rule">4293<h3 id="file-is-covered-by-a-read-deny-rule">
4099 文件被 Read 拒绝规则覆盖4294 文件被 Read 拒绝规则覆盖
4126 4321
4127**应该做什么：**4322**应该做什么：**
4128 4323
4129* 你这边不需要做任何事：错误作为工具的结果返回给 Claude，消息本身告诉 Claude 删除空字节并重试4324* 您这边不需要做任何事：错误作为工具的结果返回给 Claude，消息本身告诉 Claude 删除空字节并重试
4130 4325
4131在 v2.1.281 之前，Read、Write、Edit 或 NotebookEdit 路径中的空字节会以命名 `Path contains null bytes` 的错误结束整个轮次，工具从不运行。4326在 v2.1.281 之前，Read、Write、Edit 或 NotebookEdit 路径中的空字节会以命名 `Path contains null bytes` 的错误结束整个轮次，工具从不运行。
4132 4327
4141Claude 调用了 [Agent 工具](/docs/zh-CN/tools-reference#agent-tool-behavior)而没有 `subagent_type`，此会话没有[通用子代理](/docs/zh-CN/sub-agents#built-in-subagents)可回退。这种情况出现在两种设置中：4336Claude 调用了 [Agent 工具](/docs/zh-CN/tools-reference#agent-tool-behavior)而没有 `subagent_type`，此会话没有[通用子代理](/docs/zh-CN/sub-agents#built-in-subagents)可回退。这种情况出现在两种设置中：
4142 4337
4143* [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/zh-CN/env-vars)在非交互模式下设置，这会删除每个内置子代理4338* [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/zh-CN/env-vars)在非交互模式下设置，这会删除每个内置子代理
4144* 会话的主线程代理有一个 [`tools: Agent(...)` 允许列表](/docs/zh-CN/sub-agents#restrict-which-subagents-can-be-spawned)，其中不包括 `general-purpose`4339* 会话的主线程 Agent 有一个 [`tools: Agent(...)` 允许列表](/docs/zh-CN/sub-agents#restrict-which-subagents-can-be-spawned)，其中不包括 `general-purpose`
4145 4340
4146**应该做什么：**4341**应该做什么：**
4147 4342
4151在 v2.1.235 之前，相同的调用失败并显示 `Agent type 'general-purpose' not found`。4346在 v2.1.235 之前，相同的调用失败并显示 `Agent type 'general-purpose' not found`。
4152 4347
4153<h3 id="memory-index-is-over-its-read-limit">4348<h3 id="memory-index-is-over-its-read-limit">
4154 内存索引超过其读取限制4349 记忆索引超过其读取限制
4155</h3>4350</h3>
4156 4351
4157Claude 写入了[自动内存](/docs/zh-CN/memory#auto-memory)索引 `MEMORY.md` 并将其留在其读取限制之一上：200 行或 25KB。写入成功，但仅加载前 200 行或 25KB（以先到者为准），因此每次读取索引时，超过限制的所有内容都会被丢弃。在 v2.1.210 之前，超限索引在下次加载时被静默截断，没有写入时信号。4352Claude 写入了[自动记忆](/docs/zh-CN/memory#auto-memory)索引 `MEMORY.md`，并使其超过了读取限制之一：200 行或 25KB。写入成功，但会话开始时仅加载前 200 行或 25KB（以先到者为准），因此每次读取索引时，超过限制的所有内容都会被丢弃。在 v2.1.210 之前，超限索引在下次加载时被静默截断，没有写入时信号。
4158 4353
4159```text theme={null}4354```text theme={null}
4160Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.4355Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.
4162 4357
4163仅加载的内容计入限制。YAML frontmatter 和块级 HTML 注释在加载索引前被删除，因此它们被排除在测量之外。在 v2.1.211 之前，Claude Code 测量原始文件，frontmatter 或注释即使在加载的内容符合时也可能触发此错误。4358仅加载的内容计入限制。YAML frontmatter 和块级 HTML 注释在加载索引前被删除，因此它们被排除在测量之外。在 v2.1.211 之前，Claude Code 测量原始文件，frontmatter 或注释即使在加载的内容符合时也可能触发此错误。
4164 4359
4165Claude Code 在写入后将错误传递给 Claude，而不是在你的终端中打印为横幅，因此你可能仅在记录中注意到它。4360Claude Code 在写入后将错误传递给 Claude，而不是在您的终端中打印为横幅，因此您可能仅在会话记录中注意到它。
4166 4361
4167当 Claude 的写入使文件接近限制但未超过时，Claude Code 返回更温和的提醒以压缩索引，而不是此错误。4362当 Claude 的写入使文件接近限制但未超过时，Claude Code 返回更温和的提醒以压缩索引，而不是此错误。
4168 4363
4169**应该做什么：**4364**应该做什么：**
4170 4365
4171* 让 Claude 重写 `MEMORY.md`，或要求它：每个条目保留一行，将详细信息移到主题文件中，并合并或删除过时条目4366* 让 Claude 重写 `MEMORY.md`，或要求它：每个条目保留一行，将详细信息移到主题文件中，并合并或删除过时条目
4172* 要自己修剪索引，请参阅[审计和编辑你的内存](/docs/zh-CN/memory#audit-and-edit-your-memory)4367* 要自己修剪索引，请参阅[审计和编辑您的记忆](/docs/zh-CN/memory#audit-and-edit-your-memory)
4173 4368
4174<h3 id="pkill-pattern-matches-the-claude-code-process">4369<h3 id="pkill-pattern-matches-the-claude-code-process">
4175 pkill 模式匹配 Claude Code 进程4370 pkill 模式匹配 Claude Code 进程
4176</h3>4371</h3>
4177 4372
4178Bash 工具调用中的 `pkill` 命令使用了一个模式（通常带有 `-f`），该模式与 Claude Code 进程本身匹配，因此 Claude Code 拒绝该命令而不是让它结束会话。Claude Code 在运行 `pkill` 之前使用 `pgrep` 测试该模式，并在其自己的进程 ID 在结果中时拒绝。该检查仅在 Linux 上运行；在 macOS 上，`pkill` 不经修改地运行。在 v2.1.214 之前，该命令运行，匹配的模式在中途杀死了 Claude Code 会话。4373Bash 工具调用中的 `pkill` 命令使用了一个模式（通常带有 `-f`），该模式与 Claude Code 进程本身匹配，因此 Claude Code 拒绝该命令而不是让它结束会话。Claude Code 在运行 `pkill` 之前使用 `pgrep` 测试该模式，并在其自己的进程 ID 在结果中时拒绝。该检查仅在 Linux 上运行；在 macOS 上，`pkill` 不经修改地运行。在 v2.1.214 之前，该命令运行，匹配的模式在轮次中途杀死了 Claude Code 会话。
4179 4374
4180```text theme={null}4375```text theme={null}
4181pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.4376pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.
4182```4377```
4183 4378
4184拒绝出现在 Bash 工具结果中，而不是作为你终端中的横幅，Claude 通常会自动调整该命令。4379拒绝出现在 Bash 工具结果中，而不是作为您终端中的横幅，Claude 通常会自动调整该命令。
4185 4380
4186**应该做什么：**4381**应该做什么：**
4187 4382
4192 无法写入队友的收件箱4387 无法写入队友的收件箱
4193</h3>4388</h3>
4194 4389
4195Claude Code 无法将消息写入 `~/.claude/teams/{team-name}/inboxes/` 下的队友邮箱文件，因此收件人没有收到任何内容。当 Claude Code 无法创建或更新文件时写入失败，例如因为磁盘已满、目录不可写或另一个代理长时间持有收件箱锁。在 v2.1.224 之前，Claude Code 即使在写入失败时也报告消息已发送。4390Claude Code 无法将消息写入 `~/.claude/teams/{team-name}/inboxes/` 下的队友邮箱文件，因此收件人没有收到任何内容。当 Claude Code 无法创建或更新文件时写入失败，例如因为磁盘已满、目录不可写或另一个 Agent 长时间持有收件箱锁。在 v2.1.224 之前，Claude Code 即使在写入失败时也报告消息已发送。
4196 4391
4197该错误出现在发送代理的工具结果中，而不是作为你终端中的横幅，其文本告诉 Claude 重试：4392该错误出现在发送方 Agent 的工具结果中，而不是作为您终端中的横幅，其文本告诉 Claude 重试：
4198 4393
4199```text theme={null}4394```text theme={null}
4200Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.4395Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.
4201```4396```
4202 4397
4203结构化[代理团队](/docs/zh-CN/agent-teams)协议消息以相同方式失败，错误命名未送达的消息：当 Claude Code 无法写入计划批准、计划拒绝、关闭请求或关闭拒绝时，错误读取 `Failed to write the <message> to <name>'s inbox — nothing was sent`。该列表中的 `plan approval` 是领导批准队友计划的决定；队友的计划提交是单独的 `plan approval request` 消息。该消息和另外两个协议消息携带自己的消息文本和后果：4398结构化 [agent team](/docs/zh-CN/agent-teams) 协议消息以相同方式失败，错误命名未送达的消息：当 Claude Code 无法写入计划批准、计划拒绝、关闭请求或关闭拒绝时，错误读取 `Failed to write the <message> to <name>'s inbox — nothing was sent`。该列表中的 `plan approval` 是领导批准队友计划的决定；队友的计划提交是单独的 `plan approval request` 消息。该消息和另外两个协议消息携带自己的消息文本和后果：
4204 4399
4205* `Failed to write the plan approval request to the lead's inbox — plan not submitted; try again`：队友的计划从未到达领导，队友保持计划模式直到重新提交成功4400* `Failed to write the plan approval request to the lead's inbox — plan not submitted; try again`：队友的计划从未到达领导，队友保持计划模式直到重新提交成功
4206* `The permission request could not be delivered to the team lead (mailbox write failed)`：队友的权限请求从未到达领导，因此没有人批准工具调用4401* `The permission request could not be delivered to the team lead (mailbox write failed)`：队友的权限请求从未到达领导，因此没有人批准工具调用
4207* `The confirmation could not be written to team-lead's inbox.`：关闭批准本身生效，队友退出；仅缺少对领导的确认4402* `The confirmation could not be written to team-lead's inbox.`：关闭批准本身生效，队友退出；仅缺少对领导的确认
4208 4403
4209当你自己给队友发消息时，在领导会话中输入 `@name` 后跟消息，相同的失败显示为通知 `Couldn't write to @name's inbox — message not sent. Try again.`，Claude Code 将你的文本保留在提示框中，以便你可以再次发送。4404当您自己给队友发消息时，在领导会话中输入 `@name` 后跟消息，相同的失败显示为通知 `Couldn't write to @name's inbox — message not sent. Try again.`，Claude Code 将您的文本保留在输入框中，以便您可以再次发送。
4210 4405
4211**应该做什么：**4406**应该做什么：**
4212 4407
4213* 要求发送者重新发送消息；收件箱锁的争用是暂时的，重试时会清除4408* 要求发送者重新发送消息；收件箱锁的争用是暂时的，重试时会清除
4214* 检查可用磁盘空间，并检查 `~/.claude/teams` 及其下的文件是否可由你的用户写入4409* 检查可用磁盘空间，并检查 `~/.claude/teams` 及其下的文件是否可由您的用户写入
4215 4410
4216<h3 id="teammate-agent-definition-not-restored">4411<h3 id="teammate-agent-definition-not-restored">
4217 队友的代理定义未被恢复4412 队友的 Agent 定义未被恢复
4218</h3>4413</h3>
4219 4414
4220Claude 给停止的[代理团队](/docs/zh-CN/agent-teams)队友发消息，Claude Code 将其恢复而没有重新应用它生成时的[子代理定义](/docs/zh-CN/agent-teams#use-subagent-definitions-for-teammates)，因为其定义文件来自没有保存信任的文件夹。该通知跟随发送代理的工具结果中的恢复报告：4415Claude 给停止的 [agent team](/docs/zh-CN/agent-teams) 队友发消息，Claude Code 将其恢复而没有重新应用它生成时的[子代理定义](/docs/zh-CN/agent-teams#use-subagent-definitions-for-teammates)，因为其定义文件来自没有保存信任的文件夹。该通知跟随发送方 Agent 的工具结果中的恢复报告：
4221 4416
4222```text wrap theme={null}4417```text wrap theme={null}
4223Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.4418Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.
4224```4419```
4225 4420
4226该检查适用于项目的 `.claude/agents/` 目录或 `--add-dir` 目录中的定义，接受父文件夹的信任对话不满足它。4421该检查适用于项目的 `.claude/agents/` 目录或 `--add-dir` 目录中的定义，接受父文件夹的信任对话框并不能满足它。
4227 4422
4228**应该做什么：**4423**应该做什么：**
4229 4424
4230* 在[调试日志](/docs/zh-CN/debug-your-config)命名的文件夹中运行 `claude` 并接受信任对话。下次 Claude Code 恢复队友时重新应用定义；你不需要重启领导会话4425* 在[调试日志](/docs/zh-CN/debug-your-config)命名的文件夹中运行 `claude` 并接受信任对话框。下次 Claude Code 恢复队友时重新应用定义；您不需要重启领导会话
4231* 或在 `~/.claude.json` 中将 `hasTrustDialogAccepted` 条目设置为 `true`，使用调试日志打印的确切 `projects["<path>"]` 键4426* 或在 `~/.claude.json` 中将 `hasTrustDialogAccepted` 条目设置为 `true`，使用调试日志打印的确切 `projects["<path>"]` 键
4232 4427
4233<h3 id="message-too-large-for-cross-session-delivery">4428<h3 id="message-too-large-for-cross-session-delivery">
4234 跨会话传递消息过大4429 跨会话传递消息过大
4235</h3>4430</h3>
4236 4431
4237Claude 的[跨会话消息](/docs/zh-CN/cross-session-messaging)到此机器上你的另一个会话太长而无法发送。Claude Code 拒绝了它，接收会话什么都没有收到。拒绝出现在发送会话的工具结果中，而不是作为你终端中的横幅。它命名两个大小以及如何使消息符合：4432Claude 发往此机器上您的另一个会话的[跨会话消息](/docs/zh-CN/cross-session-messaging)太长而无法发送。Claude Code 拒绝了它，接收会话什么都没有收到。拒绝出现在发送会话的工具结果中，而不是作为您终端中的横幅。它命名两个大小以及如何使消息符合：
4238 4433
4239```text wrap theme={null}4434```text wrap theme={null}
4240Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.4435Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.
4244 4439
4245**应该做什么：**4440**应该做什么：**
4246 4441
4247* 要求 Claude 总结消息，或将大量内容放在收件人可以读取的文件中而不是消息中4442* 要求 Claude 总结消息，或将大量内容放入文件并发送该文件的路径
4248* 要求 Claude 将内容分成几条较短的消息4443* 要求 Claude 将内容分成几条较短的消息
4249 4444
4250在 v2.1.235 之前，Claude Code 报告超大消息已发送。接收会话未读地丢弃了它。4445在 v2.1.235 之前，Claude Code 报告超大消息已发送。接收会话未读地丢弃了它。
4253 此会话刚刚收到太多消息4448 此会话刚刚收到太多消息
4254</h3>4449</h3>
4255 4450
4256Claude 向此机器上你的一个会话发送了快速的[跨会话消息](/docs/zh-CN/cross-session-messaging)突发，突发达到了该会话的收件箱接受的内容。Claude Code 拒绝了下一次发送，接收会话什么都没有收到。拒绝出现在发送会话的工具结果中，而不是作为你终端中的横幅：4451Claude 向此机器上您的一个会话快速连续发送了大量[跨会话消息](/docs/zh-CN/cross-session-messaging)，达到了该会话收件箱所能接受的上限。Claude Code 拒绝了下一次发送，接收会话什么都没有收到。拒绝出现在发送会话的工具结果中，而不是作为您终端中的横幅：
4257 4452
4258```text wrap theme={null}4453```text wrap theme={null}
4259Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.4454Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.
4262**应该做什么：**4457**应该做什么：**
4263 4458
4264* 通常不需要做任何事：Claude 将剩余内容批处理为一条消息，或在发送更多内容前等待4459* 通常不需要做任何事：Claude 将剩余内容批处理为一条消息，或在发送更多内容前等待
4265* 如果你自己提示了突发，要求 Claude 将剩余内容合并为单条消息4460* 如果是您自己的提示词引发了这次突发，请要求 Claude 将剩余内容合并为单条消息
4266 4461
4267在 v2.1.236 之前，Claude Code 报告这些发送已发送。接收会话未读地丢弃了它们。4462在 v2.1.236 之前，Claude Code 报告这些消息已发送。接收会话未读地丢弃了它们。
4268 4463
4269<h3 id="cross-session-message-dropped-at-the-inbox">4464<h3 id="cross-session-message-dropped-at-the-inbox">
4270 跨会话消息在收件人会话的收件箱处被丢弃4465 跨会话消息在收件人会话的收件箱处被丢弃
4271</h3>4466</h3>
4272 4467
4273Claude 发送了[跨会话消息](/docs/zh-CN/cross-session-messaging)到此机器上你的另一个会话，该会话的收件箱在 Claude 在该会话中读取之前丢弃了它。该行命名收件人的地址，当收件人给出原因时，在破折号后添加原因：4468Claude 发送了[跨会话消息](/docs/zh-CN/cross-session-messaging)到此机器上您的另一个会话，该会话的收件箱在该会话中的 Claude 读取之前丢弃了它。该行命名收件人的地址，当收件人给出原因时，在破折号后添加原因：
4274 4469
4275```text wrap theme={null}4470```text wrap theme={null}
4276Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.4471Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.
4280 4475
4281在破折号后，该行给出以下一个或多个原因：4476在破折号后，该行给出以下一个或多个原因：
4282 4477
4283* `its queue of undelivered peer messages was full`：收件人已经持有尽可能多的来自其他会话的未送达消息，其队列允许4478* `its queue of undelivered peer messages was full`：收件人持有的来自其他会话的未送达消息已达到其队列允许的上限
4284* `you sent faster than that session accepts`：发送会话的消息到达速度比收件人从一个发送者接受的速度快4479* `you sent faster than that session accepts`：发送会话的消息到达速度比收件人从一个发送者接受的速度快
4285* `it repeated your previous message`：该消息与发送会话不久前发送给该收件人的消息相同4480* `it repeated your previous message`：该消息与发送会话不久前发送给该收件人的消息相同
4286* `a relay loop between sessions was cut`：该消息继续了会话相互发送消息的链，链已通过收件人太多次或增长太长4481* `a relay loop between sessions was cut`：该消息延续了会话之间相互发送消息的链，且该链经过收件人的次数过多或增长过长
4287 4482
4288**应该做什么：**4483**应该做什么：**
4289 4484
4290* 假设收件人从未看到丢弃的消息。Claude Code 告诉 Claude 相同的内容，并告诉它改为在一条稍后的消息中包含仍然重要的任何内容，而不是立即重新发送4485* 假设收件人从未看到丢弃的消息。Claude Code 也会这样告诉 Claude，并告诉它在稍后的一条消息中包含仍然重要的任何内容，而不是立即重新发送
4291* 如果你的会话相互发送频繁更新，要求 Claude 发送更少、更大的消息，例如会话完成其工作时的一份报告4486* 如果您的会话相互发送频繁更新，请要求 Claude 发送更少、更大的消息，例如在会话完成其工作时发送一份报告
4292* 对于 `a relay loop between sessions was cut`，在其中一个会话中自己输入下一条指令。Claude 发送以响应你自己的提示的消息开始一条新链4487* 对于 `a relay loop between sessions was cut`，请在其中一个会话中自己输入下一条指令。Claude 为响应您自己的提示词而发送的消息会开始一条新链
4293 4488
4294在 v2.1.238 之前，当收件人的收件箱丢弃消息时，发送会话没有收到报告。4489在 v2.1.238 之前，当收件人的收件箱丢弃消息时，发送会话没有收到报告。
4295 4490
4297 拒绝发送跨会话消息4492 拒绝发送跨会话消息
4298</h3>4493</h3>
4299 4494
4300在 Claude Code 将[跨会话消息](/docs/zh-CN/cross-session-messaging)写入此机器上你的另一个会话之前，它检查目标会话的收件箱套接字是消息寻址到的端点。当检查失败时，Claude Code 拒绝发送，目标会话什么都没有收到。对于 Claude 发送的消息，拒绝出现在发送会话的工具结果中：4495在 Claude Code 将[跨会话消息](/docs/zh-CN/cross-session-messaging)写入此机器上您的另一个会话之前，它检查目标会话的收件箱套接字是否为消息寻址到的端点。当检查失败时，Claude Code 在发送会话中拒绝发送，目标会话什么都没有收到。对于 Claude 发送的消息，拒绝出现在发送会话的工具结果中：
4301 4496
4302```text theme={null}4497```text theme={null}
4303Failed to send to api-worker: Refusing to send: reply target is a symlink4498Failed to send to api-worker: Refusing to send: reply target is a symlink
4310 4505
4311**应该做什么：**4506**应该做什么：**
4312 4507
4313* 通常不需要做任何事：检查防止消息到达除了它寻址到的会话之外的端点，什么都没有发送4508* 通常不需要做任何事：这些检查防止消息到达其寻址会话之外的端点，且没有发送任何内容
4314* 如果 `reply target is a symlink` 对一个会话重复，检查在该会话的套接字路径处创建了什么链接，显示在其 `/status` 下的 `Peer address`4509* 如果 `reply target is a symlink` 对某个会话重复出现，请检查是什么在该会话的套接字路径处创建了链接，该路径显示在其 `/status` 的 `Peer address` 下
4315 4510
4316<h3 id="refusing-after-a-symlink-changed">4511<h3 id="refusing-after-a-symlink-changed">
4317 拒绝读取、写入或搜索路径4512 拒绝读取、写入或搜索路径
4326每个拒绝命名其原因：4521每个拒绝命名其原因：
4327 4522
4328* `its symlink resolution changed after permission was checked`：路径上的符号链接或 Grep 或 Glob 搜索根在权限检查和操作之间被替换。在读取拒绝中，括号中的短语命名哪个比较失败。4523* `its symlink resolution changed after permission was checked`：路径上的符号链接或 Grep 或 Glob 搜索根在权限检查和操作之间被替换。在读取拒绝中，括号中的短语命名哪个比较失败。
4329* `its parent-directory symlink resolution changed after permission was checked`：写入路径通过的目录不再解析到批准的位置4524* `its parent-directory symlink resolution changed after permission was checked`：写入路径经过的目录不再解析到批准的位置
4330* `where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)`：Claude Code 无法跟随路径到磁盘上的最终位置，例如因为其上的符号链接形成循环4525* `where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)`：Claude Code 无法跟随路径到磁盘上的最终位置，例如因为其上的符号链接形成循环
4331* `it is a symbolic link. Write to the link's target path instead`：符号链接位于批准的写入位置本身，例如 `CLAUDE.md` 是 `AGENTS.md` 的符号链接；消息指导 Claude 到链接的目标4526* `it is a symbolic link. Write to the link's target path instead`：符号链接位于请求的写入位置本身，例如 `CLAUDE.md` 是 `AGENTS.md` 的符号链接；消息指导 Claude 转向链接的目标
4332* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`：当另一个写入器打开文件时捕获的相同条件，例如写入符号链接的 `.mcp.json`4527* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`：当另一个写入器打开文件时捕获的相同条件，例如写入符号链接的 `.mcp.json`
4333* `Refusing to write into symlinked directory: <path>`：持有文件的目录本身是符号链接，例如项目的 `.claude/` 目录链接到另一个位置4528* `Refusing to write into symlinked directory: <path>`：持有文件的目录本身是符号链接，例如项目的 `.claude/` 目录链接到另一个位置
4334* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`：搜索的 `Read` 拒绝规则命名通过符号链接的路径，该链接在 Claude Code 准备搜索时更改4529* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`：搜索的 `Read` 拒绝规则命名了经过符号链接的路径，该链接在 Claude Code 准备搜索时发生更改
4335* `it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.`：搜索根存在但无法打开；括号中的代码是操作系统错误4530* `it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.`：搜索根存在但无法打开；括号中的代码是操作系统错误
4336* `its permission check expired before it ran (too many concurrent file operations). Retry.`：Claude Code 在许多同时文件操作下驱逐了批准记录，然后工具使用了它；重试运行新的权限检查4531* `its permission check expired before it ran (too many concurrent file operations). Retry.`：在大量同时进行的文件操作下，Claude Code 在工具使用批准记录之前将其逐出；重试会运行新的权限检查
4337* `ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration`：Claude Code 无法将 `rg` 二进制文件解析为绝对路径，因此它拒绝工作目录外的搜索，而不是运行你的拒绝规则不覆盖的搜索4532* `ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration`：Claude Code 无法将 `rg` 二进制文件解析为绝对路径，因此它拒绝工作目录外的搜索，而不是运行您的拒绝规则无法覆盖的搜索
4338 4533
4339**应该做什么：**4534**应该做什么：**
4340 4535
4341* 通常不需要做任何事：拒绝到达 Claude 作为工具结果，拒绝的操作不运行4536* 通常不需要做任何事：拒绝作为工具结果到达 Claude，被拒绝的操作不会运行
4342* 如果符号链接拒绝在一个路径上重复，找到什么保持在那里重写链接，例如构建工具或文件监视程序，或要求 Claude 使用文件的解析路径而不是链接的路径4537* 如果符号链接拒绝在某个路径上重复出现，请找出是什么在不断重写那里的链接，例如构建工具或文件监视程序，或要求 Claude 使用文件的解析路径而不是链接路径
4343* 如果此拒绝对 Windows 上 AppContainer 或受限令牌沙箱内运行的每个文件出现，升级到 v2.1.265 或更高版本4538* 如果 Claude Code 在 Windows 上的 AppContainer 或受限令牌沙箱内运行时，每个文件都出现此拒绝，请升级到 v2.1.265 或更高版本
4344* 如果读取拒绝在 macOS 上出现，针对没有任何东西重写的文件，例如拖入提示的屏幕截图，升级到 v2.1.273 或更高版本4539* 如果在 macOS 上，对没有任何东西在重写的文件（例如拖入提示词的屏幕截图）出现读取拒绝，请升级到 v2.1.273 或更高版本
4345* 对于 ripgrep 拒绝，使用你的包管理器安装 ripgrep，以便 `rg` 在 `PATH` 上解析为绝对路径，或将搜索保持在工作目录下4540* 对于 ripgrep 拒绝，使用您的包管理器安装 ripgrep，以便 `rg` 在 `PATH` 上解析为绝对路径，或将搜索保持在工作目录下
4346 4541
4347在 v2.1.251 之前，Claude Code 仅对文件写入重新检查路径的解析，因此在权限检查后替换的链接可能会将读取或搜索重定向到不同的位置而没有消息。其中，仅父目录、通过符号链接和符号链接目录写入拒绝出现在早期版本上。4542在 v2.1.251 之前，Claude Code 仅对文件写入重新检查路径的解析，因此在权限检查后替换的链接可能会将读取或搜索重定向到不同的位置而没有消息。其中，仅父目录、通过符号链接和符号链接目录写入拒绝会出现在早期版本上。
4348 4543
4349在 v2.1.280 之前，`where it leads on disk could not be determined` 拒绝没有出现。4544在 v2.1.280 之前，`where it leads on disk could not be determined` 拒绝没有出现。
4350 4545
4358task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.4553task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.
4359```4554```
4360 4555
4361括号中的文本命名失败的检查。诸如 `output symlink was re-pointed`、`output file identity changed` 和 `not a regular file` 之类的原因都报告相同的条件：输出路径上或沿着的某些东西不再是 Claude Code 创建的文件。仅某些原因携带 `To recover:` 句子。4556括号中的文本命名失败的检查。诸如 `output symlink was re-pointed`、`output file identity changed` 和 `not a regular file` 之类的原因都报告相同的条件：输出路径上或沿途的某些东西不再是 Claude Code 创建的文件。仅某些原因携带 `To recover:` 句子。
4362 4557
4363如果在命令仍在运行时检查失败，Claude Code 停止该命令，其结果报告：4558如果在命令仍在运行时检查失败，Claude Code 停止该命令，其结果报告：
4364 4559
4370 4565
4371* 升级到 v2.1.260 或更高版本。早期版本有时在没有链接或移动目录存在时显示此消息4566* 升级到 v2.1.260 或更高版本。早期版本有时在没有链接或移动目录存在时显示此消息
4372* 使用设置为新目录的 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars)重启 Claude Code4567* 使用设置为新目录的 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars)重启 Claude Code
4373* 或检查你的项目在 Claude Code 临时目录下的目录，示例消息中的 `/private/tmp/claude-501/-Users-you-my-project`。如果该路径是符号链接或不应该存在的目录，删除链接或目录本身而不是链接的目标，然后重启 Claude Code4568* 或检查您的项目在 Claude Code 临时目录下的目录，示例消息中的 `/private/tmp/claude-501/-Users-you-my-project`。如果该路径是符号链接或不应该存在的目录，删除链接或目录本身而不是链接的目标，然后重启 Claude Code
4374* 如果拒绝重复，进程在会话运行时替换、链接或删除 Claude Code 临时目录下的条目。将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为没有其他东西管理的目录并重启4569* 如果拒绝重复出现，说明有进程在会话运行时替换、链接或删除 Claude Code 临时目录下的条目。将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为没有其他东西管理的目录并重启
4375 4570
4376<h3 id="disk-quota-or-temp-filesystem-is-full">4571<h3 id="disk-quota-or-temp-filesystem-is-full">
4377 磁盘配额或临时文件系统已满4572 磁盘配额或临时文件系统已满
4378</h3>4573</h3>
4379 4574
4380Claude Code 将每个 Bash 和 PowerShell 命令的输出保存到其临时目录下的文件。当命令以非零代码退出且完全没有输出时，Claude Code 检查持有该文件的文件系统是否空间不足或 inode 不足，或你在其上的磁盘配额是否已用完。如果是这样，诊断出现在命令的结果中，代替空输出：4575Claude Code 将每个 Bash 和 PowerShell 命令的输出保存到其临时目录下的文件。当命令以非零代码退出且完全没有输出时，Claude Code 检查持有该文件的文件系统是否空间不足或 inode 不足，或您在其上的磁盘配额是否已用完。如果是这样，诊断出现在命令的结果中，代替空输出：
4381 4576
4382```text wrap theme={null}4577```text wrap theme={null}
4383Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.4578Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.
4385 4580
4386该消息命名什么用完了：4581该消息命名什么用完了：
4387 4582
4388* `Your disk quota is full ... (EDQUOT)`：你在该文件系统上的配额已用完。配额可以在文件系统仍显示可用空间时已满4583* `Your disk quota is full ... (EDQUOT)`：您在该文件系统上的配额已用完。配额可以在文件系统仍显示可用空间时已满
4389* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`：文件系统或你在其上的配额没有剩余空间4584* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`：文件系统或您在其上的配额没有剩余空间
4390* `Command output was lost: the temp filesystem at ... is full` 或 `... is out of inodes`：文件系统几乎没有剩余空间，或 inode 即将用完4585* `Command output was lost: the temp filesystem at ... is full` 或 `... is out of inodes`：文件系统几乎没有剩余空间，或 inode 即将用完
4391 4586
4392**应该做什么：**4587**应该做什么：**
4393 4588
4394* 删除你在持有 Claude Code 临时目录的文件系统上不再需要的文件。对于 `EDQUOT`，删除计入你自己配额的文件。对于 `out of inodes`，删除许多文件而不是几个大文件，因为每个文件占用一个 inode，无论其大小如何4589* 删除您在持有 Claude Code 临时目录的文件系统上不再需要的文件。对于 `EDQUOT`，删除计入您自己配额的文件。对于 `out of inodes`，删除许多文件而不是几个大文件，因为每个文件占用一个 inode，无论其大小如何
4395* 或使用设置为具有空间的文件系统上的目录的 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars)重启 Claude Code4590* 或使用设置为具有空间的文件系统上的目录的 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars)重启 Claude Code
4396* 然后让 Claude 再次运行该命令。它打印的输出已丢失，未被截断4591* 然后让 Claude 再次运行该命令。它打印的输出已丢失，未被截断
4397 4592
4399 源文件不是有效的 UTF-8 文本4594 源文件不是有效的 UTF-8 文本
4400</h3>4595</h3>
4401 4596
4402Claude 尝试从字节不解码为文本的文件发布[工件](/docs/zh-CN/artifacts)，或其文本已包含替换字符 `U+FFFD`，因此 Claude Code 拒绝发布，然后上传任何内容。消息出现在 Artifact 工具结果中并命名第一个要修复的位置：4597Claude 尝试从一个字节无法解码为文本、或其文本已包含替换字符 `U+FFFD` 的文件发布 [Artifact](/docs/zh-CN/artifacts)，因此 Claude Code 在上传任何内容之前拒绝了发布。消息出现在 Artifact 工具结果中并命名第一个要修复的位置：
4403 4598
4404```text wrap theme={null}4599```text wrap theme={null}
4405file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.4600file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.
4407file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.4602file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.
4408```4603```
4409 4604
4410Claude Code 将文件解码为 UTF-8，或当它以小端 UTF-16 字节顺序标记开始时解码为 UTF-16。当这样的 UTF-16 文件不解码时，第一条消息命名 `UTF-16` 并仍然告诉你将文件重写为 UTF-8。当更多位置跟随命名的位置时，消息在位置后添加计数，例如 `(+2 more)`。4605Claude Code 将文件解码为 UTF-8，或当它以小端 UTF-16 字节顺序标记开始时解码为 UTF-16。当这样的 UTF-16 文件无法解码时，第一条消息命名 `UTF-16` 并仍然告诉您将文件重写为 UTF-8。当命名的位置之后还有更多位置时，消息在位置后添加计数，例如 `(+2 more)`。
4411 4606
4412**应该做什么：**4607**应该做什么：**
4413 4608
4414* 通常不需要做任何事：Claude 重写文件并再次发布4609* 通常不需要做任何事：Claude 重写文件并再次发布
4415* 如果文件是你写或导出的，再次将其保存为 UTF-8，并将每个 `U+FFFD` 替换为早期编辑、粘贴或转换丢失的字符4610* 如果文件是您编写或导出的，请再次将其保存为 UTF-8，并将每个 `U+FFFD` 替换为早期编辑、粘贴或转换丢失的字符
4416* 要在页面上显示有意的 `U+FFFD`，在 HTML 中将其写为 `�` 而不是文字字符4611* 要在页面上显示有意的 `U+FFFD`，在 HTML 中将其写为 `�` 而不是字面字符
4612
4613在 v2.1.267 之前，Claude Code 不加检查地上传这样的文件，而由服务器拒绝发布。
4614
4615<h3 id="not-published-that-file-is-on-a-network-share">
4616 未发布：该文件位于网络共享上
4617</h3>
4618
4619Claude 尝试从一个路径指向网络主机的文件发布 [Artifact](/docs/zh-CN/artifacts)：
4417 4620
4418在 v2.1.267 之前，Claude Code 上传这样的文件而不检查它，服务器拒绝发布。4621* 在 Windows 上，不在您启动时通过 [`--add-dir`](/docs/zh-CN/cli-reference#cli-flags) 传入的映射网络驱动器下的 `\\server\share` 路径
4622* 在 macOS 或 Linux 上，自动挂载路径，例如 `/net/<host>/page.html`
4623
4624查找此类路径会联系其指向的主机，而在 Windows 上，这种联系可能会将您的凭据发送给该主机。Claude Code 拒绝发布该文件，也不会读取它。拒绝出现在 Artifact 工具结果中：
4625
4626```text theme={null}
4627Not published: that file is on a network share. Publish a file from this session's folders instead.
4628```
4629
4630**应该做什么：**
4631
4632* 如果您不需要该特定文件，则无需执行任何操作：消息会告诉 Claude 改为从会话自己的文件夹发布文件
4633* 要发布该特定文件，请将其复制到本地磁盘上的文件夹中，然后再次请求
4634* 在 Windows 上，要让 Claude 直接从共享发布，请将其映射到驱动器号，并在启动 Claude Code 时传入该驱动器。例如，在 PowerShell 中运行 `net use Z: \\server\share`，然后运行 `claude --add-dir Z:\`。之后 Claude 就可以从该驱动器发布文件。在会话中途使用 `/add-dir` 添加驱动器是不够的。
4635* 在 macOS 或 Linux 上，将共享挂载到某个目录（例如 `/mnt` 或 `/Volumes` 下的目录），并从该路径而不是自动挂载路径发布
4419 4636
4420<h3 id="reading-a-local-file-from-outside-the-connected-folders">4637<h3 id="reading-a-local-file-from-outside-the-connected-folders">
4421 在 Cowork 会话中从连接的文件夹外读取本地文件4638 在 Cowork 会话中从连接的文件夹外读取本地文件
4422</h3>4639</h3>
4423 4640
4424在 Claude Desktop 应用中在你的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude 为[工件](/docs/zh-CN/artifacts)命名了本地文件。Claude Code 无法确认文件是会话连接的文件夹内的纯文件：路径位于这些文件夹外、通过符号链接或以可能命名不同文件的方式拼写。读取这样的文件需要你的批准，在无法向你显示批准卡的会话中，例如设置为跳过所有批准的会话，Claude Code 拒绝读取。4641在 Claude Desktop 应用中于您的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude 为 [Artifact](/docs/zh-CN/artifacts) 指定了一个本地文件。Claude Code 无法确认该文件是会话连接的文件夹内的普通文件：路径位于这些文件夹之外、经过符号链接，或者其写法可能指向与表面不同的文件。读取这样的文件需要您的批准，而在无法向您显示批准卡片的会话中（例如设置为跳过所有批准的会话），Claude Code 会拒绝读取。
4425 4642
4426拒绝出现在 Artifact 工具结果中；当文件根本无法检查时，它改为命名该失败：4643拒绝出现在 Artifact 工具结果中；当文件根本无法检查时，它改为命名该失败：
4427 4644
4433 4650
4434**应该做什么：**4651**应该做什么：**
4435 4652
4436* 通常不需要做任何事：消息告诉 Claude 改为使用连接的文件夹内的纯文件4653* 通常不需要做任何事：消息告诉 Claude 改为使用连接的文件夹内的普通文件
4437* 要将该确切文件放在工件中，将其复制到会话的连接文件夹之一中作为常规文件（不是符号链接），然后再次询问4654* 要将该特定文件放入 Artifact，请将其作为常规文件（而非符号链接）复制到会话的某个连接文件夹中，然后再次请求
4438 4655
4439<h3 id="webfetch-cannot-fetch-localhost">4656<h3 id="webfetch-cannot-fetch-localhost">
4440 WebFetch 无法获取 localhost4657 WebFetch 无法获取 localhost
4441</h3>4658</h3>
4442 4659
4443Claude 调用了 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior)，其 URL 的主机名没有点，例如 `http://localhost:3000` 或裸 intranet 名称如 `http://wiki/`。WebFetch 在进行任何请求之前拒绝这些 URL：4660Claude 调用了 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior)，其 URL 的主机名中没有点，例如 `http://localhost:3000` 或类似 `http://wiki/` 的纯内网名称。WebFetch 在发出任何请求之前拒绝这些 URL：
4444 4661
4445```text wrap theme={null}4662```text wrap theme={null}
4446WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.4663WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.
4448 4665
4449**应该做什么：**4666**应该做什么：**
4450 4667
4451* 通常不需要做任何事：消息指向 Claude 通过 Bash 工具使用 `curl`，它可以到达本地和 intranet 服务器4668* 通常不需要做任何事：消息引导 Claude 通过 Bash 工具使用 `curl`，它可以访问本地和内网服务器
4452 4669
4453在 v2.1.268 之前，WebFetch 用通用 `Invalid URL` 错误报告这些 URL。4670在 v2.1.268 之前，WebFetch 用通用的 `Invalid URL` 错误报告这些 URL。
4454 4671
4455<h3 id="webfetch-domain-safety-check-failed">4672<h3 id="webfetch-domain-safety-check-failed">
4456 WebFetch 域名安全检查失败4673 WebFetch 域名安全检查失败
4457</h3>4674</h3>
4458 4675
4459在获取 URL 之前，WebFetch 将 URL 的主机名发送到 `api.anthropic.com` 以根据 Anthropic 的[域名安全阻止列表](/docs/zh-CN/data-usage#webfetch-domain-safety-check)检查它。如果检查无法完成，WebFetch 无法确认域名是安全的，因此它不获取页面，工具结果改为携带以下消息之一：4676在获取 URL 之前，WebFetch 将 URL 的主机名发送到 `api.anthropic.com`，以根据 Anthropic 的[域名安全阻止列表](/docs/zh-CN/data-usage#webfetch-domain-safety-check)检查它。如果检查无法完成，WebFetch 无法确认域名是安全的，因此它不获取页面，工具结果改为携带以下消息之一：
4460 4677
4461```text wrap theme={null}4678```text wrap theme={null}
4462The safety check for domain example.com is rate-limited (too many domain checks from this network; the limit is shared and can stay exhausted for minutes). Do not retry WebFetch in a loop or sleep to wait it out; continue without this page and report that its safety check was rate-limited. A single later attempt is fine; if that is rate-limited too, stop.4679The safety check for domain example.com is rate-limited (too many domain checks from this network; the limit is shared and can stay exhausted for minutes). Do not retry WebFetch in a loop or sleep to wait it out; continue without this page and report that its safety check was rate-limited. A single later attempt is fine; if that is rate-limited too, stop.
4464Unable to verify if domain example.com is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.4681Unable to verify if domain example.com is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.
4465```4682```
4466 4683
4467* `rate-limited`：检查端点以 HTTP `429` 回答。消息告诉 Claude 继续而不使用页面，最多稍后再尝试一次。Claude Code 不缓存失败的检查，因此该域的稍后获取再次运行检查。如果你的网络上的会话经常遇到这种情况，你可以使用[`skipWebFetchPreflight: true`](/docs/zh-CN/settings-reference#skipwebfetchpreflight)在设置中跳过检查。4684* `rate-limited`：检查端点以 HTTP `429` 响应。消息告诉 Claude 在没有该页面的情况下继续，并且稍后最多再尝试一次。Claude Code 不缓存失败的检查，因此稍后获取该域名时会再次运行检查。如果您网络上的会话经常遇到这种情况，您可以在设置中使用 [`skipWebFetchPreflight: true`](/docs/zh-CN/settings-reference#skipwebfetchpreflight) 跳过检查。
4468* `Unable to verify`：检查请求失败、超时或获得另一个错误状态。如果你的网络阻止 `api.anthropic.com`，允许列表该域，或使用[`skipWebFetchPreflight: true`](/docs/zh-CN/settings-reference#skipwebfetchpreflight)在设置中跳过检查。4685* `Unable to verify`：检查请求失败、超时或收到其他错误状态。如果您的网络阻止 `api.anthropic.com`，请将该域名加入允许列表，或在设置中使用 [`skipWebFetchPreflight: true`](/docs/zh-CN/settings-reference#skipwebfetchpreflight) 跳过检查。
4469 4686
4470在 v2.1.286 之前，速率限制消息读取 `The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.`。4687在 v2.1.286 之前，速率限制消息为 `The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.`。
4471在 v2.1.285 之前，速率限制检查用 `Unable to verify` 消息报告。4688在 v2.1.285 之前，被限流的检查改为用 `Unable to verify` 消息报告。
4472 4689
4473<h2 id="background-session-errors">4690<h2 id="background-session-errors">
4474 后台会话错误4691 后台会话错误
4475</h2>4692</h2>
4476 4693
4477[后台会话](/docs/zh-CN/agent-view)在没有自己的交互式终端的情况下运行，因此需要终端的命令在那里的行为会有所不同。这些消息出现在后台会话的记录中、附加到后台会话的终端中、您分派的会话或 shell 中，或者对于下面的[worktree-guard 条目](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)，出现在任何在 worktree 中隔离的会话或运行 worktree 隔离子代理中；当消息特定于一个表面时，其条目会说明这一点。4694[后台会话](/docs/zh-CN/agent-view)在没有自己的交互式终端的情况下运行，因此需要终端的命令在那里的行为会有所不同。这些消息出现在后台会话的会话记录中、附加到后台会话的终端中、您分派的会话或 shell 中，或者对于下面的[worktree-guard 条目](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)，出现在任何在 worktree 中隔离的会话或运行 worktree 隔离子代理中；当消息特定于一个使用入口时，其条目会说明这一点。
4478 4695
4479<h3 id="commands-refused-in-a-background-session">4696<h3 id="commands-refused-in-a-background-session">
4480 后台会话中拒绝的命令4697 后台会话中拒绝的命令
4481</h3>4698</h3>
4482 4699
4483打开交互式对话框的命令在没有终端附加到后台会话时无法执行。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作会响应一条消息。对于 `/install-github-app` 和 `/mcp` 设置列表，该会话也在[代理视图](/docs/zh-CN/agent-view)中的**需要输入**下显示，以便您可以找到它、附加并再次运行该命令。附加终端时，这些命令正常工作。4700打开交互式对话框的命令在没有终端附加到后台会话时无法执行。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作会响应一条消息。对于 `/install-github-app` 和 `/mcp` 设置列表，该会话也在 [Agent 视图](/docs/zh-CN/agent-view)中的**需要输入**下显示，以便您可以找到它、附加并再次运行该命令。附加终端时，这些命令正常工作。
4484 4701
4485在 v2.1.216 之前，会话在拒绝 `/install-github-app` 或 `/mcp` 设置列表后不会在**需要输入**下显示。在 v2.1.213 到 v2.1.215 中，附加终端时命令仍然有效，拒绝消息告诉您附加并再次运行该命令。从 v2.1.208 到 v2.1.212，Claude Code 即使附加了终端也拒绝了它们，消息如 `Can't open MCP settings in a background session`；在这些版本上，从常规 `claude` 会话运行该命令，或升级。在 v2.1.208 之前，它们在后台会话内打开了对话框。在仅 v2.1.208 中，Claude Code 也拒绝了后台会话中的 `/model` 选择器，`/upgrade` 打印了升级 URL 而不是打开浏览器。4702在 v2.1.216 之前，会话在拒绝 `/install-github-app` 或 `/mcp` 设置列表后不会在**需要输入**下显示。在 v2.1.213 到 v2.1.215 中，附加终端时命令仍然有效，拒绝消息告诉您附加并再次运行该命令。从 v2.1.208 到 v2.1.212，Claude Code 即使附加了终端也拒绝了它们，消息如 `Can't open MCP settings in a background session`；在这些版本上，从常规 `claude` 会话运行该命令，或升级。在 v2.1.208 之前，它们在后台会话内打开了对话框。在仅 v2.1.208 中，Claude Code 也拒绝了后台会话中的 `/model` 选择器，`/upgrade` 打印了升级 URL 而不是打开浏览器。
4486 4703
4492 4709
4493**要做什么：**4710**要做什么：**
4494 4711
4495* 从代理视图附加到会话并再次运行该命令4712* 从 Agent 视图附加到会话并再次运行该命令
4496* 或使用消息命名的形式，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`，这些不需要附加即可工作4713* 或使用消息命名的形式，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`，这些不需要附加即可工作
4497 4714
4498<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">4715<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">
4509 4726
4510**要做什么：**4727**要做什么：**
4511 4728
4512* 通常什么都不做：完整消息作为工具错误发送给 Claude，Claude 使用它命名的直接路径重试。对于被阻止的文件编辑，对话视图仅显示简短的 `Error editing file` 行；完整消息出现在您使用 `Ctrl+O` 打开的记录视图中。被阻止的命令在其命令输出中打印它。4729* 通常什么都不做：完整消息作为工具错误发送给 Claude，Claude 使用它命名的直接路径重试。对于被阻止的文件编辑，对话视图仅显示简短的 `Error editing file` 行；完整消息出现在您使用 `Ctrl+O` 打开的会话记录视图中。被阻止的命令在其命令输出中打印它。
4513* 如果同一文件上的块重复，路径可能通过包含 `..` 的已提交符号链接运行，例如 `docs/current -> ../README.md`；要求 Claude 通过其真实路径而不是通过链接编辑目标文件4730* 如果同一文件上的阻止重复出现，路径可能通过包含 `..` 的已提交符号链接运行，例如 `docs/current -> ../README.md`；要求 Claude 通过其真实路径而不是通过链接编辑目标文件
4514 4731
4515<h3 id="write-or-command-blocked-because-the-path-names-a-network-location">4732<h3 id="write-or-command-blocked-because-the-path-names-a-network-location">
4516 写入或命令被阻止，因为路径命名网络位置4733 写入或命令被阻止，因为路径命名网络位置
4550* 要有意对主检出采取行动，在会话外的终端中自己运行该命令4767* 要有意对主检出采取行动，在会话外的终端中自己运行该命令
4551 4768
4552<h3 id="this-session-has-no-saved-transcript">4769<h3 id="this-session-has-no-saved-transcript">
4553 此会话没有保存的记录4770 此会话没有保存的会话记录
4554</h3>4771</h3>
4555 4772
4556您附加到一个停止的[后台会话](/docs/zh-CN/agent-view)，该会话从另一个对话中用 `←` 或 `/background` 后台化，并在其第一个响应完成之前停止。在该第一个响应完成之前，对话仍然仅存在于后台化它的会话中，因此 `claude attach` 拒绝启动停止的会话，而不是在相同的会话 ID 下开始空白对话。消息以此会话的 `claude respawn` 命令结尾：4773您附加到一个停止的[后台会话](/docs/zh-CN/agent-view)，该会话从另一个对话中用 `←` 或 `/background` 后台化，并在其第一个回复完成之前停止。在该第一个回复完成之前，对话仍然仅存在于后台化它的会话中，因此 `claude attach` 拒绝启动停止的会话，而不是在相同的会话 ID 下开始空白对话。消息以此会话的 `claude respawn` 命令结尾：
4557 4774
4558```text theme={null}4775```text theme={null}
4559This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4776This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.
4560```4777```
4561 4778
4562在[代理视图](/docs/zh-CN/agent-view)中打开相同会话的行显示 `Press enter again to restart this session fresh` 在列表下方，在该行上第二次 `Enter` 使用空对话重启会话。在 v2.1.212 之前，打开该行显示拒绝消息，无法从代理视图重启。在 v2.1.211 之前，打开停止的会话无声地启动了该空白对话，并可能重新运行会话的原始提示。4779在 [Agent 视图](/docs/zh-CN/agent-view)中打开相同会话的行会在列表下方显示 `Press enter again to restart this session fresh`，在该行上第二次按 `Enter` 会使用空对话重启会话。在 v2.1.212 之前，打开该行显示拒绝消息，无法从 Agent 视图重启。在 v2.1.211 之前，打开停止的会话会无声地启动该空白对话，并可能重新运行会话的原始提示词。
4563 4780
4564**要做什么：**4781**要做什么：**
4565 4782
4566* 您后台化的对话是完整的：使用 [`claude --resume`](/docs/zh-CN/sessions) 恢复它或继续在其中工作4783* 您后台化的对话是完整的：使用 [`claude --resume`](/docs/zh-CN/sessions) 恢复它或继续在其中工作
4567* 要无论如何启动停止的会话，请使用消息中的 ID 运行 `claude respawn <id>`，或在代理视图中的其行上按 `Enter` 两次4784* 要无论如何启动停止的会话，请使用消息中的 ID 运行 `claude respawn <id>`，或在 Agent 视图中的其行上按 `Enter` 两次
4568* 如果会话确实完成了响应，您仍然在 v2.1.214 之前的版本上看到此拒绝，`~/.claude/projects` 中的不可读文件夹可能会使记录扫描错过保存的对话；更新到 v2.1.214 或更高版本，它在扫描期间容忍不可读的文件夹4785* 如果会话确实完成了回复，您仍然在 v2.1.214 之前的版本上看到此拒绝，`~/.claude/projects` 中的不可读文件夹可能会使会话记录扫描错过保存的对话；更新到 v2.1.214 或更高版本，它在扫描期间容忍不可读的文件夹
4569 4786
4570<h3 id="this-session-is-running-in-another-terminal">4787<h3 id="this-session-is-running-in-another-terminal">
4571 此会话在另一个终端中运行4788 此会话在另一个终端中运行
4572</h3>4789</h3>
4573 4790
4574您在[代理视图](/docs/zh-CN/agent-view)中打开了停止的会话的行，其保存的对话已在此机器上的另一个实时 Claude Code 进程中打开，因此 Claude Code 拒绝启动将写入相同记录的第二个进程。您看到的消息取决于[什么持有对话](/docs/zh-CN/agent-view#opening-a-session-says-the-conversation-is-already-open)：4791您在 [Agent 视图](/docs/zh-CN/agent-view)中打开了停止的会话的行，其保存的对话已在此机器上的另一个实时 Claude Code 进程中打开，因此 Claude Code 拒绝启动将写入相同会话记录的第二个进程。您看到的消息取决于[什么持有对话](/docs/zh-CN/agent-view#opening-a-session-says-the-conversation-is-already-open)：
4575 4792
4576```text theme={null}4793```text theme={null}
4577Can't open — this session is running in another terminal4794Can't open — this session is running in another terminal
4581* **`running in another terminal`**：终端持有对话，例如您使用 `claude --resume` 或 `/resume` 恢复它的终端。该行也显示 `Open in a terminal`。4798* **`running in another terminal`**：终端持有对话，例如您使用 `claude --resume` 或 `/resume` 恢复它的终端。该行也显示 `Open in a terminal`。
4582* **`already open in another running Claude session`**：另一个非交互式 Claude Code 进程持有它，例如相同对话的[后台会话](/docs/zh-CN/agent-view#the-supervisor-process)进程尚未退出。4799* **`already open in another running Claude session`**：另一个非交互式 Claude Code 进程持有它，例如相同对话的[后台会话](/docs/zh-CN/agent-view#the-supervisor-process)进程尚未退出。
4583 4800
4584Claude Code 保存您在打开行时键入的回复，并在会话下次启动时将其作为会话的下一个提示发送。4801Claude Code 保存您在打开行时键入的回复，并在会话下次启动时将其作为会话的下一个提示词发送。
4585 4802
4586**要做什么：**4803**要做什么：**
4587 4804
4593 此会话的保存对话不再在磁盘上4810 此会话的保存对话不再在磁盘上
4594</h3>4811</h3>
4595 4812
4596您打开了一个[后台会话](/docs/zh-CN/agent-view)，该会话在后台服务关闭时结束，[记录清理](/docs/zh-CN/settings-reference#cleanupperioddays)随后删除了其保存的对话，例如在机器关闭数周后。通常打开这样的行会[恢复其保存的对话](/docs/zh-CN/agent-view#sessions-show-as-failed-after-shutdown)。没有什么可恢复的，Claude Code 拒绝而不是在不询问的情况下重新运行会话的原始提示：4813您打开了一个[后台会话](/docs/zh-CN/agent-view)，该会话在后台服务关闭时结束，[会话记录清理](/docs/zh-CN/settings-reference#cleanupperioddays)随后删除了其保存的对话，例如在机器关闭数周后。通常打开这样的行会[恢复其保存的对话](/docs/zh-CN/agent-view#sessions-show-as-failed-after-shutdown)。没有什么可恢复的，Claude Code 拒绝而不是在不询问的情况下重新运行会话的原始提示词：
4597 4814
4598```text theme={null}4815```text theme={null}
4599This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.4816This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.
4600```4817```
4601 4818
4602`claude attach <id>` 打印此文本。在代理视图中，页脚更短，以 `ctrl+x deletes the row` 结尾。4819`claude attach <id>` 打印此文本。在 Agent 视图中，页脚更短，以 `ctrl+x deletes the row` 结尾。
4603 4820
4604**要做什么：**4821**要做什么：**
4605 4822
4606* 运行 `claude rm <id>` 删除该行。当[保留的情况](/docs/zh-CN/agent-view#what-deleting-a-session-removes)之一适用时，`claude rm` 保留该行和 worktree，并命名原因4823* 运行 `claude rm <id>` 删除该行。当[保留的情况](/docs/zh-CN/agent-view#what-deleting-a-session-removes)之一适用时，`claude rm` 保留该行和 worktree，并命名原因
4607* 要再次运行会话的原始提示作为新对话，请运行 `claude respawn <id>`4824* 要再次运行会话的原始提示词作为新对话，请运行 `claude respawn <id>`
4608 4825
4609在 v2.1.248 之前，打开这样的行会重新运行会话的原始提示，而不是拒绝，将数周前的任务拉回前景。4826在 v2.1.248 之前，打开这样的行会重新运行会话的原始提示词，而不是拒绝，将数周前的任务拉回前台。
4610 4827
4611<h3 id="worktree-has-commits-that-are-not-pushed-anywhere">4828<h3 id="worktree-has-commits-that-are-not-pushed-anywhere">
4612 Worktree 有未推送到任何地方的提交4829 Worktree 有未推送到任何地方的提交
4613</h3>4830</h3>
4614 4831
4615您尝试删除一个[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)，其 worktree 持有 Claude Code 无法确认保存在其他地方的提交。Claude Code 保留 worktree 和会话行，而不是销毁提交。`claude rm` 命名分支和未推送的提交，并说明如何继续：4832您尝试删除一个[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)，其 worktree 持有 Claude Code 无法确认保存在其他地方的提交。Claude Code 保留 worktree 和会话行，而不是在未查看的情况下销毁提交。`claude rm` 命名分支和未推送的提交，并说明如何继续：
4616 4833
4617```text theme={null}4834```text theme={null}
4618kept 7c5dcf5d — its worktree is still at "/home/you/project/.claude/worktrees/fix-login"4835kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”
4619 2 unpushed commits on "claude/fix-login": a1b2c3d "Fix login flow" and 1 more. They exist on no remote, so deleting the worktree would lose them.4836 2 unpushed commits on “claude/fix-login”: a1b2c3d “Fix login flow” and 1 more. They exist on no remote, so deleting the worktree would lose them.
4620 push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef4837 push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef
4621```4838```
4622 4839
4623当 Claude Code 无法总结提交时，详细行读取 `The worktree has unpushed commits`。在[代理视图](/docs/zh-CN/agent-view)中，会话的行显示 `not deleted` 和相同的原因。4840当 Claude Code 无法总结提交时，详细行读取 `The worktree has unpushed commits`。在 [Agent 视图](/docs/zh-CN/agent-view)中，会话的行显示 `not deleted` 和相同的原因。
4624 4841
4625远程上的提交不会阻止删除。本地副本中您的 `origin` 远程的默认分支上的提交也不会，只要该分支在您的主检出中检出，即存储库目录本身而不是 worktree。4842远程上的提交不会阻止删除。本地副本中您的 `origin` 远程的默认分支上的提交也不会，只要该分支在您的主检出中检出，即仓库目录本身而不是 worktree。
4626 4843
4627**要做什么：**4844**要做什么：**
4628 4845
4629* 要保留提交，推送 worktree 的分支，或将其合并到在主检出中检出的默认分支，然后再次删除会话4846* 要保留提交，推送 worktree 的分支，或将其合并到在主检出中检出的默认分支，然后再次删除会话
4630* 要丢弃提交，运行消息打印的 `claude rm <id> --discard-unpushed` 命令，或在代理视图中的会话行上再次按 `Ctrl+X`。这会删除会话和 worktree 以及其分支、未推送的提交和任何未提交的更改。如果 worktree 自拒绝以来获得了提交，Claude Code 再次保留它并显示更新的状态4847* 要丢弃提交，运行消息打印的 `claude rm <id> --discard-unpushed` 命令，或在 Agent 视图中的会话行上再次按 `Ctrl+X` 两次。这会删除会话和 worktree 以及其分支、未推送的提交和任何未提交的更改。如果 worktree 自拒绝以来获得了提交，Claude Code 再次保留它并显示更新的状态
4631* 当消息说 worktree 也由另一个完成的会话记录时，再次删除不会丢弃它：推送提交，然后再次删除会话4848* 当消息说 worktree 也由另一个完成的会话记录时，再次删除不会丢弃它：推送提交，然后再次删除会话
4632 4849
4633在 v2.1.268 之前，`claude rm` 将提交摘要放在 `kept` 行本身上。当 `claude rm` 无法总结提交时，`kept` 行读取 `worktree has commits that are not pushed anywhere` 代替摘要。4850在 v2.1.268 之前，`claude rm` 将提交摘要放在 `kept` 行本身上。当 `claude rm` 无法总结提交时，`kept` 行读取 `worktree has commits that are not pushed anywhere` 代替摘要。
4642 4859
4643每个[后台会话的](/docs/zh-CN/agent-view)终端在后台服务下的主机进程中运行，该进程在服务仍然持有其连接时死亡，因此无法到达会话。4860每个[后台会话的](/docs/zh-CN/agent-view)终端在后台服务下的主机进程中运行，该进程在服务仍然持有其连接时死亡，因此无法到达会话。
4644 4861
4645在 Linux 和 WSL 上，后台服务每隔几秒检查每个主机进程，当进程已退出但其与服务的连接从未关闭时标记会话失败，并在[代理视图](/docs/zh-CN/agent-view#read-session-state)中的其行上显示原因：4862在 Linux 和 WSL 上，后台服务每隔几秒检查每个主机进程，当进程已退出但其与服务的连接从未关闭时标记会话失败，并在 [Agent 视图](/docs/zh-CN/agent-view#read-session-state)中的其行上显示原因：
4646 4863
4647```text theme={null}4864```text theme={null}
4648terminal host process died — press Enter to restart4865terminal host process died — press Enter to restart
4656 4873
4657对话无论如何都被保存。4874对话无论如何都被保存。
4658 4875
4659运行[shell 命令](/docs/zh-CN/agent-view#run-a-shell-command)的行显示 `terminal host process died — its output is gone; the command was not run again`，`claude attach` 打印 `This command's terminal host process died — its output is gone and the command was not run again`。Claude Code 从不为您重新运行该命令。4876运行 [shell 命令](/docs/zh-CN/agent-view#run-a-shell-command)的行显示 `terminal host process died — its output is gone; the command was not run again`，`claude attach` 打印 `This command's terminal host process died — its output is gone and the command was not run again`。Claude Code 从不为您重新运行该命令。
4660 4877
4661**要做什么：**4878**要做什么：**
4662 4879
4663* 在代理视图中，在失败的行上按 `Enter`；会话在新的主机进程上重启，对话恢复4880* 在 Agent 视图中，在失败的行上按 `Enter`；会话在新的主机进程上重启，对话恢复
4664* 从 shell，再次运行 `claude attach <id>`。Claude Code 打印 `Session <id>'s terminal host died — restarting it on a fresh one…` 并重新打开会话4881* 从 shell，再次运行 `claude attach <id>`。Claude Code 打印 `Session <id>'s terminal host died — restarting it on a fresh one…` 并重新打开会话
4665* 您无法以这种方式重启 shell 命令行；再次分派命令以重新运行它4882* 您无法以这种方式重启 shell 命令行；再次分派命令以重新运行它
4666 4883
4672 4889
4673您打开了一个[后台会话](/docs/zh-CN/agent-view)，后台服务接受了打开，但大约十秒钟内没有输出到达，因此 Claude Code 得出结论，中继会话终端的进程无法传递输出，并结束尝试而不是等待。4890您打开了一个[后台会话](/docs/zh-CN/agent-view)，后台服务接受了打开，但大约十秒钟内没有输出到达，因此 Claude Code 得出结论，中继会话终端的进程无法传递输出，并结束尝试而不是等待。
4674 4891
4675在代理视图中，Claude Code 在页脚中提供重启：4892在 Agent 视图中，Claude Code 在页脚中提供重启：
4676 4893
4677```text theme={null}4894```text theme={null}
4678Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).4895Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).
4684Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).4901Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).
4685```4902```
4686 4903
4687Claude Code 从不为您重启运行[shell 命令](/docs/zh-CN/agent-view#run-a-shell-command)的行，因为重启会再次运行该命令。4904Claude Code 从不为您重启运行 [shell 命令](/docs/zh-CN/agent-view#run-a-shell-command)的行，因为重启会再次运行该命令。
4688 4905
4689**要做什么：**4906**要做什么：**
4690 4907
4691* 在代理视图中，在同一行上再次按 `Enter`。Claude Code 停止无响应的进程并重启会话，对话恢复。没有第二次按下就不会停止任何东西4908* 在 Agent 视图中，在同一行上再次按 `Enter`。Claude Code 停止无响应的进程并重启会话，对话恢复。没有第二次按下就不会停止任何东西
4692* 从 shell，运行 `claude stop <id>`，然后 `claude attach <id>`4909* 从 shell，运行 `claude stop <id>`，然后 `claude attach <id>`
4693* 对于 shell 命令行，在代理视图中按 `Ctrl+X` 或运行 `claude stop <id>` 停止它；再次分派命令以重新运行它4910* 对于 shell 命令行，在 Agent 视图中按 `Ctrl+X` 或运行 `claude stop <id>` 停止它；再次分派命令以重新运行它
4694 4911
4695<h3 id="session-was-stopped-while-the-respawn-was-in-flight">4912<h3 id="session-was-stopped-while-the-respawn-was-in-flight">
4696 会话在 respawn 进行中时被停止4913 会话在 respawn 进行中时被停止
4702Session <id> was stopped while the respawn was in flight4919Session <id> was stopped while the respawn was in flight
4703```4920```
4704 4921
4705打开您刚刚分派的会话，当其进程仍在启动时，等待进程。在 v2.1.246 之前，在那一刻打开它可能会停止它并显示此消息。4922打开您刚刚分派的会话，当其进程仍在启动时，会改为等待进程。在 v2.1.246 之前，在那一刻打开它可能会停止它并显示此消息。
4706 4923
4707**要做什么：**4924**要做什么：**
4708 4925
4709* 如果您没有停止会话，在代理视图中再次打开其行或运行 `claude respawn <id>` 重启它4926* 如果您没有停止会话，在 Agent 视图中再次打开其行或运行 `claude respawn <id>` 重启它
4710* 如果您自己停止了它，没有什么剩下要做的：会话保持停止4927* 如果您自己停止了它，没有什么剩下要做的：会话保持停止
4711 4928
4712<h3 id="session-agent-no-longer-available">4929<h3 id="session-agent-no-longer-available">
4713 会话代理不再可用4930 会话 Agent 不再可用
4714</h3>4931</h3>
4715 4932
4716您恢复了一个正在运行[自定义代理](/docs/zh-CN/sub-agents#invoke-subagents-explicitly)的会话，使用 `--agent` 或 `agent` 设置启动，Claude Code 没有找到具有该名称的代理。它首先搜索会话的原始目录，当您[信任该工作区](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)时，然后搜索您恢复的目录。会话仍然恢复，但使用默认工具，因此代理的工具限制不再适用：4933您恢复了一个正在运行[自定义 Agent](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 的会话，该会话使用 `--agent` 或 `agent` 设置启动，Claude Code 没有找到具有该名称的 Agent。它首先搜索会话的原始目录（当您已[信任该工作区](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)时），然后搜索您恢复的目录。会话仍然恢复，但使用默认工具，因此 Agent 的工具限制不再适用：
4717 4934
4718```text theme={null}4935```text theme={null}
4719This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.4936This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.
4720```4937```
4721 4938
4722警告仅命名 Claude Code 搜索的目录，它出现在恢复的对话中，无论您唤醒[后台会话](/docs/zh-CN/agent-view)、运行 `/resume` 或 `claude --resume`，还是在[非交互式模式](/docs/zh-CN/headless)中恢复，它也发送到 stderr。使用 `--input-format stream-json` 的会话不显示它，因为 Agent SDK 在启动后提供代理。4939警告仅命名 Claude Code 搜索的目录，它出现在恢复的对话中，无论您唤醒[后台会话](/docs/zh-CN/agent-view)、运行 `/resume` 或 `claude --resume`，还是在[非交互模式](/docs/zh-CN/headless)中恢复，在非交互模式中它也会发送到 stderr。使用 `--input-format stream-json` 的会话不显示它，因为 Agent SDK 在启动后提供 Agent。
4723 4940
4724Claude Code 不保存回退到会话，因此警告在每次恢复时重复，直到您采取行动。内置 `claude` 代理不触发警告，因为回退到默认工具集对它没有改变。在 v2.1.216 之前，Claude Code 无声地继续作为默认代理，查找仅覆盖您恢复的目录，因此项目范围的代理在从另一个目录恢复时丢失。4941Claude Code 不会将回退保存到会话，因此警告在每次恢复时重复，直到您采取行动。内置 `claude` Agent 不触发警告，因为回退到默认工具集对它没有改变。在 v2.1.216 之前，Claude Code 无声地继续作为默认 Agent，查找仅覆盖您恢复的目录，因此项目范围的 Agent 在从另一个目录恢复时丢失。
4725 4942
4726**要做什么：**4943**要做什么：**
4727 4944
4728* 在会话的项目中的 `.claude/agents/<name>.md` 或个人代理的 `~/.claude/agents/<name>.md` 重新创建代理文件，然后再次恢复4945* 在会话的项目中的 `.claude/agents/<name>.md` 或个人 Agent 的 `~/.claude/agents/<name>.md` 重新创建 Agent 文件，然后再次恢复
4729* 或使用 `--agent <name>` 恢复，命名确实存在的代理，以改为作为该代理运行会话4946* 或使用 `--agent <name>` 恢复，命名确实存在的 Agent，以改为作为该 Agent 运行会话
4730* 如果代理是项目范围的，您还没有信任会话的原始目录，在那里运行一次 Claude Code，接受信任对话，然后再次恢复4947* 如果 Agent 是项目范围的，您还没有信任会话的原始目录，在那里运行一次 Claude Code，接受信任对话框，然后再次恢复
4731 4948
4732<h3 id="claude_code_process_wrapper-launcher-errors">4949<h3 id="claude_code_process_wrapper-launcher-errors">
4733 CLAUDE\_CODE\_PROCESS\_WRAPPER 启动器错误4950 CLAUDE\_CODE\_PROCESS\_WRAPPER 启动器错误
4739CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file4956CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file
4740```4957```
4741 4958
4742启动但在用 Claude Code 替换自己之前退出的启动器会使其启动的会话失败，会话在代理视图中的行报告启动器 `must exec, not daemonize`，后跟启动器打印的任何内容。无法启动或到达后台服务的会话因启动器报告启动器问题作为 `Couldn't reach the background service (...)` 内的原因。4959启动但在用 Claude Code 替换自己之前退出的启动器会使其启动的会话失败，会话在 Agent 视图中的行报告启动器 `must exec, not daemonize`，后跟启动器打印的任何内容。因启动器而无法启动或到达后台服务的会话会将启动器问题作为 `Couldn't reach the background service (...)` 内的原因报告。
4743 4960
4744**要做什么：**4961**要做什么：**
4745 4962
4746* 将变量设置为以调用 `exec "$@"` 结尾的可执行文件的绝对路径。有关完整合同，请参阅[启动器合同](/docs/zh-CN/corporate-launcher#the-launcher-contract)4963* 将变量设置为以调用 `exec "$@"` 结尾的可执行文件的绝对路径。有关完整合同，请参阅[启动器合同](/docs/zh-CN/corporate-launcher#the-launcher-contract)
4747* 检查 `/status`，它在其 Self-exec 条目中显示解析的启动命令，并在运行的后台服务不匹配时警告，或从 shell 运行 `claude daemon status`4964* 检查 `/status`，它在其 Self-exec 条目中显示解析的启动命令，并在运行的后台服务不匹配时警告，或从 shell 运行 `claude daemon status`
4748* 在[设置](/docs/zh-CN/corporate-launcher#set-up-the-launcher)的 `env` 块中修复值后，使用 `claude daemon stop --any` 重启后台服务，以便下一次分派启动一个包装的4965* 在[设置](/docs/zh-CN/corporate-launcher#set-up-the-launcher)的 `env` 块中修复值后，使用 `claude daemon stop --any` 重启后台服务，以便下一次分派启动一个包装的后台服务
4749 4966
4750<h3 id="eunknown-when-starting-a-background-session">4967<h3 id="eunknown-when-starting-a-background-session">
4751 启动后台会话时 EUNKNOWN4968 启动后台会话时 EUNKNOWN
4767 4984
4768**要做什么：**4985**要做什么：**
4769 4986
4770* 如果消息读取 `Couldn't start the session`，升级到 v2.1.212 或更高版本。在早期版本上，您也可以在单独的终端中首先运行 `claude daemon run`，然后再次启动后台会话。该命令在终端的前景中运行后台服务，因此服务仅在该终端保持打开时持续。4987* 如果消息读取 `Couldn't start the session`，升级到 v2.1.212 或更高版本。在早期版本上，您也可以在单独的终端中首先运行 `claude daemon run`，然后再次启动后台会话。该命令在终端的前台运行后台服务，因此服务仅在该终端保持打开时持续。
4771* 如果 npm 安装正在替换二进制文件，等待它完成，然后再次启动后台会话4988* 如果 npm 安装正在替换二进制文件，等待它完成，然后再次启动后台会话
4772* 如果错误在 v2.1.212 或更高版本上出现，而没有 npm 安装运行，请要求您的 Windows 管理员在限制策略中允许 Claude Code 可执行文件4989* 如果错误在 v2.1.212 或更高版本上出现，而没有 npm 安装运行，请向您的 Windows 管理员确认是否有限制策略阻止了 Claude Code 可执行文件
4773* 如果关闭终端时后台服务停止，Claude Code 在没有 PowerShell 的情况下启动了它。安装 PowerShell 7，或要求您的管理员解除对 PowerShell 的阻止，以便服务可以超越终端。4990* 如果关闭终端时后台服务停止，Claude Code 在没有 PowerShell 的情况下启动了它。安装 PowerShell 7，或要求您的管理员解除对 PowerShell 的阻止，以便服务可以超越终端。
4774 4991
4775<h3 id="eacces-when-starting-a-background-session">4992<h3 id="eacces-when-starting-a-background-session">
4776 启动后台会话时 EACCES4993 启动后台会话时 EACCES
4777</h3>4994</h3>
4778 4995
4779Claude Code 无法运行其自己的二进制文件来启动[后台服务](/docs/zh-CN/agent-view#the-supervisor-process)，该服务托管后台会话。在 npm 安装上，这通常意味着 `npm install -g @anthropic-ai/claude-code` 在那一刻替换二进制文件，无论您运行它还是[自动更新程序](/docs/zh-CN/setup#auto-updates)运行。当您从[代理视图](/docs/zh-CN/agent-view)打开会话时，错误出现：4996Claude Code 无法运行其自己的二进制文件来启动[后台服务](/docs/zh-CN/agent-view#the-supervisor-process)，该服务托管后台会话。在 npm 安装上，这通常意味着 `npm install -g @anthropic-ai/claude-code` 在那一刻替换二进制文件，无论您运行它还是[自动更新程序](/docs/zh-CN/setup#auto-updates)运行。当您从 [Agent 视图](/docs/zh-CN/agent-view)打开会话时，错误出现：
4780 4997
4781```text theme={null}4998```text theme={null}
4782Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'4999Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'
4795**要做什么：**5012**要做什么：**
4796 5013
4797* 等待几秒钟，然后打开会话或再次分派。当消息说 Claude Code 正在更新时，在更新完成后重试。5014* 等待几秒钟，然后打开会话或再次分派。当消息说 Claude Code 正在更新时，在更新完成后重试。
4798* 如果错误在没有 npm 安装运行时持续，您的用户无法运行已安装的二进制文件。检查其权限及其目录的，或重新安装 Claude Code。5015* 如果错误在没有 npm 安装运行时持续，您的用户无法运行已安装的二进制文件。检查其权限及其目录的权限，或重新安装 Claude Code。
4799 5016
4800<h3 id="background-service-exited-before-it-became-reachable">5017<h3 id="background-service-exited-before-it-became-reachable">
4801 后台服务在变得可达之前退出5018 后台服务在变得可达之前退出
4802</h3>5019</h3>
4803 5020
4804Claude Code 启动的进程作为[后台服务](/docs/zh-CN/agent-view#the-supervisor-process)在变得可达之前退出，因此 Claude Code 无法打开您的会话。当服务在退出前打印错误时，括号中的原因给出退出代码或信号以及服务打印的第一行，它命名停止它的内容：5021Claude Code 作为[后台服务](/docs/zh-CN/agent-view#the-supervisor-process)启动的进程在接受连接之前退出，因此 Claude Code 无法打开您的会话。当服务在退出前打印错误时，括号中的原因给出退出码或信号以及服务打印的第一行，它命名停止它的内容：
4805 5022
4806```text theme={null}5023```text theme={null}
4807Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'5024Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'
4808```5025```
4809 5026
4810当您从[代理视图](/docs/zh-CN/agent-view)打开会话时，相同的原因跟随 `Couldn't start the background service —`。当服务在退出前没有打印任何内容时，消息说 `nothing on stderr`。5027当您从 [Agent 视图](/docs/zh-CN/agent-view)打开会话时，相同的原因跟随 `Couldn't start the background service —`。当服务在退出前没有打印任何内容时，消息说 `nothing on stderr`。
4811 5028
4812Claude Code 使用服务的错误行报告失败。在 v2.1.246 之前，失败仅在 45 秒等待后显示，作为 `background service did not become reachable within 45s`，没有服务的错误行。5029Claude Code 使用服务的错误行报告失败。在 v2.1.246 之前，失败仅在 45 秒等待后显示，作为 `background service did not become reachable within 45s`，没有服务的错误行。
4813 5030
4814两个引用的原因有已知的原因：5031两个引用的原因有已知的成因：
4815 5032
4816* `Error: claude native binary not installed.`：npm 安装在那一刻替换 Claude Code 二进制文件，因此服务运行了 npm 的占位符。在安装完成后重试；如果没有安装运行的行持续，[完成 npm 安装](/docs/zh-CN/troubleshoot-install#native-binary-not-found-after-npm-install)。在 v2.1.257 之前，macOS npm 自更新在安装窗口期间的每次启动时产生此失败。5033* `Error: claude native binary not installed.`：npm 安装在那一刻替换 Claude Code 二进制文件，因此服务运行了 npm 的占位符。在安装完成后重试；如果在没有安装运行时该行持续出现，[完成 npm 安装](/docs/zh-CN/troubleshoot-install#native-binary-not-found-after-npm-install)。在 v2.1.257 之前，macOS npm 自更新在安装窗口期间的每次启动时产生此失败。
4817* 在 Windows 上，`nothing on stderr` 和退出代码 1，每次启动：`daemon.lock` 命名一个 Claude Code 既无法发信号也无法证明已消失的进程，因此每个新服务得出结论另一个持有锁并退出。Claude Code 可以证明其编写者已消失的锁会自动替换，不会产生此失败。当失败在每次启动时重复时，删除 `~/.claude/daemon.lock`，然后打开会话或再次分派。在 v2.1.257 之前，这样的锁阻止了每次启动，直到您删除了文件。5034* 在 Windows 上，`nothing on stderr` 和退出码 1，每次启动：`daemon.lock` 命名一个 Claude Code 既无法发信号也无法证明已消失的进程，因此每个新服务得出结论另一个持有锁并退出。Claude Code 可以证明其编写者已消失的锁会自动替换，不会产生此失败。当失败在每次启动时重复时，删除 `~/.claude/daemon.lock`，然后打开会话或再次分派。在 v2.1.257 之前，这样的锁阻止了每次启动，直到您删除了文件。
4818 5035
4819**要做什么：**5036**要做什么：**
4820 5037
4825 启动后台会话时工作目录不再存在5042 启动后台会话时工作目录不再存在
4826</h3>5043</h3>
4827 5044
4828您尝试在不再存在的目录中启动[后台会话](/docs/zh-CN/agent-view)。Claude Code 不启动会话，消息命名缺失的目录：5045您启动[后台会话](/docs/zh-CN/agent-view)所在的目录在会话启动期间被删除。Claude Code 不启动会话，消息命名缺失的目录：
4829 5046
4830```text theme={null}5047```text theme={null}
4831Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)5048Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)
4832```5049```
4833 5050
4834在 v2.1.257 之前，会话似乎启动，然后在代理视图中显示为具有相同原因的失败行。5051在 v2.1.257 之前，会话似乎启动，然后在 Agent 视图中显示为具有相同原因的失败行。
4835 5052
4836在 v2.1.281 之前，当您启动会话之前目录已经消失时，此消息也出现。该情况报告[`could not be resolved on disk`](#workspace-not-trusted-when-dispatching-a-background-session)。5053在 v2.1.281 之前，当您启动会话之前目录已经消失时，此消息也出现。该情况报告 [`could not be resolved on disk`](#workspace-not-trusted-when-dispatching-a-background-session)。
4837 5054
4838**要做什么：**5055**要做什么：**
4839 5056
4843 分派后台会话时工作区不受信任5060 分派后台会话时工作区不受信任
4844</h3>5061</h3>
4845 5062
4846您在未[信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)的目录中启动或重启[后台会话](/docs/zh-CN/agent-view)，工作区信任对话无法出现以询问您。Claude Code 不启动会话：5063您在未[信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)的目录中启动或重启[后台会话](/docs/zh-CN/agent-view)，工作区信任对话框无法出现以询问您。Claude Code 不启动会话：
4847 5064
4848```text theme={null}5065```text theme={null}
4849Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.5066Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.
4850```5067```
4851 5068
4852从会话自己的目录中的终端，相同的命令显示信任对话，并在您接受后启动会话。此消息出现在无法显示对话的地方，例如在脚本中，或当您从不同于其自己的目录重启会话时。5069从会话自己的目录中的终端，相同的命令会改为显示信任对话框，并在您接受后启动会话。此消息出现在无法显示对话框的地方，例如在脚本中，或当您从不同于其自己的目录重启会话时。
4853 5070
4854两个变体命名不同的原因：5071两个变体命名不同的原因：
4855 5072
4856* **`The home directory is trusted one session at a time`**：会话的目录是您的主目录。Claude Code 从不保存主目录的信任，因此在早期会话中接受那里的对话不计数。5073* **`The home directory is trusted one session at a time`**：会话的目录是您的主目录。Claude Code 从不保存主目录的信任，因此在早期会话中在那里接受对话框不计数。
4857* **`<path> could not be resolved on disk`**：Claude Code 无法在磁盘上找到会话的目录。5074* **`<path> could not be resolved on disk`**：Claude Code 无法在磁盘上找到会话的目录。
4858 5075
5076在 v2.1.286 之前，在 Windows 上，如果某个您已信任的目录的信任记录是以不同字母大小写的路径保存的，此消息也可能在该目录中出现。请更新到 v2.1.286 或更高版本。
5077
4859**要做什么：**5078**要做什么：**
4860 5079
4861* 在消息命名的目录中运行 `claude` 并接受信任对话，然后再次运行该命令5080* 在消息命名的目录中运行 `claude` 并接受信任对话框，然后再次运行该命令
4862* 对于主目录消息，从您的主目录中的终端运行该命令，以便对话可以出现，或改为从项目目录启动会话5081* 对于主目录消息，从您的主目录中的终端运行该命令，以便对话框可以出现，或改为从项目目录启动会话
4863* 对于 `could not be resolved on disk` 消息，重新创建目录，或从存在的目录启动新会话5082* 对于 `could not be resolved on disk` 消息，重新创建目录，或从存在的目录启动新会话
4864 5083
4865<h2 id="wrapper-and-ide-errors">5084<h2 id="wrapper-and-ide-errors">
5067在 v2.1.236 之前，Claude Code 在此类错误后退出而不打印消息。5286在 v2.1.236 之前，Claude Code 在此类错误后退出而不打印消息。
5068 5287
5069<h3 id="agent-descriptions-are-over-the-15000-token-limit">5288<h3 id="agent-descriptions-are-over-the-15000-token-limit">
5070 代理描述超过 15.0k 令牌限制5289 Agent 描述超过 15.0k token 限制
5071</h3>5290</h3>
5072 5291
5073Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上。您的[子代理](/docs/zh-CN/sub-agents)（除了内置代理）的组合描述超过 Claude Code 估计的 15,000 个令牌。每个代理计算其名称加上其 `description` frontmatter。Claude Code 加载每个代理，无论总数是否超过限制，因此警告不会改变加载的内容。5292Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上。您的[子代理](/docs/zh-CN/sub-agents)（内置子代理除外）的组合描述超过 Claude Code 估计的 15,000 个 token。每个 Agent 计算其名称加上其 `description` frontmatter。Claude Code 加载每个 Agent，无论总数是否超过限制，因此警告不会改变加载的内容。
5074 5293
5075```text theme={null}5294```text theme={null}
5076Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/5295Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/
5078 5297
5079**要做什么：**5298**要做什么：**
5080 5299
5081* 缩短您的代理文件的 `description` frontmatter，或要求 Claude 为您修剪它们。5300* 缩短您的 Agent 文件的 `description` frontmatter，或要求 Claude 为您修剪它们。
5082* 删除您不再使用的代理文件。5301* 删除您不再使用的 Agent 文件。
5083 5302
5084<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">5303<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">
5085 技能、命令或工作流未被加载，因为其名称是保留的5304 skill、命令或工作流未被加载，因为其名称是保留的
5086</h3>5305</h3>
5087 5306
5088技能文件夹、frontmatter `name`、`.claude/commands/` 中的文件或子文件夹，或[保存的工作流](/docs/zh-CN/workflows#save-the-workflow-for-reuse)使用名称 `anthropic-skills` 或以 `anthropic-skills:` 开头的名称。Claude Code [为从 claude.ai 同步的技能保留该名称](/docs/zh-CN/skills#names-reserved-for-synced-skills)，不加载该项。5307skill 文件夹、frontmatter `name`、`.claude/commands/` 中的文件或子文件夹，或[保存的工作流](/docs/zh-CN/workflows#save-the-workflow-for-reuse)使用名称 `anthropic-skills` 或以 `anthropic-skills:` 开头的名称。Claude Code [为从 claude.ai 同步的 skill 保留该名称](/docs/zh-CN/skills#names-reserved-for-synced-skills)，不加载该项。
5089 5308
5090Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上：5309Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上：
5091 5310
5093Not loaded: rename .claude/skills/anthropic-skills, then restart — its name uses "anthropic-skills", a name reserved for the skills synced from your claude.ai account5312Not loaded: rename .claude/skills/anthropic-skills, then restart — its name uses "anthropic-skills", a name reserved for the skills synced from your claude.ai account
5094```5313```
5095 5314
5096通知命名它拒绝的第一项：要重命名的文件夹或文件、要编辑的 `name:` 行，或要重命名的工作流。当拒绝多个项时，通知以计数结尾，例如 `· 2 more`，[调试日志](/docs/zh-CN/debug-your-config)命名每一个。5315通知命名它拒绝的第一项需要更改的内容：要重命名的文件夹或文件、要编辑的 `name:` 行，或要重命名的工作流。当拒绝多个项时，通知以计数结尾，例如 `· 2 more`，[调试日志](/docs/zh-CN/debug-your-config)命名每一个。
5097 5316
5098**要做什么：**5317**要做什么：**
5099 5318
5100* 重命名通知命名的项，或编辑它指向的 `name:` 行，然后重启会话。5319* 重命名通知命名的项，或编辑它指向的 `name:` 行，然后重启会话。
5101 5320
5102在 v2.1.282 之前，Claude Code 加载具有这些名称的技能和命令。5321在 v2.1.282 之前，Claude Code 加载具有这些名称的 skill 和命令。
5103 5322
5104<h3 id="workspace-has-not-been-trusted">5323<h3 id="workspace-has-not-been-trusted">
5105 工作区尚未被信任5324 工作区尚未被信任
5115 5334
5116* 在目录中运行 `claude` 并接受信任对话框。[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)说明该接受涵盖的文件夹。5335* 在目录中运行 `claude` 并接受信任对话框。[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)说明该接受涵盖的文件夹。
5117* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 不显示对话框。使用消息打印的确切 `projects` 键在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。5336* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 不显示对话框。使用消息打印的确切 `projects` 键在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。
5118* 如果消息命名 `.claude/settings.local.json` 并且您在 git 存储库外或主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 至 2.1.199 在这些工作区中将您自己的 `.claude/settings.local.json` 视为存储库提供的。在 v2.1.207 及更高版本上，如果您尚未信任该文件夹，在 git 存储库外更新是不够的：确定文件夹不在存储库内会运行 git，Claude Code 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他[配置主目录](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)是豁免的，不等待对话框。请参阅[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。5337* 如果消息命名 `.claude/settings.local.json` 并且您在 git 仓库外或主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 至 2.1.199 在这些工作区中将您自己的 `.claude/settings.local.json` 视为仓库提供的。在 v2.1.207 及更高版本上，如果您尚未信任该文件夹，在 git 仓库外仅更新是不够的：确定文件夹不在仓库内会运行 git，Claude Code 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他[配置主目录](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)是豁免的，不等待对话框。请参阅[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。
5119 5338
5120<h3 id="working-directory-is-a-network-path">5339<h3 id="working-directory-is-a-network-path">
5121 工作目录是网络路径5340 工作目录是网络路径
5122</h3>5341</h3>
5123 5342
5124Claude Code 不将网络路径添加为工作目录。查找网络路径可以联系它命名的主机，在 Windows 上该联系可以向主机发送您的凭据，因此 Claude Code 拒绝该路径而不查找它。当您使用此类路径运行 `/add-dir` 时，或作为启动时的警告，您会看到此消息。当它在启动时出现时，Claude Code 启动时不包含该目录。5343Claude Code 不将网络路径添加为工作目录。查找网络路径可能会联系它命名的主机，在 Windows 上该联系可能会向主机发送您的凭据，因此 Claude Code 拒绝该路径而不查找它。当您使用此类路径运行 `/add-dir` 时，或作为启动时的警告，您会看到此消息。当它在启动时出现时，Claude Code 启动时不包含该目录。
5125 5344
5126```text theme={null}5345```text theme={null}
5127\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).5346\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).
5131 5350
5132* UNC 共享，例如 `\\server\share`5351* UNC 共享，例如 `\\server\share`
5133* 自动挂载路径，例如 `/net/<host>`，除非您从该主机的自动挂载下的目录启动了 Claude Code5352* 自动挂载路径，例如 `/net/<host>`，除非您从该主机的自动挂载下的目录启动了 Claude Code
5134* 通过符号链接或连接到达网络位置的本地路径5353* 通过符号链接或连接点到达网络位置的本地路径
5135 5354
5136映射的驱动器号和 `\\wsl$` 路径不计为网络路径。5355映射的驱动器号和 `\\wsl$` 路径不计为网络路径。
5137 5356
5149 5368
5150您的会话符合[服务器托管设置](/docs/zh-CN/server-managed-settings)的条件，但 Claude Code 无法获取它们或无法应用服务器返回的内容，因此在交互式会话中显示此警告。5369您的会话符合[服务器托管设置](/docs/zh-CN/server-managed-settings)的条件，但 Claude Code 无法获取它们或无法应用服务器返回的内容，因此在交互式会话中显示此警告。
5151 5370
5152括号中的原因命名失败的内容，例如 `network error`、`request timed out` 或 `authentication rejected (401)`。原因 `no setting in the server response could be applied as written` 意味着服务器已应答，但它返回的设置都没有通过[验证](/docs/zh-CN/server-managed-settings#invalid-entries-in-delivered-settings)。在 v2.1.282 之前，此原因读取 `server returned invalid settings`。5371括号中的原因命名失败的内容，例如 `network error`、`request timed out` 或 `authentication rejected (401)`。原因 `no setting in the server response could be applied as written` 意味着服务器已应答，但它返回的设置都没有通过[验证](/docs/zh-CN/server-managed-settings#invalid-entries-in-delivered-settings)。在 v2.1.282 之前，此原因显示为 `server returned invalid settings`。
5153 5372
5154该行的其余部分说明会话运行的策略：5373该行的其余部分说明会话运行的策略：
5155 5374
5156* **从较早的成功获取缓存的设置**：Claude Code 在该缓存策略上运行会话，除了[扣留的环境变量](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)，行读取 `using cached policy`。5375* **从较早的成功获取缓存的设置**：Claude Code 在该缓存策略上运行会话，但[扣留的环境变量](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)除外，该行显示 `using cached policy`。
5157* **无缓存**：Claude Code 在没有服务器托管设置的情况下运行会话，行读取 `no remote policy applied`。5376* **无缓存**：Claude Code 在没有服务器托管设置的情况下运行会话，该行显示 `no remote policy applied`。
5158 5377
5159**要做什么：**5378**要做什么：**
5160 5379
5176 5395
5177**要做什么：**5396**要做什么：**
5178 5397
5179* 再次启动 Claude Code 并批准对话框以在您的组织设置下继续。拒绝的对话框不被记住，因此在下一次启动时再次出现。5398* 再次启动 Claude Code 并批准对话框以在您的组织设置下继续。拒绝的对话框不会被记住，因此在下一次启动时会再次出现。
5180* 如果您对对话框列出的设置不确定，请在批准前询问维护您的组织托管设置的人5399* 如果您对对话框列出的设置不确定，请在批准前询问维护您的组织托管设置的人
5181 5400
5182<h3 id="managed-settings-block-the-default-model">5401<h3 id="managed-settings-block-the-default-model">
5183 托管设置阻止默认模型5402 托管设置阻止默认模型
5184</h3>5403</h3>
5185 5404
5186您的组织的[托管设置](/docs/zh-CN/managed-settings)阻止默认选项解析到的模型以及它可以降级到的每个模型。将在默认选项上启动的会话在启动时退出，而不是运行被阻止的模型。您看到的消息取决于阻止它的设置。当 [`deniedModels`](/docs/zh-CN/model-config#block-specific-models-or-versions) 列表阻止它时，消息读取：5405您的组织的[托管设置](/docs/zh-CN/managed-settings)阻止默认选项解析到的模型以及它可以降级到的每个模型。将在默认选项上启动的会话在启动时退出，而不是运行被阻止的模型。您看到的消息取决于阻止它的设置。当 [`deniedModels`](/docs/zh-CN/model-config#block-specific-models-or-versions) 列表阻止它时，消息显示为：
5187 5406
5188```text theme={null}5407```text theme={null}
5189Claude Code can't start: your organization's managed settings block the default model (claude-opus-5-5) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".5408Claude Code can't start: your organization's managed settings block the default model (claude-opus-5-5) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".
5190```5409```
5191 5410
5192当 `availableModels` 列表与 [`availableModelsMatch`](/docs/zh-CN/settings-reference#availablemodelsmatch) 设置为 `"exact"` 省略它时，消息读取：5411当 [`availableModelsMatch`](/docs/zh-CN/settings-reference#availablemodelsmatch) 设置为 `"exact"` 的 `availableModels` 列表省略它时，消息显示为：
5193 5412
5194```text theme={null}5413```text theme={null}
5195Claude Code can't start: your organization allows only the models listed in "availableModels", and none of them can be used as the default model (claude-opus-5-5 isn't listed). Ask your administrator to update "availableModels".5414Claude Code can't start: your organization allows only the models listed in "availableModels", and none of them can be used as the default model (claude-opus-5-5 isn't listed). Ask your administrator to update "availableModels".
5197 5416
5198**要做什么：**5417**要做什么：**
5199 5418
5200* 如果您管理设置，请将您的用户可以运行的模型添加到 `availableModels`，或缩小阻止每个回退的 `deniedModels` 条目。[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)描述默认选项如何降级5419* 如果您管理设置，请将您的用户可以运行的模型添加到 `availableModels`，或缩小阻止每个备用模型的 `deniedModels` 条目。[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)描述默认选项如何降级
5201* 如果您不管理它们，请将消息发送给您的管理员。您自己的设置文件无法扩大托管的 `availableModels` 或 `deniedModels` 列表5420* 如果您不管理它们，请将消息发送给您的管理员。您自己的设置文件无法扩大托管的 `availableModels` 或 `deniedModels` 列表
5202 5421
5203<h3 id="managed-settings-dont-allow-this-api-provider">5422<h3 id="managed-settings-dont-allow-this-api-provider">
5204 托管设置不允许此 API 提供商5423 托管设置不允许此 API 提供商
5205</h3>5424</h3>
5206 5425
5207您的组织的[托管设置](/docs/zh-CN/managed-settings)设置了 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 列表，会话的 API 提供商不在其上，或会话使用的端点不是按该条目要求的方式固定的。Claude Code 在启动前、登录前或会话下次联系 API 时拒绝。消息以允许的提供商开头：5426您的组织的[托管设置](/docs/zh-CN/managed-settings)设置了 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 列表，会话的 API 提供商不在其上，或会话使用的端点不是按该条目要求的方式固定的。Claude Code 在启动时、登录前或会话下次联系 API 时拒绝。消息以允许的提供商开头：
5208 5427
5209```text theme={null}5428```text theme={null}
5210Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.5429Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.
5211```5430```
5212 5431
5213当列表为空时，消息改为读取：5432当列表为空时，消息改为显示：
5214 5433
5215```text theme={null}5434```text theme={null}
5216Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.5435Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.
5217```5436```
5218 5437
5219当每个条目都无法识别时，括号读取 `(allowedProviders lists only unrecognized entries)` 代替。5438当每个条目都无法识别时，括号内容改为 `(allowedProviders lists only unrecognized entries)`。
5220 5439
5221**要做什么：**5440**要做什么：**
5222 5441
5223* 按照消息的 `To continue:` 步骤进行5442* 按照消息的 `To continue:` 步骤进行
5224* 如果您管理设置，消息的以 `Admins:` 开头的行命名要添加的条目或要固定的值，[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 条目说明哪个源的 `env` 块可以固定它5443* 如果您管理设置，消息中以 `Admins:` 开头的行命名要添加的条目或要固定的值，[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 条目说明哪个源的 `env` 块可以固定它
5225 5444
5226<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5445<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">
5227 MCP 服务器被企业托管策略阻止5446 MCP 服务器被企业托管策略阻止
5228</h3>5447</h3>
5229 5448
5230您在 `/mcp` 中的服务器上选择了**重新连接**，或在那里重新打开了禁用的服务器，[限制 MCP 服务器](/docs/zh-CN/managed-mcp)的设置阻止了该服务器。Claude Code 拒绝连接它并显示：5449您在 `/mcp` 中的服务器上选择了**重新连接**，或在那里重新打开了禁用的服务器，而[限制 MCP 服务器](/docs/zh-CN/managed-mcp)的设置阻止了该服务器。Claude Code 拒绝连接它并显示：
5231 5450
5232```text theme={null}5451```text theme={null}
5233MCP server <name> is blocked by enterprise managed policy5452MCP server <name> is blocked by enterprise managed policy
5234```5453```
5235 5454
5236这些设置中的任何一个都可以产生消息：5455这些设置中的任何一个都可以产生该消息：
5237 5456
5238* 与服务器匹配的 [`deniedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 条目，包括您自己的 `~/.claude/settings.json` 或项目的 `.claude/settings.json` 中的条目5457* 与服务器匹配的 [`deniedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 条目，包括您自己的 `~/.claude/settings.json` 或项目的 `.claude/settings.json` 中的条目
5239* 服务器不匹配的 [`allowedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 列表5458* 服务器不匹配的 [`allowedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 列表
5240* [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) 与 `mcp` 锁定，这阻止在 `~/.claude.json` 和 `.mcp.json` 中配置的服务器5459* 锁定了 `mcp` 的 [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization)，这会阻止在 `~/.claude.json` 和 `.mcp.json` 中配置的服务器
5241* [`disableClaudeAiConnectors`](/docs/zh-CN/mcp#disable-claude-ai-connectors)，当服务器是 claude.ai 连接器时5460* [`disableClaudeAiConnectors`](/docs/zh-CN/mcp#disable-claude-ai-connectors)，当服务器是 claude.ai 连接器时
5242 5461
5243**要做什么：**5462**要做什么：**
5244 5463
5245* 检查您自己的用户和项目设置文件中的这些设置之一，并更改或删除它5464* 检查您自己的用户和项目设置文件中是否有这些设置之一，并更改或删除它
5246* 如果您自己的设置都不能解释该阻止，请询问您的管理员哪个托管设置阻止了服务器5465* 如果您自己的设置都不能解释该阻止，请询问您的管理员哪个托管设置阻止了服务器
5247 5466
5248在 v2.1.257 之前，`/mcp` 中的**重新连接**和重新启用可以连接中途策略更新阻止的服务器。5467在 v2.1.257 之前，`/mcp` 中的**重新连接**和重新启用可以连接被会话中途策略更新阻止的服务器。
5249 5468
5250<h3 id="managed-settings-document-could-not-be-parsed">5469<h3 id="managed-settings-document-could-not-be-parsed">
5251 托管设置文档无法解析5470 托管设置文档无法解析
5252</h3>5471</h3>
5253 5472
5254您的组织部署[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的文档存在但无法解析为 JSON 对象，因此 Claude Code 在启动时以代码 1 退出，而不是在没有文档携带的策略的情况下运行。该行在消息前命名失败的源：5473您的组织部署了[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的文档存在但无法解析为 JSON 对象，因此 Claude Code 在启动时以退出码 1 退出，而不是在没有该文档所携带策略的情况下运行。该行在消息前命名失败的源：
5255 5474
5256```text theme={null}5475```text theme={null}
5257/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.5476/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.
5260源是以下之一：5479源是以下之一：
5261 5480
5262* `managed-settings.json` 文件的路径或 `managed-settings.d` 下的放入文件5481* `managed-settings.json` 文件的路径或 `managed-settings.d` 下的放入文件
5263* macOS 托管首选项配置文件、`per-user managed preferences` 或 `device-level managed preferences`5482* macOS 托管首选项配置文件，`per-user managed preferences` 或 `device-level managed preferences`
5264* Windows 注册表值、`Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`5483* Windows 注册表值，`Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`
5265 5484
5266[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)列出了使每个源无法解析的原因。5485[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)列出了使每个源无法解析的原因。
5267 5486
5268Claude Code 拒绝启动，即使另一个管理员源提供有效策略。您在交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view)和大多数子命令（包括 `claude doctor`）中看到此错误。拒绝故意失败关闭：Claude Code 无法解析的文档中的设置无法被强制执行，启动时不运行会话会在没有组织控制的情况下运行。5487即使另一个管理员源提供了有效策略，Claude Code 也会拒绝启动。您在交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view)和大多数子命令（包括 `claude doctor`）中都会看到此错误。该拒绝有意采用失败关闭：Claude Code 无法解析的文档中的设置无法被强制执行，强行启动会在没有组织控制的情况下运行会话。
5269 5488
5270可解析文档中的架构问题不会产生此错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖 Claude Code 对其所做的操作。5489可解析文档中的 schema 问题不会产生此错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖 Claude Code 对此类问题的处理方式。
5271 5490
5272当 `managed-settings.d/` 目录存在但无法列出时，Claude Code 报告 `Managed settings drop-in directory could not be read:` 后跟基础错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖读取失败在启动时退出的时间。5491当 `managed-settings.d/` 目录存在但无法列出时，Claude Code 改为报告 `Managed settings drop-in directory could not be read:`，后跟底层错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖读取失败何时会在启动时退出。
5273 5492
5274**要做什么：**5493**要做什么：**
5275 5494
5276* 如果您管理计算机，修复命名的文档使其解析为 JSON 对象，或删除文件、配置文件或注册表值。空的 `managed-settings.json` 计为 `{}` 并不阻止启动。5495* 如果您管理计算机，请修复命名的文档使其解析为 JSON 对象，或删除文件、配置文件或注册表值。空的 `managed-settings.json` 计为 `{}`，不会阻止启动。
5277* 如果您不管理，请要求您的管理员修复部署的文档。您自己的设置文件中的任何内容都不会导致或清除此错误。5496* 如果您不管理，请要求您的管理员修复部署的文档。您自己的设置文件中的任何内容都不会导致或清除此错误。
5278 5497
5279<h3 id="unable-to-read-managed-policy-settings">5498<h3 id="unable-to-read-managed-policy-settings">
5280 无法读取托管策略设置5499 无法读取托管策略设置
5281</h3>5500</h3>
5282 5501
5283您的组织部署[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的源存在但无法读取，原因例如 I/O 错误而不是操作系统拒绝读取。没有其他管理员源提供策略，Claude Code 在启动时退出，而不是在没有源可能携带的策略的情况下运行：5502您的组织部署了[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的源存在但无法读取，原因例如 I/O 错误，而不是操作系统拒绝读取。在没有其他管理员源提供策略的情况下，Claude Code 在启动时退出，而不是在没有该源可能携带的策略的情况下运行：
5284 5503
5285```text theme={null}5504```text theme={null}
5286Unable to read managed policy settings.5505Unable to read managed policy settings.
5290Detail: <source>: <reason>5509Detail: <source>: <reason>
5291```5510```
5292 5511
5293在相同的状态下，登录流、来自已运行的会话的 API 请求和 [`claude gateway`](/docs/zh-CN/claude-apps-gateway) 服务器被拒绝，其中第一行的变体命名 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders)。5512在相同的状态下，登录流程、来自已运行会话的 API 请求和 [`claude gateway`](/docs/zh-CN/claude-apps-gateway) 服务器会被拒绝，并显示第一行的一个变体，其中命名 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders)。
5294 5513
5295操作系统拒绝的读取，例如在仅限 root 的文件上，不会产生此退出：[会话启动时不使用该源的策略](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)。对于无法解析的源，Claude Code 以[不同的消息命名源](#managed-settings-document-could-not-be-parsed)退出。5514操作系统拒绝的读取（例如对仅限 root 的文件）不会导致此退出：[会话启动时不使用该源的策略](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)。对于无法解析的源，Claude Code 以[命名该源的不同消息](#managed-settings-document-could-not-be-parsed)退出。
5296 5515
5297**要做什么：**5516**要做什么：**
5298 5517
5299* 如果您管理计算机，修复 `Detail:` 行命名的问题，以便部署的源可以被读取，或删除源5518* 如果您管理计算机，请修复 `Detail:` 行命名的问题，以便部署的源可以被读取，或删除该源
5300* 如果您不管理，请将消息发送给您的管理员。您自己的设置文件中的任何内容都不会导致或清除此错误5519* 如果您不管理，请将消息发送给您的管理员。您自己的设置文件中的任何内容都不会导致或清除此错误
5301 5520
5302在 v2.1.285 之前，仅使用 claude.ai 或 Claude Console 凭据登录的会话以此消息退出，操作系统拒绝的读取也产生了它。5521在 v2.1.285 之前，仅使用 claude.ai 或 Claude Console 凭据登录的会话以此消息退出，并且操作系统拒绝的读取也会产生它。
5303 5522
5304<h3 id="otelheadershelper-failed">5523<h3 id="otelheadershelper-failed">
5305 otelHeadersHelper 失败5524 otelHeadersHelper 失败
5307 5526
5308当 [`otelHeadersHelper`](/docs/zh-CN/settings-reference#otelheadershelper) 脚本失败或打印不符合[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)的输出时，Claude Code 将此警告显示为终端界面中的通知，每个交互式会话一次。5527当 [`otelHeadersHelper`](/docs/zh-CN/settings-reference#otelheadershelper) 脚本失败或打印不符合[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)的输出时，Claude Code 将此警告显示为终端界面中的通知，每个交互式会话一次。
5309 5528
5310当脚本继续失败时，导出失败，您的遥测后端从会话中接收不到任何内容。5529当脚本持续失败时，导出失败，您的遥测后端从会话中接收不到任何内容。
5311 5530
5312`See /status:` 后的文本说明失败的内容，例如脚本的退出代码后跟其错误输出：5531`See /status:` 后的文本说明失败的内容，例如脚本的退出码后跟其错误输出：
5313 5532
5314```text theme={null}5533```text theme={null}
5315otelHeadersHelper failed; telemetry is not being exported. See /status: exited 1: token service unreachable5534otelHeadersHelper failed; telemetry is not being exported. See /status: exited 1: token service unreachable
5318**要做什么：**5537**要做什么：**
5319 5538
5320* 运行 `/status` 以读取失败详情。5539* 运行 `/status` 以读取失败详情。
5321* 修复脚本使其在 30 秒内退出 0 并在 stdout 上打印字符串标头值的 JSON 对象。请参阅[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)。5540* 修复脚本使其在 30 秒内以 0 退出，并在 stdout 上打印由字符串标头值组成的 JSON 对象。请参阅[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)。
5322* 如果您的组织通过[托管设置](/docs/zh-CN/managed-settings)部署脚本，请要求维护它们的人修复它。5541* 如果您的组织通过[托管设置](/docs/zh-CN/managed-settings)部署脚本，请要求维护它们的人修复它。
5323 5542
5324在[非交互模式](/docs/zh-CN/headless)中使用 `-p`，相同的失败在 stderr 上显示为 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>`。5543在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 时，相同的失败改为在 stderr 上显示为 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>`。
5325 5544
5326<h3 id="headershelper-not-run">5545<h3 id="headershelper-not-run">
5327 headersHelper 未运行5546 headersHelper 未运行
5328</h3>5547</h3>
5329 5548
5330Claude Code 仅使用 MCP 服务器的静态 `headers` 连接了它，并跳过了服务器的 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)，因为助手是 shell 命令，文件夹没有保存的信任。当您手动在 `~/.claude.json` 中设置其条目时，或在主目录外，当您在交互式会话中为其接受信任对话框时，文件夹获得保存的信任。请参阅[在 headersHelper 运行前信任文件夹](/docs/zh-CN/mcp#trust-a-folder-before-its-headershelper-runs)了解此检查适用于哪些服务器。5549Claude Code 仅使用 MCP 服务器的静态 `headers` 连接了它，并跳过了服务器的 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)，因为该助手是 shell 命令，而该文件夹没有保存的信任。当您手动在 `~/.claude.json` 中设置其条目时，或在主目录外，当您在交互式会话中为其接受信任对话框时，文件夹获得保存的信任。请参阅[在 headersHelper 运行前信任文件夹](/docs/zh-CN/mcp#trust-a-folder-before-its-headershelper-runs)了解此检查适用于哪些服务器。
5331 5550
5332Claude Code 仅在[非交互模式](/docs/zh-CN/headless)中写入此行，每个服务器一次。在交互式会话中，它将相同的拒绝写入调试日志。5551Claude Code 仅在[非交互模式](/docs/zh-CN/headless)中写入此行，每个服务器一次。在交互式会话中，它改为将相同的拒绝写入调试日志。
5333 5552
5334```text theme={null}5553```text theme={null}
5335MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.5554MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.
5336```5555```
5337 5556
5338消息打印的 `projects` 键是文件夹[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)说明 Claude Code 在其上键入信任的。为父文件夹接受信任对话框不满足检查，`-p` 或 SDK 会话也不满足。5557消息打印的 `projects` 键就是[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)中说明的 Claude Code 用来记录信任的文件夹。为父文件夹接受信任对话框不满足该检查，`-p` 或 SDK 会话也不满足。
5339 5558
5340**要做什么：**5559**要做什么：**
5341 5560
5347 格式错误的 Tool(content) 规则5566 格式错误的 Tool(content) 规则
5348</h3>5567</h3>
5349 5568
5350您的一个设置文件中的[权限规则](/docs/zh-CN/permissions#permission-rule-syntax)没有 `Tool` 或 `Tool(content)` 的形状，例如因为文本跟在右括号后或其中一个括号缺失。Claude Code 跳过规则，当交互式会话启动时在无效设置对话框中列出它，以及在 [`claude doctor`](/docs/zh-CN/debug-your-config#check-resolved-settings) 输出中：5569您的某个设置文件中的[权限规则](/docs/zh-CN/permissions#permission-rule-syntax)不具有 `Tool` 或 `Tool(content)` 的形式，例如因为右括号后跟有文本或缺少其中一个括号。Claude Code 跳过该规则，并在交互式会话启动时的无效设置对话框中以及 [`claude doctor`](/docs/zh-CN/debug-your-config#check-resolved-settings) 输出中列出它：
5351 5570
5352```text theme={null}5571```text theme={null}
5353Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal5572Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal
5356**要做什么：**5575**要做什么：**
5357 5576
5358* 在消息列出的设置文件中，重写规则使其在其右括号处结束，例如用 `Bash(ls *)` 代替 `Bash(ls) x`5577* 在消息列出的设置文件中，重写规则使其在其右括号处结束，例如用 `Bash(ls *)` 代替 `Bash(ls) x`
5359* 将内容内的括号保留原样。它们是字面的，因此诸如 `Edit(./Finance (2024)/**)` 的规则在没有转义的情况下是有效的5578* 将内容内的括号保留原样。它们是字面量，因此诸如 `Edit(./Finance (2024)/**)` 的规则无需转义即有效
5360 5579
5361在 v2.1.260 之前，Claude Code 将具有不匹配括号的规则报告为 `Mismatched parentheses`。5580在 v2.1.260 之前，Claude Code 将具有不匹配括号的规则报告为 `Mismatched parentheses`。
5362 5581
5364 不匹配文件权限检查5583 不匹配文件权限检查
5365</h3>5584</h3>
5366 5585
5367Claude Code 在您的[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools`、`--disallowedTools` 或 `--settings` 标志值中找到了 `Write`、`NotebookEdit`、`MultiEdit` 或 `Glob` [权限规则](/docs/zh-CN/permissions#read-and-edit)，其中包含路径。它仅针对 `Edit` 和 `Read` 规则检查文件权限，因此它从不查询命名其他文件工具之一的路径规则。它保留规则并不改变其他任何内容；警告命名规则、其括号中的源和要写入的替换：5586Claude Code 在您的某个[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools`、`--disallowedTools` 或 `--settings` 标志值中找到了带有路径的 `Write`、`NotebookEdit`、`MultiEdit` 或 `Glob` [权限规则](/docs/zh-CN/permissions#read-and-edit)。它仅针对 `Edit` 和 `Read` 规则检查文件权限，因此从不查询命名其他文件工具之一的路径规则。它保留该规则且不改变其他任何内容；警告命名该规则、括号中的来源以及要写入的替换内容：
5368 5587
5369```text theme={null}5588```text theme={null}
5370Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).5589Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).
5373**要做什么：**5592**要做什么：**
5374 5593
5375* 将 `Write(path)`、`NotebookEdit(path)` 和旧版 `MultiEdit(path)` 规则替换为 `Edit(path)`。`Edit` 规则涵盖所有文件编辑工具。5594* 将 `Write(path)`、`NotebookEdit(path)` 和旧版 `MultiEdit(path)` 规则替换为 `Edit(path)`。`Edit` 规则涵盖所有文件编辑工具。
5376* 除了在 `--allowedTools` 中，Claude Code 接受 `Glob` 规则而不警告，将 `Glob(path)` 规则替换为 `Read(path)`。5595* 除了在 `--allowedTools` 中（Claude Code 接受 `Glob` 规则而不警告），将 `Glob(path)` 规则替换为 `Read(path)`。
5377* 在警告括号中命名的源处修复规则：设置文件路径，或 `--allowed-tools` 和 `--disallowed-tools` 的标志本身。不存在于磁盘上的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。修复您传递给该标志的 JSON。5596* 在警告括号中命名的来源处修复规则：设置文件路径，或对于 `--allowed-tools` 和 `--disallowed-tools` 则是标志本身。磁盘上不存在的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。请修复您传递给该标志的 JSON。
5378* 将诸如 `Write` 或 `Glob` 的裸工具名称规则保留原样。Claude Code 在[工具级别](/docs/zh-CN/permissions#match-all-uses-of-a-tool)匹配它们，不对它们发出警告。5597* 将诸如 `Write` 或 `Glob` 的裸工具名称规则保留原样。Claude Code 在[工具级别](/docs/zh-CN/permissions#match-all-uses-of-a-tool)匹配它们，不对它们发出警告。
5379* 如果源读取 `managed policy settings`，将警告转发给维护您的托管设置的人，因为您无法自己清除它。5598* 如果来源显示为 `managed policy settings`，请将警告转发给维护您的托管设置的人，因为您无法自己清除它。
5380 5599
5381在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json`，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取输出保持干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.210 之前，Claude Code 接受这些规则而不警告。5600在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json` 时，Claude Code 将警告写入调试日志而不是 stderr，以保持机器读取的输出干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.210 之前，Claude Code 接受这些规则而不警告。
5382 5601
5383<h3 id="has-a-wildcard-before-the-rest-of-the-command">5602<h3 id="has-a-wildcard-before-the-rest-of-the-command">
5384 在命令的其余部分之前有通配符5603 在命令的其余部分之前有通配符
5385</h3>5604</h3>
5386 5605
5387Claude Code 找到了一个 `Bash` 允许规则，其 `*` 在后来的单词之前，该单词确定它是哪个命令，例如 `Bash(git * main)` 或 `Bash(git -C * status *)`，在您的[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools` 或 `--settings` 标志值中。`*` 匹配任何文本，包括在该位置插入的选项：`Bash(git * main)` 也批准 `git -c core.fsmonitor=<script> diff main`，其中 `-c` 使 git 运行命令命名的程序。[通配符模式](/docs/zh-CN/permissions#wildcard-patterns)显示匹配规则。5606Claude Code 在您的某个[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools` 或 `--settings` 标志值中找到了一个 `Bash` 允许规则，其 `*` 出现在决定命令类型的后续单词之前，例如 `Bash(git * main)` 或 `Bash(git -C * status *)`。`*` 匹配任何文本，包括在该位置插入的选项：`Bash(git * main)` 也会批准 `git -c core.fsmonitor=<script> diff main`，其中 `-c` 会使 git 运行命令所命名的程序。[通配符模式](/docs/zh-CN/permissions#wildcard-patterns)显示匹配规则。
5388 5607
5389警告存在是为了让您缩小通配符比您打算的更宽的规则。Claude Code 保留规则并不改变它如何匹配；警告命名规则及其括号中的源：5608此警告的目的是让您缩小通配符范围超出预期的规则。Claude Code 保留该规则且不改变其匹配方式；警告命名该规则及括号中的来源：
5390 5609
5391```text theme={null}5610```text theme={null}
5392Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).5611Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).
5394 5613
5395**要做什么：**5614**要做什么：**
5396 5615
5397* 将子命令前的 `*` 替换为您的确切值：用 `Bash(git checkout main)` 代替 `Bash(git * main)`。5616* 将子命令前的 `*` 替换为您想要的确切值：用 `Bash(git checkout main)` 代替 `Bash(git * main)`。
5398* 将每个 `*` 移到子命令后：用 `Bash(git status *)` 代替 `Bash(git -C * status *)`。为您想允许的每个子命令写一个规则。5617* 将每个 `*` 移到子命令后：用 `Bash(git status *)` 代替 `Bash(git -C * status *)`。为您想允许的每个子命令写一条规则。
5399* 在警告括号中命名的源处修复规则：设置文件路径，或 `--allowed-tools` 标志本身。不存在于磁盘上的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。修复您传递给该标志的 JSON。5618* 在警告括号中命名的来源处修复规则：设置文件路径，或 `--allowed-tools` 标志本身。磁盘上不存在的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。请修复您传递给该标志的 JSON。
5400* 如果源读取 `managed policy settings`，将警告转发给维护您的托管设置的人，因为您无法自己清除它。5619* 如果来源显示为 `managed policy settings`，请将警告转发给维护您的托管设置的人，因为您无法自己清除它。
5401
5402Claude Code 不对具有相同形状的拒绝和询问规则发出警告：它拒绝或提示它们匹配的额外命令，而不是批准它们。它也不对子命令在第一个 `*` 之前的规则发出警告，例如 `Bash(git commit *)`，或规则中除了选项之外没有其他单词跟在 `*` 后的规则，例如 `Bash(git *)`，或关于 `:*` 前缀规则的规则，例如 `Bash(git:*)`。
5403 5620
5404在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json`，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取输出保持干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.246 之前，Claude Code 接受这些规则而不警告。5621在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json` 时，Claude Code 将警告写入调试日志而不是 stderr，以保持机器读取的输出干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.246 之前，Claude Code 接受这些规则而不警告。
5405 5622
5406<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5623<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">
5407 crossSessionInbound 必须是 accept、hold 或 refuse 之一5624 crossSessionInbound 必须是 accept、hold 或 refuse 之一
5408</h3>5625</h3>
5409 5626
5410设置文件将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 Claude Code 不识别的值，例如拼写错误 `"reject"`。警告的第二句取决于哪个文件保存该值；在用户、项目、本地或 `--settings` 文件中，它读取：5627某个设置文件将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 Claude Code 无法识别的值，例如拼写错误 `"reject"`。警告的第二句取决于哪个文件包含该值；在用户、项目、本地或 `--settings` 文件中，它显示为：
5411 5628
5412```text theme={null}5629```text theme={null}
5413"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.5630"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.
5414```5631```
5415 5632
5416在[托管设置](/docs/zh-CN/managed-settings)中，Claude Code 将无法识别的值视为 `refuse`（最严格的值），警告说跨会话消息被拒绝，直到管理员修复它。有关保留如何与您的其他设置文件中的值结合，请参阅 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound)。5633在[托管设置](/docs/zh-CN/managed-settings)中，Claude Code 将无法识别的值视为 `refuse`（最严格的值），警告说明跨会话消息将被拒绝，直到管理员修复它。有关保留行为如何与您的其他设置文件中的值结合，请参阅 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound)。
5417 5634
5418**要做什么：**5635**要做什么：**
5419 5636
5420* 将键设置为 `"accept"`、`"hold"` 或 `"refuse"`，或删除它5637* 将该键设置为 `"accept"`、`"hold"` 或 `"refuse"`，或删除它
5421* 当警告命名托管设置时，要求管理员修复该值5638* 当警告命名托管设置时，要求管理员修复该值
5422 5639
5423在 v2.1.248 之前，Claude Code 忽略无法识别的值而不警告。5640在 v2.1.248 之前，Claude Code 忽略无法识别的值而不警告。
5424 5641
5642<h3 id="anthropic-foundry-resource-must-be-a-foundry-resource-name">
5643 ANTHROPIC\_FOUNDRY\_RESOURCE 必须是 Foundry 资源名称
5644</h3>
5645
5646您将 [`ANTHROPIC_FOUNDRY_RESOURCE`](/docs/zh-CN/env-vars) 设置为了裸 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 资源名称以外的内容，例如端点 URL 或其主机名。Claude Code 在发送请求前拒绝了该值。该消息出现在 Claude 回复的位置，而不是作为启动警告：
5647
5648```text theme={null}
5649API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name (2-64 letters, digits and hyphens, not starting or ending with a hyphen, such as my-resource), not a URL or host name. To use a full URL, set ANTHROPIC_FOUNDRY_BASE_URL instead.
5650```
5651
5652**要做什么：**
5653
5654* 将 `ANTHROPIC_FOUNDRY_RESOURCE` 仅设置为资源名称，然后重启 Claude Code。对于端点 `https://my-resource.services.ai.azure.com/anthropic`，名称为 `my-resource`。
5655* 若要改为提供完整的端点 URL，请将 [`ANTHROPIC_FOUNDRY_BASE_URL`](/docs/zh-CN/env-vars) 设置为该 URL 并删除 `ANTHROPIC_FOUNDRY_RESOURCE`，然后重启 Claude Code。Claude Code 只接受这两个变量之一。
5656
5425<h3 id="the-200k-limit-isnt-enforced">5657<h3 id="the-200k-limit-isnt-enforced">
5426 200K 限制未被强制执行5658 200K 限制未被强制执行
5427</h3>5659</h3>
5428 5660
5429您设置了 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars)，这通常使[自动压缩](/docs/zh-CN/model-config#default-auto-compact-thresholds)将 1M 上下文模型上的会话保持在 200K 窗口，但没有压缩阈值将此会话限制在或低于 200K，因此对话可以超过它。5661您设置了 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars)，这通常使[自动压缩](/docs/zh-CN/model-config#default-auto-compact-thresholds)将 1M 上下文模型上的会话保持在 200K 窗口内，但没有压缩阈值将此会话限制在 200K 或以下，因此对话可以超过它。
5430 5662
5431```text theme={null}5663```text theme={null}
5432CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).5664CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).
5433```5665```
5434 5666
5435Claude Code 为它识别为具有本机 1M 窗口的每个模型自己强制执行 200K 限制，对于它不识别的模型 ID，它在它假设的窗口处压缩。当其他配置击败该强制执行时出现警告：5667Claude Code 会为它识别为具有原生 1M 窗口的每个模型自行强制执行 200K 限制，对于它无法识别的模型 ID，它会在其假设的窗口处压缩。当其他配置使该强制执行失效时，会出现此警告：
5436 5668
5437* 模型 ID 不是 Claude Code 识别的，例如[LLM 网关](/docs/zh-CN/llm-gateway)别名，并且您设置了 [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/zh-CN/env-vars) 或使用 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/zh-CN/env-vars) 将假设的窗口提高到 200K 以上。在这种情况下，消息也提供 `or update to a Claude Code version that recognizes <model>` 作为补救。5669* 模型 ID 不是 Claude Code 能识别的，例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名，并且您设置了 [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/zh-CN/env-vars) 或使用 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/zh-CN/env-vars) 将假设的窗口提高到 200K 以上。在这种情况下，消息还会提供 `or update to a Claude Code version that recognizes <model>` 作为补救措施。
5438* 通过 [`ANTHROPIC_BETAS`](/docs/zh-CN/env-vars) 或 [`--betas`](/docs/zh-CN/cli-reference#cli-flags) 标志请求的 `context-1m` 测试版仍然要求 API 在接受该测试版的模型上使用 1M 窗口，而没有任何东西在 200K 处压缩会话5670* 通过 [`ANTHROPIC_BETAS`](/docs/zh-CN/env-vars) 或 [`--betas`](/docs/zh-CN/cli-reference#cli-flags) 标志请求的 `context-1m` 测试版仍然会在接受该测试版的模型上向 API 请求 1M 窗口，而没有任何机制在 200K 处压缩会话
5439 5671
5440**要做什么：**5672**要做什么：**
5441 5673
5442* 设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-CN/env-vars)，或 [`autoCompactWindow`](/docs/zh-CN/settings-reference#autocompactwindow) 设置为 `200000`，以便自动压缩在 200K 边界处压缩5674* 设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-CN/env-vars)，或将 [`autoCompactWindow`](/docs/zh-CN/settings-reference#autocompactwindow) 设置为 `200000`，以便自动压缩在 200K 边界处压缩
5443* 如果消息命名此版本不识别的模型 ID，运行 `claude update`。识别 ID 为 1M 上下文模型的版本在没有进一步配置的情况下强制执行限制。5675* 如果消息命名了此版本无法识别的模型 ID，请运行 `claude update`。能够将该 ID 识别为 1M 上下文模型的版本会强制执行该限制，无需进一步配置。
5444* 如果您希望会话使用模型的完整窗口，请取消设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT`；警告仅报告 200K 限制未被强制执行5676* 如果您希望会话改为使用模型的完整窗口，请取消设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT`；该警告仅报告 200K 限制未被强制执行
5445 5677
5446在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json`，Claude Code 将警告写入调试日志而不是 stderr。5678在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json` 时，Claude Code 将警告写入调试日志而不是 stderr。
5447 5679
5448<h3 id="unrecognized-model-id-on-a-request">5680<h3 id="unrecognized-model-id-on-a-request">
5449 请求上无法识别的模型 ID5681 请求上无法识别的模型 ID
5450</h3>5682</h3>
5451 5683
5452Claude Code 为您的 Claude Code 版本不识别的模型 ID 发送了请求，并找不到将该 ID 映射到它识别的模型的 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 条目。Claude Code 仍然使用您配置的 ID 发送请求，不退出或切换模型。5684Claude Code 为您的 Claude Code 版本无法识别的模型 ID 发送了请求，并且找不到将该 ID 映射到它能识别的模型的 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 条目。Claude Code 仍然使用您配置的 ID 发送请求，不会退出或切换模型。
5453 5685
5454```text theme={null}5686```text theme={null}
5455[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}5687[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}
5456```5688```
5457 5689
5458在读取 stderr 的脚本或工具中，匹配 `[claude-code:unrecognized_model]` 前缀。在前缀和一个空格之后，Claude Code 写入一行 JSON 对象。Claude Code 可以在更高版本中向其添加字段，因此忽略您不期望的任何字段。它至少写入这两个：5690在读取 stderr 的脚本或测试工具中，请匹配 `[claude-code:unrecognized_model]` 前缀。在前缀和一个空格之后，Claude Code 写入单行 JSON 对象。Claude Code 可能在更高版本中向其添加字段，因此请忽略任何您未预期的字段。它至少写入以下两个字段：
5459 5691
5460* `model`：您配置的模型字符串5692* `model`：您配置的模型字符串
5461* `query_source`：使用模型的请求路径。Claude Code 为 `-p` 运行报告 `sdk`，为以 `agent:` 开头的值报告子代理。5693* `query_source`：使用该模型的请求路径。对于 `-p` 运行，Claude Code 报告 `sdk`；对于子代理，报告以 `agent:` 开头的值。
5462 5694
5463Claude Code 根据您运行它的方式将行写入两个位置之一：5695Claude Code 根据您的运行方式将该行写入以下两个位置之一：
5464 5696
5465* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p`，Claude Code 在每个 `--output-format` 下将其写入 stderr，因此您可以解析 stdout 而不过滤该行5697* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 时，Claude Code 在每种 `--output-format` 下都将其写入 stderr，因此您可以解析 stdout 而无需过滤掉该行
5466* 在交互式会话或[后台会话](/docs/zh-CN/agent-view)中，Claude Code 将其写入调试日志；使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它5698* 在交互式会话或[后台会话](/docs/zh-CN/agent-view)中，Claude Code 改为将其写入调试日志；使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它
5467 5699
5468Claude Code 每个模型字符串每个进程写入该行一次。它为每个进一步的无法识别的 ID 写入单独的行，例如[子代理](/docs/zh-CN/sub-agents#choose-a-model)或[后台功能](/docs/zh-CN/costs#background-token-usage)使用的 ID。5700Claude Code 每个进程为每个模型字符串写入该行一次。对于每个其他无法识别的 ID，例如[子代理](/docs/zh-CN/sub-agents#choose-a-model)或[后台功能](/docs/zh-CN/costs#background-token-usage)使用的 ID，它会写入单独的一行。
5469 5701
5470Claude Code 不为它解析为它识别的模型的提供商 ID 写入该行，例如 Amazon Bedrock `us.anthropic.claude-...` ID、Google Cloud 的 Agent Platform ID 带有 `@` 版本后缀，以及包含 Claude 模型 ID 的 Microsoft Foundry 部署名称。Claude Code 检查 Amazon Bedrock [应用推理配置文件 ARN](/docs/zh-CN/amazon-bedrock#map-each-model-version-to-an-inference-profile) 后面的模型，而不是 ARN 本身。它为无法解析的 ARN（例如拼写错误的 ARN）不写入行。5702对于它能解析为可识别模型的提供商 ID，Claude Code 不写入该行，例如 Amazon Bedrock `us.anthropic.claude-...` ID、带有 `@` 版本后缀的 Google Cloud Agent Platform ID，以及包含 Claude 模型 ID 的 Microsoft Foundry 部署名称。Claude Code 检查 Amazon Bedrock [应用推理配置文件 ARN](/docs/zh-CN/amazon-bedrock#map-each-model-version-to-an-inference-profile) 背后的模型，而不是 ARN 本身。对于无法解析的 ARN（例如拼写错误的 ARN），它不写入任何行。
5471 5703
5472**要做什么：**5704**要做什么：**
5473 5705
5474* 如果您故意设置了 ID，例如[LLM 网关](/docs/zh-CN/llm-gateway)别名，请在您的[设置文件](/docs/zh-CN/settings#where-settings-live)中添加 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 条目，其中 ID 作为其值。使用 Anthropic 模型 ID 作为键，而不是系列别名，例如 `opus`。对于示例行中的 `my-proxy-model`，添加此条目：5706* 如果您是有意设置该 ID 的，例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名，请在您的[设置文件](/docs/zh-CN/settings#where-settings-live)中添加一个以该 ID 为值的 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 条目。使用 Anthropic 模型 ID 作为键，而不是诸如 `opus` 的系列别名。对于示例行中的 `my-proxy-model`，添加此条目：
5475 5707
5476 ```json theme={null}5708 ```json theme={null}
5477 {5709 {
5481 }5713 }
5482 ```5714 ```
5483 5715
5484 Claude Code 然后将 `my-proxy-model` 视为 `claude-opus-4-6` 并停止写入该行。5716 然后 Claude Code 会将 `my-proxy-model` 视为 `claude-opus-4-6` 并停止写入该行。
5485 5717
5486* 如果 ID 命名比您的 Claude Code 版本更新的模型，运行 `claude update`5718* 如果该 ID 命名的模型比您的 Claude Code 版本更新，请运行 `claude update`
5487 5719
5488* 如果 ID 是拼写错误，在您可以设置模型的[位置](/docs/zh-CN/model-config#setting-your-model)或[别名变量](/docs/zh-CN/model-config#environment-variables)中修复它。如果 `query_source` 以 `agent:` 开头，改为在您设置[子代理模型](/docs/zh-CN/sub-agents#choose-a-model)的地方修复它。5720* 如果该 ID 是拼写错误，请在包含它的[可设置模型的位置](/docs/zh-CN/model-config#setting-your-model)或[别名变量](/docs/zh-CN/model-config#environment-variables)中修复它。如果 `query_source` 以 `agent:` 开头，请改为在您设置[子代理模型](/docs/zh-CN/sub-agents#choose-a-model)的地方修复它。
5489 5721
5490在 v2.1.233 之前，Claude Code 在为它不识别的模型 ID 发送请求时不写入行。5722在 v2.1.233 之前，Claude Code 在为无法识别的模型 ID 发送请求时不写入任何行。
5491 5723
5492<h3 id="stale-sandbox-mask-files-left-by-a-killed-session">5724<h3 id="stale-sandbox-mask-files-left-by-a-killed-session">
5493 被杀死的会话留下的陈旧沙箱掩码文件5725 被终止的会话留下的陈旧沙箱掩码文件
5494</h3>5726</h3>
5495 5727
5496`claude doctor` 在其诊断中打印此警告，`/status` 列出相同的行。当[沙箱](/docs/zh-CN/sandboxing)在文件系统隔离打开的情况下启用时，它在 Linux 和 WSL2 上出现。5728`claude doctor` 在其诊断中打印此警告，`/status` 也列出相同的行。当启用了[沙箱隔离](/docs/zh-CN/sandboxing)并打开文件系统隔离时，它会在 Linux 和 WSL2 上出现。
5497 5729
5498当沙箱命令运行时，沙箱通过在那里创建 0 字节只读占位符来保持对尚不存在的文件的写入拒绝，并在之后删除它。在该清理运行前被杀死的会话，例如通过 SIGKILL，会留下占位符。后来的会话在每次启动时再次只读绑定它们，因此诸如保存"是，不要再问"之类的设置写入失败。5730当沙箱中的命令运行时，沙箱通过在尚不存在的文件位置创建 0 字节只读占位符来保持对该文件的写入拒绝，并在之后删除它。在该清理运行前被终止的会话（例如通过 SIGKILL）会留下这些占位符。之后的会话在每次启动时都会再次以只读方式绑定它们，因此在占位符所在位置的设置写入（例如保存"是，不要再问"）会失败。
5499 5731
5500```text theme={null}5732```text theme={null}
5501- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json5733- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json
5504 5736
5505**要做什么：**5737**要做什么：**
5506 5738
5507* 退出在该项目中运行的任何其他 Claude Code 会话，然后使用 `rm` 删除每个列出的文件。警告列出最多三个文件并计数其余的，因此在删除后重新运行 `claude doctor` 直到警告不再出现。另一个会话的沙箱仍在使用的占位符是该会话写入保护的活跃部分5739* 退出在该项目中运行的任何其他 Claude Code 会话，然后使用 `rm` 删除每个列出的文件。警告最多列出三个文件并对其余文件计数，因此删除后请重新运行 `claude doctor`，直到警告不再出现。另一个会话的沙箱仍在使用的占位符是该会话写入保护的有效组成部分
5508* 如果您使用"是，不要再问"保存的权限选择没有坚持，请在删除占位符后再次保存5740* 如果您使用"是，不要再问"保存的权限选择没有生效，请在删除占位符后再次保存
5509 5741
5510在 v2.1.257 之前，`claude doctor` 没有标记这些文件；较早的版本在会话被杀死时留下相同的占位符。5742在 v2.1.257 之前，`claude doctor` 不会标记这些文件；较早的版本在会话被终止时会留下相同的占位符。
5511 5743
5512<h2 id="responses-seem-lower-quality-than-usual">5744<h2 id="responses-seem-lower-quality-than-usual">
5513 回复质量似乎低于预期5745 回复质量似乎低于预期
