Desktop application

• 使用 diff 视图审查和评论更改，然后通过 CI 监控生成的 PR
• 在浏览器窗格中预览你的运行应用，同时 Claude 验证自己的更改，并在其旁边打开外部网站
• 在 iOS Simulator 窗格中观看 Claude 运行和测试你的 iOS 应用
• 整理窗格，将聊天、diff、浏览器、终端和文件编辑器并排放置
• 提出侧边问题，使用会话的上下文而不偏离主线
• 让 Claude 检查、消息或存档你的其他会话
• 连接外部工具，如 GitHub、Slack 和 Linear
• 让 Claude 打开应用和控制你的屏幕
• 在你的机器上、云中或通过 SSH 运行

​

启动会话

• 环境：使用环境选择器（该行中的第一个控件）选择 Claude 运行的位置。请参阅环境配置。
  • 如果新会话的输入框下方没有环境选择器，请按照早期布局的步骤操作。
• 项目文件夹：点击环境选择器旁边的项目文件夹控件，选择 Claude 工作的文件夹。
  • 云端会话：选择仓库而不是文件夹
  • 已保存的本地或 SSH 环境：该环境已包含其文件夹，因此该行不显示项目文件夹控件。要更改文件夹，请编辑该环境。
• 权限模式：使用模式选择器选择 Claude 拥有多少自主权。您可以在会话期间更改权限模式。
• 模型：从该行靠右端的模型选择器中选择一个模型。您可以在会话期间更改模型。

​

使用代码

​

使用提示框

​

接受建议的提示词

• 使用建议：按 Tab 或 右箭头 将其放入输入框，根据需要进行编辑，然后按 Enter 发送。在接受建议之前按 Enter 不会发送它。
• 编写自己的提示词：直接开始输入。建议仅在输入框为空且没有附加文件时显示。

​

向提示添加文件和上下文

• @mention 文件：输入 @ 后跟文件名，将文件添加到对话上下文。
  • 在云端会话中：@ 只有在您发送第一条消息后才能列出文件。如果 @ 未列出任何文件，请先发送不含该文件的第一条消息，然后在下一条消息中 @mention 该文件。
• 附加文件：通过输入框旁边的 + 按钮将图像、PDF 和其他文件附加到您的提示词，或直接将文件拖放到提示词中。这对于共享错误的屏幕截图、设计模型或参考文档很有用。
  • 在 WSL 会话中：如果 + 菜单显示 Add image 而不是 Add files or photos，则您只能附加图像。要向 Claude 提供会话文件夹中的任何其他文件，请 @mention 它。

​

选择权限模式

​

自动模式可用性

​

预览您的应用

• 直接在浏览器窗格中与运行的应用交互
• 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单，并修复它发现的问题
• 从浏览器窗格标题栏中的 Dev servers 菜单启动或停止服务器，或一次停止所有服务器
• 通过浏览器窗格 ⋮ 菜单中的 Keep cookies，选择浏览器在您退出应用后是否保留 cookie，这样您就不必在开发期间重新登录

​

浏览外部网站

• 安全分类器在每个权限模式中审查 Claude 在外部页面上的写入操作，例如点击和输入。这些与自动模式使用的分类器相同，当它们标记操作时，无论模式如何，您都会收到权限提示。
• 在 Auto 和 Bypass permissions 以外的权限模式中，在 Claude 导航到新网站之前也会应用域名允许列表检查。

​

批准 Claude 在网站上的操作

​

在浏览器和 Chrome 扩展之间选择

​

为您的组织限制外部浏览

​

使用 diff 视图审查更改

• macOS：按 Cmd+Enter
• Windows：按 Ctrl+Enter

​

审查您的代码

• 点击 Walk through in diff 打开 diff 视图，逐条查看结果。当前 diff 中的结果会显示在其对应的行上，您可以在那里点击 Fix this one 或忽略它。
• 点击 Apply fixes 让 Claude 修复仍未处理的结果。

​

监控 Pull Request 状态

• Auto-fix：在本地会话中，Claude 还会处理除您之外的其他人留下的新审查评论。评论作者必须是仓库所有者、组织成员、协作者或 GitHub App。
• Merge when ready：为该 PR 启用 GitHub 的自动合并。在本地会话中，除非基础分支使用合并队列，否则 Desktop 会请求 squash 合并。
  • 在 SSH 和 WSL 会话中：Merge when ready 处于禁用状态，因此请在 GitHub 上为该 Pull Request 启用自动合并
  • 如果仓库不允许自动合并：Merge when ready 无法打开，因此请先在您的 GitHub 仓库设置中启用自动合并
• 早期布局：会话有 Pull Request 后，点击其状态栏上的 CI。

​

整理工作区

• 窗口较窄时：放不下的按钮会移入该菜单
• 对于没有按钮的窗格：Background tasks 和 Plan 等窗格会在会话有内容可在这些窗格中显示时列出

​

查看会话详细信息

​

隐藏或显示会话详细信息面板

​

在终端中运行命令

​

打开和编辑文件

• 本地会话：您可以编辑会话工作目录中的文件，但 .mcp.json 和 .claude/settings.json 等部分文件为只读。要更改这些文件，请在其他应用中打开。
• 云端、SSH 和 WSL 会话：文件窗格为只读，因此请要求 Claude 进行编辑。

​

在文件窗格中保存编辑

​

在其他应用中打开文件

• Attach as context：将文件添加到您的下一个提示词
• Open in：在已安装的编辑器（如 VS Code、Cursor 或 Zed）中打开文件
• Show in Finder（macOS）、Show in Explorer（Windows）：打开包含文件夹
• Copy：一个子菜单，可复制文件的 Absolute path、Relative path 或 Filename

​

切换视图模式

​

快捷键

• Cmd+Option：按 Alt
• Cmd+Ctrl：按 Ctrl+Alt
• Cmd：按 Ctrl

​

检查使用情况

• 当前布局：会话详细信息面板中 Context 卡片的标题以百分比形式显示该值。打开该卡片可按类别查看占用上下文窗口的内容。
• 早期布局：点击模型选择器旁的使用环形图。其弹出窗口会显示您的上下文窗口使用情况。

​

让 Claude 使用你的计算机

​

何时应用计算机使用

• 如果你有一个服务的连接器，Claude 使用连接器。
• 如果任务是 shell 命令，Claude 使用 Bash。
• 如果任务是浏览器工作且你已设置Chrome 中的 Claude，Claude 使用那个。
• 如果任务是运行或测试 iOS 应用，Claude 使用 iOS Simulator 窗格，它不使用屏幕控制。
• 如果以上都不适用，Claude 使用计算机使用。

​

启用计算机使用

​

应用权限

• 拒绝的应用：在此处添加应用以拒绝它们而不提示。Claude 可能仍然通过允许应用中的操作间接影响被拒绝的应用，但它无法直接与被拒绝的应用交互。
• Claude 完成时取消隐藏应用：当计算机使用不在后台运行时，Claude 隐藏你的其他窗口，以便它仅与批准的应用交互。当 Claude 完成时，隐藏的窗口被恢复，除非你关闭此设置。

​

管理会话

​

使用会话并行工作

• 并排显示：在 macOS 上按住 Option 或在 Windows 上按住 Alt 并点击侧边栏中的会话，或右键点击该会话并选择 Open in，然后选择 Split view
• 在单独的窗口中：在 macOS 上按住 Cmd 或在 Windows 上按住 Ctrl 并点击会话，或右键点击该会话并选择 Open in，然后选择 New window

​

在独立的 worktree 中运行会话

• 使用已保存的环境时：在创建或编辑环境时设置 Worktree
• 早期布局：选中输入框上方分支名称旁边的 worktree 复选框

• 本地会话：在 Settings > Claude Code 中设置 Worktree location
• SSH 会话：在 SSH 连接上设置 Worktree folder

​

向会话添加文件夹

• 本地会话启动前：在创建已保存的环境或编辑已保存的环境时，在 Folders 下添加文件夹，然后从该已保存的环境启动会话。
• 本地或 SSH 会话运行期间：点击输入框旁边的 + 并选择 Add folder。Claude 会直接在该文件夹中工作，不使用 worktree。

​

存档会话

​

存档会话时保留未提交的更改

• 如果 Desktop 询问这些更改：选择 Archive anyway 以丢弃它们，或取消并提交它们
• 如果更改仅为未跟踪的文件：请在 Claude 于该会话中创建的 Pull Request 合并之前，提交您想保留的文件，因为届时 Desktop 可能会在不询问的情况下删除它们
• 其他任何情况：worktree 及其更改会保留在磁盘上。对于本地会话，Desktop 会在会话被存档或您最后一次打开它（以较晚者为准）约 30 天后将两者一并删除。要保留这些更改，请从 Archived 选项卡打开该会话并选择 Unarchive

​

整理和查找会话

• 当前布局：将鼠标悬停在会话列表中的标题上以显示 Group and sort 图标，然后点击它。要查找已存档的会话，请选择菜单最后一行的 View all，然后打开 Archived 选项卡。
• 早期布局：Filter 图标无需悬停即会显示。点击它可使用 Group by 或 Sort by 排列列表。要显示已存档的会话，请选择 Status，然后选择 Archived。

​

检查并释放上下文

​

在会话完成时获得通知

​

在不偏离会话的情况下提出侧边问题

​

查看后台任务

​

跨会话工作

• 在 Claude 存档会话之前，您会看到一张批准卡片，但自动模式和 Bypass permissions 模式除外，在这两种模式下 Claude 可以在没有批准卡片的情况下存档会话。如需在存档前被询问，请切换到 Manual。
• Claude Code 会根据接收会话的入站控制检查来自此使用入口的每条消息，即使接收会话本身未启用跨会话消息传递。如果您在接收会话中将 crossSessionInbound 设置为 refuse，Claude Code 会丢弃来自此使用入口的消息。Claude Code 会向 Claude 桌面应用报告该拒绝。在 v2.1.234 之前，对于未启用跨会话消息传递的接收会话，Claude Code 会丢弃来自此使用入口的所有消息。
• Claude Code 会引用每条传入消息并注明其来自哪个发送会话，且 Claude 在据此执行操作时仍遵循接收会话自身的权限设置。

​

启动 Claude 建议的任务

• Start：在另一个会话中启动该任务。默认情况下，该任务在当前会话的环境中运行。随后卡片会显示已启动会话的状态，侧边栏会在当前会话下方列出已启动的会话。
• Do it here：将该任务作为消息发送到当前会话
• Options：在点击 Start 之前，查看或更改环境、模型、worktree 和权限等设置
• Start all：当卡片列出多个任务时，在各自的会话中启动每个任务，无需等待一个任务完成后再启动下一个

​

在云端运行长时间运行的任务

• 当前布局：选择云端环境后，在输入框下方的一行中选择。
• 早期布局：在输入框上方选择。要添加另一个仓库，请点击所选仓库旁边的 +。

​

在另一个使用入口继续

• 选择 Cloud 可将会话作为云端会话继续，您的对话会以摘要形式带过去。在您确认之前，对话框会说明您的文件是否也会一并移动，以及云端会话就绪后此会话是否会被存档。通过 SSH 或在 WSL 中运行的会话无法以这种方式移动。
• 选择已安装的编辑器或文件管理器，可在其中打开该会话在磁盘上的文件夹。

​

控制哪些会话显示在您的其他设备上

• 您为该会话打开它：使用该会话的 Remote Control 开关，或在其输入框中输入 /remote-control。
• 在启动时连接：当 Settings > Claude Code 中的 Connect new sessions to Remote Control 处于打开状态时，新会话会自动连接。如果您从未更改过该设置，Desktop 会遵循您的用户设置或托管设置中的 remoteControlAtStartup，其次是您组织的默认值。

• 单个会话：关闭其 Remote Control 开关。在启动时已自动连接的会话中，输入 /remote-control 会保持 Remote Control 打开，并显示 Remote Control is already on. This session connected automatically when it started.。点击该行上的 Turn off 即可断开连接。
• 此计算机上的新 Desktop 会话：在 Settings > Claude Code 中关闭 Connect new sessions to Remote Control。如果它已显示为关闭，请先将其打开再关闭，以便 Desktop 保存您的选择。保存后，它优先于 remoteControlAtStartup 和默认值。
• 此计算机上的任何会话，包括 CLI：在 ~/.claude/settings.json 中将 disableRemoteControl 设置为 true，以阻止会话连接。保存该文件时已连接的会话会保持连接，直到您为其关闭 Remote Control。

​

来自 Dispatch 的会话

​

跟进 Dispatch 启动的会话

​

设置 Dispatch

​

扩展 Claude Code

​

连接外部工具

​

使用 skills

​

安装插件

​

配置预览服务器

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

​

自动验证更改

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

​

配置字段

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 8443,
      "url": "https://localhost:8443"
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "url": "https://app.localhost:3000"
    }
  ]
}

​

端口冲突

• true：Claude 自动查找并使用空闲端口。适合大多数开发服务器。
• false：Claude 失败并出现错误。当你的服务器必须使用特定端口时使用此选项，例如 OAuth 回调或 CORS 允许列表。
• 未设置（默认）：您的服务器会获得下一个空闲端口，与 true 相同，但下面这一种情况除外。在 Claude Desktop v2.37337.0 之前，Claude 会改为询问服务器是否需要该确切端口，然后将您的回答保存在 launch.json 中。

• 您通过 npm、yarn、pnpm 或 bun 脚本启动服务器。
• 您的首选端口在该脚本中是硬编码的，或者 Claude 无法检查该脚本。
• 您没有在 runtimeArgs 中传递端口。

​

示例

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev"],
      "port": 3000
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "apps/web",
      "port": 3000,
      "autoPort": true
    },
    {
      "name": "api",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start"],
      "cwd": "server",
      "port": 8080,
      "env": { "NODE_ENV": "development" },
      "autoPort": false
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "server",
      "program": "server.js",
      "args": ["--verbose"],
      "port": 4000
    }
  ]
}

​

环境配置

• Local：在您的计算机上运行，可直接访问您的文件
• Cloud：默认在 Anthropic 托管的基础设施上运行。即使您关闭应用，会话也会继续。
• SSH：在您通过 SSH 连接的远程计算机上运行，例如您自己的服务器、云虚拟机或开发容器。正在运行的任务可以在 Desktop 断开连接时继续运行，但使用 Claude 账户时，任务可能会在其登录过期时停止。
• WSL（Windows）：在您计算机上的 WSL 2 发行版内运行，使用该发行版的 Linux 工具链和原生路径

​

创建已保存的环境

​

Desktop 为您创建的环境

​

使用、编辑或移除已保存的环境

• 启动会话：选择该条目。
• 编辑或删除：将鼠标悬停在条目上并点击齿轮图标。要删除本地或 SSH 环境，请在 Edit environment 中点击 Delete environment。
• 归档云端环境：请参阅归档环境。

​

本地会话中的环境变量

​

为本地会话设置环境变量

​

为开发服务器设置环境变量

• macOS 和 Linux：在您的 shell 配置文件中导出它
• Windows：将其添加到您的用户或系统环境变量中
• 任何平台：如果您能打开本地环境编辑器，请将其保存在其中

​

使用本地环境编辑器

• 输入框下方的选择器：将鼠标悬停在代表您计算机的条目上，即 Local 下的第一个条目。如果出现齿轮图标，请点击它。如果没有出现，则表示编辑器不可用，请通过其他方式为本地会话或开发服务器设置变量。
• 输入框上方的选择器：将鼠标悬停在 Local 上并点击齿轮图标

​

Claude 运行的命令中缺少导出的变量或变量值错误

​

Desktop 自行设置的环境变量

• API_TIMEOUT_MS：本地会话获得的值为 900000，即 15 分钟。如需更长的超时时间，请安装 Claude Code CLI 并使用它来代替 Desktop。在您的 shell 中设置该变量，然后在终端中运行 claude。
• ANTHROPIC_BASE_URL：当您使用 Claude 账户登录时，本地会话获得的是 Anthropic 的 API 主机。要使用网关，请改为设置 Desktop 的第三方推理配置。

​

关闭扩展思考

​

固定思考预算

​

受管设备上的本地会话

​

云端会话

• 添加环境：选择选择器菜单底部的 New environment，然后选择 New environment 对话框中的 Cloud 选项卡
• 编辑或归档您自己的某个环境：将鼠标悬停在该环境上，然后点击齿轮图标

​

SSH 会话

​

SSH 会话的远程计算机要求

• 系统：x86_64 或 arm64 处理器。该计算机还必须满足 Claude Code 的系统要求。在 Linux 上，Claude Code 需要 glibc 2.17 或更高版本，或 musl。若要查看该计算机使用的是哪一种，请在其上运行 ldd --version。在 Alpine Linux 等基于 musl 的发行版上，还需安装 Claude Code 所需的软件包。
• SFTP：SSH 服务器必须提供 SFTP 子系统，该子系统通过其 sshd_config 中的 Subsystem sftp 行启用。若要检查，请在您计算机上的终端中使用 sftp 连接到相同的主机和端口。正常工作的服务器会显示 sftp> 提示符。
• 服务器上的 MaxSessions 1：要连接到其 sshd_config 设置了 MaxSessions 1 的服务器，请执行以下操作之一：
  • 您的计算机运行 macOS 或 Linux：更新到 Claude Desktop v3.1623.0 或更高版本
  • 您的计算机运行 Windows：确保 Desktop 通过 OpenSSH 客户端连接，因为 Desktop 的内置 SSH 客户端无法连接到该服务器
  • 您可以更改服务器：调高 MaxSessions，例如调到 OpenSSH 的默认值 10
• 使用 MaxSessions 1 时的登录：使用无需提示即可完成的登录方式，例如由您的 SSH agent 持有的密钥。Desktop 每次连接或重新连接时至少登录两次。每个终端选项卡，以及您在其中运行以 ! 开头的命令的每个 Desktop 会话，预计还需至少再登录一次。Claude 运行的命令则不需要额外登录。
• 使用 MaxSessions 1 时的一次性验证码：如果每次登录都会提示您（例如使用一次性验证码时），! 命令会失败。请改为在终端选项卡中运行这些命令，终端选项卡会在其自己的窗格中提示。
• 安装文件夹：Desktop 会在您主目录下的 ~/.claude/remote/ 中安装一个辅助程序和 Claude Code。它从该位置运行这些程序，因此该文件夹不能位于以 noexec 挂载的文件系统上。请在每个连接用户的主目录中预留约 1 GB 的磁盘空间。有关该文件夹包含的内容，请参阅远程计算机上的文件和进程。
• Shell：远程计算机上为您的账户设置的 shell 必须能运行通过 SSH 发送的命令，Bash、Zsh 和 sh 均可
• 网络：Claude Code 在远程计算机上运行，并从那里发出网络请求，因此该计算机需要具备 Claude Code 所需的网络访问。如果该计算机无法下载 Claude Code，Desktop 会在您的计算机上下载并上传它。Claude Code 的其他请求仍从远程计算机发出。在 Linux 远程计算机上，如果这些请求需要代理，请为 SSH 会话设置代理。

​

检查远程机器的主机密钥

• Desktop 询问 Connect to <host> for the first time?，或者您选择了 Review new key：Desktop 指明的机器，即 <host>
• Desktop 询问 Connect through <jump host> for the first time?：跳板机，即您的连接所经过的机器，而不是您想要访问的机器
• ssh 在终端中询问或发出警告：其消息中指明的机器，这可能不是您输入的那台

• 该机器由他人管理：向对方索取其主机密钥指纹
• 由您管理，且运行 Linux 或 macOS：在该机器的控制台上，或通过您已信任的连接，在该机器上运行 ssh-keygen -lf /etc/ssh/ssh_host_<type>_key.pub。对于 <type>，请使用 Desktop 或 ssh 在指纹旁显示的密钥类型的小写形式：ED25519 或 ssh-ed25519 对应 ed25519。

• 两者一致：信任该密钥。在 Desktop 中选择 Trust and connect 或 Trust new key，或在终端中回答 yes。
• 两者不一致，或者您无法检查：不要连接。在 Desktop 中选择 Cancel，或在终端中回答 no。如果该机器由他人管理，请告知对方您看到的指纹。

​

为 SSH 会话设置代理或 CA 证书

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
  }
}

​

使用您的 SSH 配置

• macOS 和 Linux：Desktop 通过运行您计算机上的 OpenSSH 客户端进行连接，因此会使用您的 ~/.ssh/config。通过 OpenSSH 客户端连接需要 Claude Desktop v1.37937.0 或更高版本。
• Windows：当 Desktop 通过 OpenSSH 客户端连接时，它会使用您的 %USERPROFILE%\.ssh\config。如果您使用的是 Claude 账户而不是第三方提供商，则通过 OpenSSH 客户端连接需要满足以下所有条件：
  • Claude Desktop v2.2553.0 或更高版本。要查找您的版本，请参阅检查您的版本。
  • Microsoft 的 OpenSSH 9.4 或更高版本
  • 使用本页顶部的下载按钮安装的 Desktop，因为来自 Microsoft Store 的 Desktop 不会通过 OpenSSH 客户端连接
  如果您无法满足这些要求，或者您使用的是第三方提供商，请参阅在 Windows 上不使用 OpenSSH 客户端进行连接。

• macOS 和 Linux 上的客户端版本：运行 ssh -V。客户端必须是 OpenSSH 7.6 或更高版本。
• Windows 上的客户端版本：Desktop 会首先尝试 PATH 上的 ssh，因此请运行 ssh -V。如果输出显示 OpenSSH_for_Windows_ 且版本为 9.4 或更高，则该客户端符合要求。如果不符合，请检查 Desktop 接下来会尝试的两个文件夹：先在 C:\Windows\System32\OpenSSH 中运行 .\ssh.exe -V，然后在 C:\Program Files\OpenSSH 中运行。
• Windows 上没有符合要求的客户端：在 Windows 中添加 OpenSSH Client 可选功能并安装待处理的 Windows 更新，或者安装 Microsoft 的较新构建版本。然后退出并重新打开 Desktop。要查看 Desktop 是否找到了可用的 OpenSSH 客户端，请在 ssh.log 中查找 Windows OpenSSH client: 及版本号，或查找 no usable Windows OpenSSH client。
• 条目：在 Windows 上，请使用通过了版本检查的客户端。使用 Host 名称运行 ssh，例如 ssh devbox。如果失败，请先修复该条目。

• SSH port：此处的值会覆盖条目的 Port
• SSH key (optional)：使用 OpenSSH 客户端时，除了条目的 IdentityFile 和 SSH agent 中的密钥外，Desktop 还会提供您选择的密钥文件。在 Windows 上，请选择 OpenSSH 格式的密钥，因为 ssh 无法读取 PuTTY .ppk 文件。

• 条目中的设置：Desktop 会采用 HostName、User、Port 和 IdentityFile。如果您的 PATH 上有 sh shell，它还会采用 ProxyCommand。
• SSH key (optional)：将此字段留空以保留条目的 IdentityFile，因为您在此处选择的密钥文件会替换 IdentityFile
• CertificateFile 和 ProxyJump：Desktop 会忽略 CertificateFile，如果条目设置了 ProxyJump，连接会失败。要使用其中任一设置，请通过 OpenSSH 客户端连接。

Host devbox
  HostName devbox.internal.example.com
  User alice
  ProxyJump bastion.example.com

Host devbox-container
  User dev
  ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i

[profile corp]
region = us-east-1
credential_process = /full/path/to/your-credential-helper

Host i-*
  ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

Host devbox
  HostName devbox.internal.example.com
  User alice
  ProxyJump bastion.example.com
  ConnectTimeout 120

ssh -G -o HostName=devbox.internal.example.com -l alice devbox

Match host *.internal.example.com !originalhost devbox

• 若要访问远程计算机上的端口：自行转发
• 若要在远程计算机上使用您自己的密钥：在远程计算机本身上设置凭据，例如用于 git push

​

访问远程计算机上的端口

ssh -N -L 3000:localhost:3000 devbox

​

Windows 远程计算机

• 终端：在文件夹为 Windows 路径（例如 C:/projects/app）的会话中，终端不会打开
• 沙箱：Claude Code 在那里以原生 Windows 方式运行，在此环境下它运行命令时不使用沙箱。请参阅沙箱在何处运行。
• 插件：如果插件包含 Windows 无法存储的文件或文件夹名称（例如含有 : 的名称），Desktop 不会复制该插件。会话会列出 Desktop 遗漏的插件。
• MCP 服务器：在某些 Windows 远程计算机上，Claude 对来自 claude_desktop_config.json 的 MCP 服务器的调用会经过 Desktop，因此 Desktop 断开连接时 Claude 无法调用其工具。在 Claude Desktop v2.37337.0 之前，这适用于所有 Windows 远程计算机。
• Worktree：worktree 位于 <project-root>/.claude/worktrees/。如果您选择其他文件夹，Desktop 会忽略它。
• 早期消息：如果 SSH 服务器的 shell 是 cmd.exe 或 Windows PowerShell，您可能需要先连接才能看到会话的早期消息
• 分叉：如果 SSH 服务器的 shell 是 cmd.exe 或 Windows PowerShell，您只能在会话的第一条消息处分叉会话
• 断开连接时运行：只有当 SSH 服务器允许程序在启动它的连接结束后继续存在时，任务才会在 Desktop 断开连接时继续运行。若要确认，请测试远程计算机。
• 残留进程：会话结束后，请检查计算机上是否有 Claude Code 启动的程序，因为它们可能会继续运行。Desktop 安装的后台辅助程序在那里不会自行停止。

​

在 Desktop 断开连接时保持任务运行

• 睡眠或网络中断后：如果进程仍在运行且 Desktop 可以无需提示登录，您会重新获得正在运行的任务。如果无法登录，请发送消息。
• 退出之后：任务会继续运行，但除非 Desktop 能重新接入其进程，否则当会话再次打开时您会失去该任务。退出之前，请查看 Desktop 何时可以重新接入。如果您失去了任务，请发送消息以继续。

• Desktop 无法重新连接：会话会说明原因，也可能会有通知说明。Desktop 可能需要您登录。
• 身份验证错误：登录令牌或凭据可能已过期。使用 Claude 账户时，请发送消息以继续。使用第三方提供商时，请参阅 3P 上 Claude Desktop 中的 SSH 远程会话。
• 等待中的请求：回应该请求
• 以上都不是：发送消息以继续

• 先更新：在开始长时间任务之前更新 Desktop。在 macOS 和 Windows 上，Desktop 可能会自行重启以安装已下载的更新。当 Claude 正在处理 SSH 任务时，该重启会等待。默认情况下，一旦更新已等待 72 小时，如果 Desktop 之后能够重新加入该任务，重启就可能在任务期间进行。
• 退出前检查：退出或重启后，您不一定能重新获得正在运行的任务，例如在某些 Desktop 更新之后。有关具体情况，请参阅退出 Desktop 后重新打开会话。
• 使用旧版本时，保持 Desktop 打开：在 Windows 上使用 v3.1623.0 之前的 Claude Desktop 时，Desktop 退出或重启后，您无法重新获得正在运行的任务。在 macOS 或 Linux 上使用 v2.42304.0 之前版本的第三方提供商时也是如此。在这两种情况下，请在任务期间保持 Desktop 打开。要查找您的版本，请参阅检查您的版本。
• 减少请求：选择让任务更少等待您的权限模式、规则或 hook
• 检查跳板机：如果您的跳板机要求登录（例如向手机发送推送），请改用无需提示即可工作的登录方式。否则，Desktop 每次尝试重新连接时都可能发送另一条推送。
• 测试远程计算机：启动一个短任务，在任务仍在运行时退出 Desktop，并在任务应该完成很久之后再次打开会话。如果任务尚未完成且会话未显示身份验证错误，请检查远程计算机上可能结束任务的因素。
• 不要在 Desktop 的终端中运行命令：如果远程计算机会注销空闲终端，请从 Desktop 之外的 SSH 登录运行您自己的命令

• 登录令牌或凭据：使用 Claude 账户时，令牌过期后任务会因身份验证错误而停止。使用第三方提供商时，会过期的凭据（例如来自单点登录或凭据辅助程序的凭据）同样如此。请参阅 3P 上 Claude Desktop 中的 SSH 远程会话。使用 Claude 账户时，请保持 Desktop 运行并连接，以便它能续期登录。
• 远程计算机：如果远程计算机重启，或在您的 SSH 连接关闭时结束您的进程，正在运行的任务就会结束。在 Desktop 断开连接期间，不会有任何东西重新启动它。systemd-logind 的 KillUserProcesses 为 yes 且适用于您用户的 Linux 计算机会以这种方式结束您的进程。若要在这类计算机上保持任务运行，请让管理员豁免您的用户，例如使用 KillExcludeUsers。
• 空闲终端：某些 Linux 远程计算机会注销在设定时间内无人输入的终端（systemd-logind 的 StopIdleSessionSec）。在 macOS 或 Linux 上的 Desktop 中，会话的终端和 ! 命令默认共享 Desktop 的 SSH 连接。因此，该注销会在 Desktop 连接期间结束连接，正在运行的任务也可能随之结束。关闭终端窗格并不能防止这种情况，因此请不要在该终端中运行命令。
• Desktop 更新：如果更新带来了新的辅助程序，Desktop 会在之后的某次连接时替换远程计算机上的辅助程序，这可能会结束仍在运行的任务
• 长时间离开：在 Linux 或 macOS 远程计算机上，如果 Desktop 30 天内未连接，辅助程序会停止，并结束在其下运行的所有 Claude Code 进程。请在此之前连接。

• Worktree：在使用 worktree 的会话中，Desktop 会在 Claude 进行每次文件编辑之前对其进行检查。在 Desktop 断开连接期间，每次编辑会等待约 30 秒然后失败。Shell 命令仍会运行。在 Linux 或 macOS 远程机器上，编辑可以继续正常进行。如果您不确定，请在不使用 worktree 的情况下启动会话。
• 文件夹限制：如果您的组织限制了会话可以使用的文件夹，无论是否使用 worktree，Desktop 都会检查每次文件读取、搜索和编辑。在 Desktop 断开连接期间，每项操作最多等待 10 分钟，然后失败。
• 连接器：连接器和 Desktop 提供的其他工具通过 Desktop 运行，因此在其断开连接期间，每次调用都会在约 30 秒后失败
• 工作流：Desktop 会在每个新工作流启动前对其进行检查，因此在 Desktop 断开连接期间，新工作流最多等待 10 分钟，然后失败
• MCP 服务器：Claude Code 在远程计算机上启动的 MCP 服务器不通过 Desktop 运行，因此 Claude 仍可调用其工具。仅当 Desktop 未使用其内置 SSH 客户端时，来自 claude_desktop_config.json 的服务器才属于这一类。否则，以及在某些 Windows 远程计算机上，Desktop 断开连接期间 Claude 无法调用其工具。

• 自动模式：如果您可以使用自动模式，请选择自动模式。在多次被阻止后，系统会再次询问您。
• 允许规则：在远程计算机上的用户设置文件 ~/.claude/settings.json 中，为任务所需的命令添加允许规则。如果您的组织仅接受来自托管设置的权限规则，请让管理员将其添加到能传递到远程计算机的托管设置中。有关项目 .claude/settings.json 中的允许规则，请参阅项目允许规则和工作区信任。
• 自动应答的 hook：在远程计算机上的 ~/.claude/settings.json 中配置 PermissionRequest hook，以代替您允许或拒绝请求
• 提醒您的 hook：在同一文件中使用 permission_prompt 匹配器配置 Notification hook，以便在有请求等待时向自己发送消息
• 在 Claude 完成时通知您的 hook：在同一文件中配置 Stop hook，以便在 Claude 完成响应时向自己发送消息。当 API 错误结束该轮次时，它不会运行。对于这种情况，请配置 StopFailure hook。

• 记住的密码：您让 Desktop 记住的密码也可以无需提示登录，但若长时间离开，最好使用由您的 SSH agent 持有的密钥。如果使用该密码的登录中断或挂起，Desktop 可能会停止重新连接并等待您。
• 任何其他提示：如果远程计算机提示输入其他内容（例如一次性验证码），您可能会在计算机上收到通知。点击该通知或在会话中发送消息，Desktop 就会显示该提示。

• Windows 上的 Desktop，任务在 v3.1623.0 之前的版本中启动：即使 Desktop 此后已更新，您也无法重新获得该任务。请仅在您预计任务已完成时再次启动 Desktop，因为会话可能会在 Desktop 启动时打开，而会话打开时任务会停止。如果您不知道任务是在哪个版本中启动的，也请等到您预计任务已完成时再启动。
• macOS 或 Linux 上的第三方提供商，任务在 v2.42304.0 之前的版本中启动：您无法重新获得该任务。请仅在您预计任务已完成时再次启动 Desktop。
• 任何其他任务：启动 Desktop 并打开会话，如果 Desktop 重新加入，任务就会继续。它并不总能重新加入，例如在某些 Desktop 更新之后，因此请在长时间任务之前更新。

​

选择 SSH 会话 worktree 的位置

1. SSH 连接上的 Worktree folder
2. 远程计算机上 ~/.claude/settings.json 中的 worktree.location
3. <project-root>/.claude/worktrees/，即默认位置

​

远程计算机上的文件和进程

• 辅助程序：每台连接的计算机对应一个或多个 server 进程
• Claude Code：辅助程序为该用户的会话启动的进程，每个进程都来自以其版本命名的文件，例如 2.1.295-…

​

在登录前关闭的连接

drop connection #0 from [203.0.113.7]:51234 on [192.0.2.10]:22 penalty: connections without attempting authentication

• 在方括号中指定模式的 filter 行，例如 filter = sshd[mode=aggressive]：使用该模式。
• 仅有带 [mode=%(mode)s] 的默认 filter 行：使用 mode 行中的值，如果没有该行则为 normal。

fail2ban-regex -o ip lines.log "sshd[mode=aggressive]"

• mode：在您的 jail 设置它的任何位置（mode 行中或诸如 filter = sshd[mode=aggressive] 的行的方括号中）将其设置为 normal。您会放弃只有其他模式才会进行的所有统计，例如对连接后未尝试登录即离开的客户端的统计。
• ignoreip：将其设置为人们连接所用的地址，例如 ignoreip = 203.0.113.7。之后 fail2ban 不会统计来自这些地址的任何内容，包括登录失败。

​

使用在远程计算机上设置的 MCP 服务器

​

通过链接打开 SSH 会话

claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

• 您已有的连接：如果主机、用户和端口与您的某个连接匹配，Desktop 会询问是否使用它，并向您显示该连接的名称和主机，如果链接指定了文件夹，还会显示文件夹。
• 新连接：否则，Desktop 会打开添加 SSH 连接的对话框。当您添加连接时，Desktop 会在保存任何内容之前询问是否连接，并向您显示链接中的主机，如果链接指定了端口和文件夹，还会显示它们。

• 确认之前：检查主机和文件夹。
• 发送之前：检查提示词和所选环境。

• 您已退出登录：登录后再次打开链接。
• 另一个对话框处于打开状态：关闭它，然后再次打开链接。
• 链接无效：Desktop 会显示一条消息说明需要修复的内容，并且不会填入提示词。
• Desktop 版本早于 v2.110.0：较早的版本会忽略 SSH 参数，仅带着提示词打开新会话页面。
• SSH 会话已关闭：如果您的管理员将允许列表设置为空数组，Desktop 会拒绝 SSH 链接。

​

通过命令创建 SSH 连接

{
  "sshHostCommands": [
    {
      "id": "devbox",
      "name": "Dev box",
      "command": "acme-dev create",
      "startDirectory": "~/project"
    }
  ]
}

• 程序：写出其名称，或从 / 开始的完整路径，不含空格。对于裸名称，Desktop 会在您的登录 shell 导出的 PATH 中查找。相对路径（例如 ./acme-dev）、以 ~ 开头的路径以及 shell 别名和函数都不起作用。
• 参数：用空格分隔普通参数。命令只能包含空格、ASCII 字母、数字以及字符 +,-./:=@_~，并且任何单词都不能以 ~ 开头。
• 脚本：如果命令需要其他内容，例如引号、管道、变量或包含 ? 或 & 的 URL，请将其放入脚本中。使脚本可执行，以 #! 行开头，并将 command 设置为其完整路径，例如 /Users/you/bin/make-devbox。在 macOS 上，请勿将脚本放在 Documents、Desktop 和 Downloads 文件夹中，macOS 可能会阻止其运行。
• 输入：程序没有输入，也没有终端，因此无法在那里提示您。如果您的工具通过浏览器或提示让您登录，请先在终端中登录，并在每次登录失效时重新登录。
• 环境：程序在您的主目录中运行，使用您的登录 shell 导出的变量。Desktop 在启动时读取这些变量，与ProxyCommand 的处理方式相同，因此更改变量后请退出并重新打开 Desktop。
• 时间限制：程序运行超过 10 分钟仍未结束时，Desktop 会将其停止。Desktop 的进度消息不会显示程序的输出。要更早停止程序，请选择该消息旁边的 Cancel。

• 一行：host 或 user@host，写法与 SSH 链接中的 ssh_host 相同。要指定端口，请使用 JSON 格式。
• 一个 JSON 对象：sshHost，以及可选的数字 sshPort 和用于替换条目中对应值的 startDirectory，例如 {"sshHost": "dev@devbox-1234.example.com", "sshPort": 2222}

acme-dev create < /dev/null > host.txt

#!/bin/bash
out=$(mktemp) || exit
trap 'rm -f "$out"' EXIT
acme-dev create > "$out" || exit
tail -n 1 "$out"

• 主机密钥：在 OpenSSH 的默认主机密钥检查下，检查密钥的指纹，然后选择是否连接。要跳过此问题，请让您的命令在打印主机之前，使用您的工具在创建机器时获得的密钥，将其添加到 ~/.ssh/known_hosts。对于 22 以外的端口，该行以 [host]:port 开头。如果您的工具会重复使用主机名，也请删除旧密钥所在的行。
• 文件夹：选择是否信任您在那里打开的文件夹

• 新主机：Desktop 保存主机后的 10 分钟内，该项显示为灰色，因为新机器可能需要一段时间才能启动。在新主机无响应期间，新建会话页面会在这 10 分钟内持续尝试连接。
• 旧主机上的会话：这些会话保留在旧主机上，除非您将其重新添加，否则 Desktop 不会连接到该主机。要继续某个会话，请打开该会话并选择 Add SSH connection。Desktop 会填入旧主机。将其另存为一个独立的连接。

{
  "sshHostCommands": [
    {
      "id": "acme-devbox",
      "name": "Dev box",
      "command": "/usr/local/bin/acme-dev create"
    }
  ],
  "strictPluginOnlyCustomization": ["hooks"]
}

• 键放在哪里：如果您针对 Claude Code 的 MDM 策略已经设置了某个策略键，请将其放在那里。否则，请将其放在托管设置文件中。默认情况下，此类策略的优先级高于该文件，此时 Desktop 会忽略文件中的条目。即使在适用服务器托管设置的计算机上，也请在计算机上设置它：Desktop 会忽略那里以及项目和本地设置中的该键。
• id：如果用户的 sshHostCommands 条目使用了您的 id，则只有您的条目生效。如果其他任何 SSH 连接使用了它（例如用户 sshConfigs 中的连接），您的条目会显示为灰色。请选择用户不太可能使用的 id。
• 程序：请提供其完整路径，因为 Desktop 会在每个用户自己的 PATH 中查找裸名称。程序以该用户身份运行，使用其登录 shell 导出的变量。
• 用户自己的条目：Desktop 将用户的条目视同 hook，因为两者都会在计算机上运行程序。要仅允许您的条目，请将 strictPluginOnlyCustomization 设置为 ["hooks"]，或将 "hooks" 添加到其列表中。这样也会阻止来自用户、项目和本地设置的 Claude Code hook，且无法保留它们。如果您改为将该键或 allowManagedHooksOnly 设置为 true，则会阻止更多内容，具体见每个键的条目说明。
• 所有条目：要同时关闭您的条目，请在托管设置中设置 disableAllHooks。如果您设置了 disableDesktopLocalSessions，或设置了不允许任何主机的 sshHostAllowlist，选择器将不会列出任何 Create 或 Replace 项。
• 锁定在哪里生效：对于这些条目，Desktop 会从服务器托管设置以及计算机自身的文件或策略中读取 allowManagedHooksOnly、strictPluginOnlyCustomization 和 disableAllHooks，并应用更严格的结果。在 Desktop 检查 claude.ai 上的服务器托管设置之前，所有条目都保持灰色，即使您的组织没有任何服务器托管设置也是如此。
• 允许的主机：如果您设置了 sshHostAllowlist，请确保有一个模式能匹配您的工具打印的每个主机名，并且模式中不要包含 user@。Desktop 只在命令运行后才检查打印的名称，因此被列表拒绝的机器已经存在，用户必须使用您的工具将其删除。每次连接时，解析后的 HostName 也必须匹配。

• 文件：~/.claude/settings.json 包含无效的 JSON 或被 schema 拒绝的值、您拼错了键名，或者您将其放在了项目的设置中。请修复该文件。
• 平台和账户：您使用的是 Windows，或者使用的是第三方提供商而非 Claude 账户。请自行将每个主机添加为 SSH 连接。
• 您组织的设置：您的管理员关闭了本地会话或 SSH 会话。请询问他们您是否可以使用命令。
• 没有 ssh 程序：Desktop 无法在您的计算机上启动 OpenSSH 客户端。请安装它，或请您的管理员允许它，然后重启 Desktop。

• 条目中有错误：修复消息中指出的字段或命令。如果 id 已被使用，请为该条目指定另一个。
• 设置文件损坏：当您自己的设置文件损坏时，管理员的条目可能显示为灰色，并附带指出该文件的消息。修复该文件。
• 新主机：主机保存满 10 分钟后，您才能替换主机。
• hook 已关闭或受限：您自己的条目只在您自己的 hook 可以运行的地方生效。请从您的设置中移除 disableAllHooks，或询问您的管理员。
• 设置仍在加载：在 Desktop 加载您组织的服务器托管设置之前，所有条目都显示为灰色，通常在启动后几秒钟内完成。如果条目一直是灰色，请检查您与 claude.ai 的连接。

​

为您的团队预配置 SSH 连接

• 用户看到的内容：以这种方式定义的连接会自动出现在每个用户的环境选择器中。
• 用户可以更改的内容：用户可以选择托管连接，并为其设置自己的 Worktree folder。他们无法在应用中编辑其其他字段或删除它。

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519"
    }
  ]
}

​

限制用户可以连接的 SSH 主机

{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}

SSH host "bastion.example.com" is not allowed by your organization's managed settings. It is a jump host on the way to "devbox".

​

关闭本地会话并分发 SSH 连接

{
  "disableDesktopLocalSessions": true,
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "dev.example.com"
    }
  ],
  "sshHostAllowlist": ["dev.example.com"]
}

• CLI：这些键都不会阻止开发者在自己的计算机上运行 Claude Code CLI
• Cowork：这些键都不适用于 Cowork 会话或 Cowork 定时任务
• 云端会话：这些键都不会改变云端会话是否可用。若要关闭它们，请使用管理控制台控制项下的 Cloud sessions 设置。

• 主机名：确保 sshHostAllowlist 中有一个模式与每个 sshConfigs 条目的主机名（不含 user@）匹配，否则开发者将无法连接到该主机。此外，还要添加与 Desktop 在通往该主机途中检查的每台跳板主机相匹配的模式。有关 Desktop 如何匹配主机名，请参阅限制用户可以连接的 SSH 主机。
• 版本：disableDesktopLocalSessions 需要 Claude Desktop v1.37937.0 或更高版本
• 文件权限：确保计算机上每位开发者的账户都能读取托管设置文件。Desktop 不会应用账户无法读取的文件中的键，Claude Code 也会在没有这些键的情况下启动。

​

企业配置

​

管理员控制台控制

• Desktop：控制您的组织中的用户是否可以在桌面应用中访问 Claude Code
• Cloud sessions：为您的组织启用或禁用云端会话
• Remote Control：为您的组织启用或禁用 Remote Control

​

托管设置

• 此机器上的本地会话：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用符合条件的登录向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的设置优先级。
• 云端会话：接收服务器管理的设置；设备部署的文件无法到达它们，因为它们在 Anthropic 管理的虚拟机上运行。路由到自托管环境的会话也读取运行程序镜像中的托管设置文件。Claude Code 如何组合托管源说明该文件何时适用。
• SSH 会话：会话从远程主机读取托管设置文件。Desktop 本身在本地机器上读取 sshConfigs、sshHostAllowlist、disableSshSavedPasswords 和 disableDesktopLocalSessions。如果您提供多个托管源，它默认只从其中一个读取。
• Cowork 会话：在此机器上的 Cowork 会话中，Claude Code 永远不会获取管理员控制台设置，即使用户使用 Team 或 Enterprise 帐户登录，并读取部署到机器的策略，除非您的 Claude Desktop 配置设置了 requireCoworkFullVmSandbox。远程 Cowork 会话两者都不接收。请参阅策略应用的位置和时间了解哪些设备文件到达 Cowork，以及MCP 权限规则了解 Bash 和 WebFetch 规则如何应用于 Cowork 的工具。

​

设备管理策略

• macOS：通过使用 Jamf 或 Kandji 等工具的 com.anthropic.claudefordesktop 偏好域配置
• Windows：通过 SOFTWARE\Policies\Claude 处的注册表配置
• Linux：通过位于 /etc/claude-desktop/managed-settings.json 的 root 所有的文件配置，该文件以 JSON 对象形式保存策略键。如果除 root 之外的任何人可以写入该文件或其所在文件夹，Desktop 将拒绝使用该文件。它与 Claude Code 的托管设置文件是不同的文件。

​

网络访问要求

anthropic.com
*.anthropic.com
claude.ai
*.claude.ai
claude.com
*.claude.com
claude.app
*.claude.app
*.claudeusercontent.com
*.claudemcpcontent.com

anthropic.com
api.anthropic.com
a-api.anthropic.com
a-cdn.anthropic.com
s-cdn.anthropic.com
assets-proxy.anthropic.com
claude.ai
a.claude.ai
assets.claude.ai
downloads.claude.ai
*.livepreview.claude.ai
claude.com
platform.claude.com
sso.claude.com
*.livepreview.claude.app
*.claudeusercontent.com
*.claudemcpcontent.com

​

身份验证和 SSO

​

数据处理

​

部署

• macOS：通过 MDM（如 Jamf 或 Kandji）使用 .dmg 安装程序分发
• Windows：通过 MSIX 包部署。有关企业部署选项（包括静默安装），请参阅为 Windows 部署 Claude Desktop

​

来自 CLI？

claude --desktop --resume <session-id>

1. 在终端中关闭会话。
2. 在 Desktop 输入框中，输入 /resume。Desktop 列出您从 CLI 在此计算机上启动的会话。按标题、文件夹或分支搜索，并预览每个会话的停止位置。
3. 选择会话。它在应用中继续，具有完整的对话和上下文。

​

CLI 标志等效项

​

共享配置

• 项目中的 CLAUDE.md 和 CLAUDE.local.md 文件由两者共同使用
• 在 ~/.claude.json 或 .mcp.json 中配置的 MCP 服务器 在两者中均可使用
• 在设置中定义的 hook 和 skill 适用于两者
• ~/.claude.json 和 ~/.claude/settings.json 中的 设置 是共享的。权限规则、允许的工具和 settings.json 中的其他设置适用于 Desktop 会话。
• 模型：相同的模型在两者中都可用。在 Desktop 中，从输入框下方一行中的模型选择器中选择模型。您可以在会话期间从同一选择器更改模型。

​

来自 Claude Desktop 聊天应用的 MCP 服务器

​

功能比较

​

Desktop 中不可用的内容

• 第三方提供商：Desktop 默认连接到 Anthropic 的 API。要通过网关路由 Desktop，或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请按照第三方提供商行中的链接操作。
• Linux (beta)：Linux 桌面应用中尚不提供计算机使用。请参阅 Claude Desktop on Linux。
• 内联代码建议：Desktop 不提供自动完成风格的代码补全。它通过对话式提示词和显式代码更改工作，并可以在 Claude 回复后建议您的下一个提示词。
• Agent team：协调的团队（由 Claude 作为团队负责人从共享任务列表中为队友分配任务）在 CLI 中可用，不在 Desktop 中。对于一个会话内的多 Agent 工作，请使用动态工作流，它可在 Desktop 中运行；Claude 也可以直接向您的其他会话发送消息并管理它们。
• Terminal-dialog 命令：在终端中打开交互式面板的内置命令，其行为在 Code 选项卡中有所不同。直接编辑设置文件来管理权限规则和配置，或从独立 CLI 运行命令。
  • 没有参数形式的命令，例如 /permissions，会回复 isn't available in this environment。
  • /config 打开 设置 > Claude Code。

​

故障排除

​

检查你的版本

• macOS：点击菜单栏中的 Claude，然后点击 About Claude
• Windows：点击 Help，然后点击 About Claude

​

Code 选项卡中的 Claude Code 版本

​

检查您使用的布局

• 低于 v2.37337.0 的 Desktop：请更新以获取当前布局。在 macOS 上选择 Claude > Check for Updates…，或在 Windows 上选择 Help > Check for Updates…。
• 会话在您计算机上运行的第三方提供商：当前布局需要 Claude Desktop v3.1623.0 或更高版本，因此请检查您的版本。要进行更新，请在 macOS 上选择 Claude > Check for Updates…，或在 Windows 上选择 Help > Check for Updates…。如果您的组织关闭了自动更新，Check for Updates… 会被隐藏，此时请向管理员索取 v3.1623.0 或更高版本。
• 会话在您组织基础设施上运行的第三方提供商：当您的组织在其自己的基础设施上而不是在您的计算机上运行会话时，Desktop 会保留早期布局，更新不会改变布局。如果您不清楚会话在哪里运行，请询问管理员。

​

Code 选项卡中的 403 或身份验证错误

1. 从应用菜单中注销并重新登录。这是最常见的修复。
2. 验证你有活跃的付费订阅：Pro、Max、Team 或 Enterprise。
3. 如果 CLI 工作但 Desktop 不工作，完全退出桌面应用，而不仅仅是关闭窗口，然后重新打开并登录。
4. 检查你的互联网连接和代理设置。

​

启动时屏幕空白或卡住

1. 重启应用。
2. 检查待处理的更新。在 macOS 和 Windows 上，应用在启动时自动更新；在 Linux 上，通过 apt 更新，如 Claude Desktop on Linux 中所述。
3. 在托管网络上，确认你的防火墙允许网络访问要求中的 CDN 主机。
4. 在 Windows 上，在 Windows 日志 → 应用程序 下的事件查看器中检查崩溃日志。

​

“Failed to load session”

​

会话找不到已安装的工具

​

Git 和 Git LFS 错误

​

MCP servers 在 Windows 上不工作

​

SSH host key verification failed

• 在 Couldn't connect to <host> 卡片的 View details 下出现 SSH host key verification failed 或 Host denied (verification failed)
• 在输入框旁边或执行 Test connection 后出现 Connection failed: Host key changed or not trusted
• 在已断开的会话上出现 <host>'s host key is not trusted 或 <host>'s host key has changed

• 您使用的是 Windows，且 Desktop 显示 Connection failed: Host key changed or not trusted：首先排除缺少 OpenSSH 客户端的情况
• Desktop 提示您设置 UserKnownHostsFile：在 ~/.ssh/config 中将其设置为 ~/.ssh/known_hosts，然后从终端检查密钥
• 您看到 Review new key 按钮：选择该按钮，并将 Desktop 显示的指纹与该机器自身的指纹进行比较。如果两者匹配，请选择 Trust new key 以替换已保存的密钥。否则请选择 Cancel。
• 您没有看到 Review new key 按钮、Desktop 显示 Couldn't show the new key，或者在 Trust new key 之后 Desktop 再次拒绝密钥：从终端检查密钥

​

从终端检查主机密钥

• ssh 询问是否继续连接：将其显示的指纹与该机器自身的指纹进行比较。仅当两者匹配时才回答 yes。
• ssh 警告主机密钥已更改：将警告中的指纹与该机器自身的指纹进行比较。仅当两者匹配时，才删除 Offending <type> key in <file>:<line> 所指出的那一行，然后重新运行 ssh。如果 ssh 再次就另一行发出警告，请按照同样的方式比较、删除并重新运行。
• ssh 未经询问就拒绝了它不认识的密钥：从该机器的管理人员处获取该机器的 known_hosts 行，不要通过您正在检查的连接获取。将该行添加到您的 known_hosts 文件中，并使用 ssh 消息中的名称作为其主机名，然后重新运行 ssh。
• ssh 没有询问主机密钥就继续登录：先不要输入密码。检查 ssh 已信任的密钥。

• 跳板主机没有 Server host key: 行：同时运行 ssh -v -S none <jump host>，并以同样的方式比较该指纹。
• 某个指纹不匹配，或者您无法检查它：不要再次连接。删除已保存的密钥：在 Host '<name>' is known 下方，Found key in <file>:<line> 行指出了保存该密钥的文件。运行 ssh-keygen -R "<name>" -f <file>。如果您将主机密钥保存在多个文件中，请从每个文件中删除该密钥。如果您无法修改某个文件，请告知您计算机的管理人员。
• 所有指纹都匹配：在 Desktop 中重试。如果 Desktop 再次拒绝该密钥，请参阅获取 SSH 问题的 Desktop 日志。

​

在没有 OpenSSH 客户端的 Windows 上 SSH 主机密钥被拒绝

​

登录后 SSH 连接失败

​

获取 SSH 问题的 Desktop 日志

• macOS：Show Logs in Finder
• Windows：Show Logs in File Explorer
• Linux：Show Logs in File Manager

​

应用无法退出

• macOS：按 Cmd+Q。如果应用不响应，使用 Cmd+Option+Esc 强制退出，选择 Claude，然后点击强制退出。
• Windows：使用 Ctrl+Shift+Esc 的任务管理器来结束 Claude 进程。

​

Windows 特定问题

• 安装后 PATH 未更新：打开新的终端窗口。PATH 更新仅适用于新的终端会话。
• 并发安装错误：如果你看到关于另一个安装正在进行的错误，但实际上没有，尝试以管理员身份运行安装程序。

​

在 CLI 中打开时”Branch doesn’t exist yet”

git fetch origin <branch-name>
git checkout <branch-name>

​

仍然卡住？

• 在桌面应用中打开 Help → Get Support，或直接访问 Claude 支持中心
• 对于在独立 claude CLI 中也能重现的问题，在 GitHub Issues 上搜索或提交错误