桌面应用

充分发挥 Claude Code 桌面版的潜力：支持 Git 隔离的并行会话、可拖拽的窗格布局、集成终端与文件编辑器、侧边对话、计算机使用、手机端发起 Dispatch 会话、可视化差异审查、应用预览、PR 监控、连接器以及企业配置。

Claude 桌面应用有三个标签页：Chat 用于对话，Cowork 用于 Dispatch 和长时间代理任务，Code 用于软件开发。本页面是 Code 标签页的参考文档。

对于 Windows ARM64，请下载 ARM64 安装程序。在 Linux 上，使用 apt 安装；详见 Claude Desktop on Linux。

安装完成后，启动 Claude，登录并点击 Code 标签页。首次在 Windows 上打开时，需要安装 Git for Windows；安装完成后重启应用。如需首次会话的详细 walkthrough，请参阅 快速入门指南。

在 Code 标签页中，每次对话都是一个会话：它拥有独立的聊天记录、项目文件夹和代码变更，与其他会话互不干扰。侧边栏列出你的会话，并支持并行运行多个会话。在会话中，你可以：

• 审查差异并添加评论，然后 通过 CI 监控生成的 PR
• 在 Browser 窗格中 预览运行中的应用，同时 Claude 自动验证其变更，并可在旁边 打开外部网站
• 排列窗格，将聊天、差异、浏览器、终端和文件编辑器并排布局
• 提出 侧边问题，使用会话上下文而不干扰主会话
• 连接外部工具，如 GitHub、Slack 和 Linear
• 让 Claude 打开应用并控制你的屏幕
• 在你的机器上、云端 或通过 SSH 运行

关于 定时重复任务、键盘快捷键 或 从手机发送任务，请参阅链接页面和章节。如果你已在使用基于终端的 CLI，请参阅 CLI 对比 了解哪些功能可以迁移。

启动会话

在发送第一条消息之前，在提示区域配置四项内容：

• 环境：选择 Claude 的运行位置。选择 Local（本地）在你的机器上运行，Remote（远程）在 Anthropic 托管的云会话中运行，或选择 SSH 连接 以连接你管理的远程机器。详见 环境配置。
• 项目文件夹：选择 Claude 工作的文件夹或仓库。对于云会话，你可以添加 多个仓库。
• 模型：从发送按钮旁边的下拉菜单中选择 模型。你可以在会话期间随时更改。
• 权限模式：从 模式选择器 中选择 Claude 的自主程度。你可以在会话期间随时更改。

输入你的任务并按 Enter 启动。每个会话独立跟踪自己的上下文和变更。

与代码协作

为 Claude 提供正确的上下文，控制它的自主程度，并审查它的修改。

使用提示框

输入你希望 Claude 执行的内容并按 Enter 发送。Claude 会根据你的 权限模式 读取项目文件、做出修改并运行命令。你可以随时重定向 Claude：点击停止按钮立即中断，或输入更正内容并按 Enter 发送，无需停止正在运行的操作。Claude 在当前操作完成后立即读取更正内容，并在下一步之前进行调整。

提示框旁边的 + 按钮让你可以访问文件附件、技能、连接器 和 插件。

向提示添加文件和上下文

提示框支持两种引入外部上下文的方式：

• @mention 文件：输入 @ 后跟文件名，将该文件添加到对话上下文中。Claude 随后可以读取并引用该文件。@mention 在云会话中不可用。
• 附加文件：使用附件按钮附加图片、PDF 和其他文件到提示中，或直接将文件拖放到提示框中。这对于分享错误截图、设计模型或参考文档非常有用。

选择权限模式

权限模式控制 Claude 在会话期间的自主程度：是否在编辑文件、运行命令或两者之前询问。你可以随时使用发送按钮旁边的模式选择器切换模式。新手建议从 Manual 开始，以准确了解 Claude 的操作，然后随着熟悉程度提升切换到 Accept edits 或 Plan。

早期版本的 Code 标签页将这些模式标记为 Ask permissions、Auto accept edits 和 Plan mode。

dontAsk 权限模式仅在 CLI 中可用。

Auto 模式是一项面向所有 Anthropic API 用户的研究预览功能，需要 Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在将 Desktop 路由到 Google Cloud Agent Platform 的企业部署中，auto 模式默认关闭，直到你 设置 CLAUDE_CODE_ENABLE_AUTO_MODE，且仅支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。

云会话支持 Accept edits、Plan 和 Auto 模式。Accept edits 对应 default 模式：云会话预先批准文件编辑，因此选择器显示 Accept edits 而非 Manual。Bypass permissions 不可用，因为云环境已经是沙盒化的。

企业管理员可以限制可用的权限模式。详见 企业配置。

预览你的应用

Claude 可以启动开发服务器并在 Browser 窗格中打开它，以验证其变更。这适用于前端 Web 应用和后端服务器：Claude 可以测试 API 端点、查看服务器日志并迭代发现的问题。在大多数情况下，Claude 在编辑项目文件后会自动启动服务器。你也可以随时要求 Claude 进行预览。默认情况下，Claude 在每次编辑后 自动验证 变更。

Browser 窗格还可以打开项目中的静态 HTML 文件、PDF、图片和视频。点击聊天中的 HTML、PDF、图片或视频路径即可在其中打开。

在 Browser 窗格中，你可以：

• 直接在 Browser 窗格中与运行中的应用交互
• 观看 Claude 自动验证其自身变更：它会截图、检查 DOM、点击元素、填写表单并修复发现的问题
• 从会话工具栏的服务器下拉菜单中启动或停止服务器
• 通过在下拉菜单中选择 Persist sessions，在服务器重启后保持 cookie 和本地存储，这样你在开发过程中无需重新登录
• 编辑服务器配置或一次性停止所有服务器

Claude 根据你的项目创建初始服务器配置。如果你的应用使用自定义开发命令，请编辑 .claude/launch.json 以匹配你的设置。完整参考请参阅 配置预览服务器。

要清除保存的会话数据，或完全关闭 Browser，请使用 Settings → Claude Code 中的开关。

浏览外部网站

Browser 窗格是一个标签式浏览器，因此你可以在运行中的应用旁边打开文档、问题跟踪器或任何其他网站。要打开 Browser，在 macOS 上按 Cmd+Shift+B，在 Windows 上按 Ctrl+Shift+B，或从 Views 菜单中选择。当你点击聊天中的外部链接时，会出现选择器提供 Open in app（使用 Browser 窗格）或 Default browser（使用你自己的浏览器）；在 macOS 上 Cmd-点击或在 Windows 上 Ctrl-点击可直接在你的系统浏览器中打开链接。你可以在窗格中登录网站，包括 Google OAuth 等弹出式登录流程。

Claude 可以使用与 验证你的应用 相同的工具来读取和交互外部页面，并有两项额外的安全检查：

• 安全分类器会审查 Claude 在外部页面上的写入操作（如点击和输入），适用于每种权限模式。这些分类器与 auto 模式 使用的相同，当它们标记某个操作时，无论模式如何你都会收到权限提示。
• 在 Auto 和 Bypass permissions 以外的权限模式下，在 Claude 导航到新网站之前还会应用域名白名单检查。

批准 Claude 在网站上的操作

Claude 首次在某个外部网站上操作时，会出现权限卡片，Claude 等待你的选择：Allow once（允许一次）、Always allow（始终允许）或 Deny（拒绝）。Allow once 批准操作但不保存任何内容。Always allow 在你的设备上保存对该网站的批准，你可以在 Settings 中撤销。每个网站都需要自己的批准，包括子域名。你的本地开发服务器和项目文件不需要批准，因此 自动验证 可以无提示地继续工作。

即使在已批准的网站上，Claude 也不会在没有你输入的情况下购买物品、创建账户或绕过 CAPTCHA。在 Browser 窗格中浏览使用的安全模型与 Claude in Chrome 扩展 相同。关于 Claude 如何处理敏感网站和风险操作，请参阅 安全使用 Claude in Chrome。

在 Browser 和 Chrome 扩展之间选择

Browser 窗格使用干净的浏览器配置文件，与你的个人浏览器分离，不包含你保存的登录信息或历史记录。将它用于构建和测试你的应用，以及不需要你身份信息的网站。当你希望 Claude 在你已登录的会话中作为你本人操作时，请改用 Claude in Chrome 扩展，它会共享你浏览器的登录状态。

为组织限制外部浏览

Browser 遵循与 Claude in Chrome 扩展相同的 网站白名单和黑名单控制。如果你的组织已为扩展配置了这些列表，Browser 会自动遵循它们。管理员还可以使用 browserExternalPageTools 托管设置 关闭 Claude 在外部页面上的工具。禁用工具后，用户仍然可以导航到外部网站；Claude 的工具无法读取或操作它们。

使用差异视图审查变更

Claude 修改代码后，差异视图让你在创建拉取请求之前逐文件审查修改。

当 Claude 修改文件时，会出现差异统计指示器，显示添加和删除的行数，例如 +12 -1。点击此指示器打开差异查看器，左侧显示文件列表，右侧显示每个文件的变更。

要对特定行添加评论，点击差异中的任意行打开评论框。输入你的反馈并按 Enter 添加评论。在多个行添加评论后，一次性提交所有评论：

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

Claude 读取你的评论并做出请求的修改，这些修改会以新的差异形式呈现供你审查。

审查你的代码

在差异视图中，点击右上角的工具栏中的 Review code 按钮，要求 Claude 在提交前评估变更。Claude 检查当前的差异并直接在差异视图中留下评论。你可以回复任何评论或要求 Claude 修改。

审查重点关注高信号问题：编译错误、确定的逻辑错误、安全漏洞和明显的 bug。它不会标记样式、格式、预存在的问题或 linter 能捕获的内容。

监控拉取请求状态

在你打开拉取请求后，会话中会出现 CI 状态栏。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败项。

• Auto-fix：启用后，Claude 自动尝试通过读取失败输出并迭代来修复失败的 CI 检查。
• Auto-merge：启用后，当所有检查通过时 Claude 自动合并 PR。合并方式为 squash。Auto-merge 必须在你的 GitHub 仓库设置中 启用 才能生效。

使用 CI 状态栏中的 Auto-fix 和 Auto-merge 开关来启用任一选项。Claude Code 在 CI 完成后还会发送桌面通知。要在 PR 合并或关闭后自动归档会话，请在 Settings → Claude Code 中开启 auto-archive。

安排你的工作区

Code 标签页围绕可任意布局的窗格构建：聊天、差异、浏览器、终端、文件、计划、任务和子代理。通过拖拽窗格标题来重新定位，或拖拽窗格边缘来调整大小。在 macOS 上按 Cmd+\ 或在 Windows 上按 Ctrl+\ 关闭聚焦的窗格。从会话工具栏的 Views 菜单中打开额外的窗格。

在终端中运行命令

集成终端让你无需切换到其他应用即可在会话旁边运行命令。从 Views 菜单打开它，或在 macOS 和 Windows 上按 Ctrl+`。终端在你的会话工作目录中打开，并与 Claude 共享相同的环境，因此 npm test 或 git status 等命令可以看到 Claude 正在编辑的相同文件。要打开第二个终端标签页，点击终端窗格标题中的 + 按钮，或在聊天中右键点击文件夹选择 Open in terminal。终端仅在本地会话中可用。

打开并编辑文件

点击聊天或差异查看器中的文件路径，在文件窗格中打开它。HTML、PDF、图片和视频路径改为在 Browser 窗格 中打开。进行局部编辑并点击 Save 写回。如果文件自打开后在磁盘上发生了变更，窗格会警告你并让你选择覆盖或放弃。点击 Discard 撤销你的编辑，或点击窗格标题中的路径复制绝对路径。

文件窗格在本地和 SSH 会话中可用。对于云会话，请让 Claude 做出修改。

在其他应用中打开文件

在聊天、差异查看器或文件窗格中右键点击任何文件路径，打开上下文菜单：

• Attach as context：将该文件添加到你的下一个提示中
• Open in：在已安装的编辑器（如 VS Code、Cursor 或 Zed）中打开文件
• Show in Finder（macOS）或 Show in Explorer（Windows）：打开包含文件夹
• Copy path：复制绝对路径到剪贴板

切换视图模式

视图模式控制聊天记录中显示的详细程度。从发送按钮旁边的 Transcript view 下拉菜单切换模式，或在 macOS 和 Windows 上按 Ctrl+O 循环切换。

在调试 Claude 为何采取特定操作时使用 Verbose。在运行多个会话并想快速扫描结果时使用 Summary。

键盘快捷键

在 macOS 上按 Cmd+/ 或在 Windows 上按 Ctrl+/ 查看 Code 标签页中所有可用的快捷键。在 Windows 上，以下快捷键使用 Ctrl 代替 Cmd。会话循环、终端切换和视图模式切换在每个平台都使用 Ctrl。

这些快捷键仅适用于 Code 标签页。基于终端的 交互模式快捷键（如 Shift+Tab 循环模式）在 Desktop 中不适用。

检查使用量

点击模型选择器旁边的使用量环，查看当前会话的上下文窗口使用量以及本周期内的计划使用量。上下文使用量按会话计算；计划使用量在你所有 Claude Code 界面之间共享。

让 Claude 使用你的计算机

计算机使用功能让 Claude 打开你的应用、控制你的屏幕，并像你一样直接在你的机器上工作。让 Claude 在移动模拟器中测试原生应用、与没有 CLI 的桌面工具交互，或自动化仅通过 GUI 才能完成的操作。

计算机使用默认关闭。在 Claude 可以控制你的屏幕之前，先在 Settings 中启用 它。在 macOS 上，你还需要授予辅助功能和屏幕录制权限。

计算机使用的适用场景

Claude 有多种方式与应用或服务交互，计算机使用是最广泛且最慢的方式。它会先尝试最精确的工具：

• 如果你有某个服务的 连接器，Claude 会使用连接器。
• 如果任务是 shell 命令，Claude 会使用 Bash。
• 如果任务是浏览器操作且你已设置 Claude in Chrome，Claude 会使用它。
• 如果以上都不适用，Claude 会使用计算机使用。

按应用的访问层级 强化了这一点：浏览器限制为仅查看，终端和 IDE 限制为仅点击，引导 Claude 使用专用工具，即使计算机使用已激活。屏幕控制保留给其他工具无法触及的内容，如原生应用、硬件控制面板、移动模拟器或没有 API 的专有工具。

启用计算机使用

计算机使用默认关闭。如果你要求 Claude 执行需要它的操作而它处于关闭状态，Claude 会告诉你如果在 Settings 中启用计算机使用就可以执行该任务。

应用权限

Claude 首次需要使用某个应用时，会话中会出现提示。点击 Allow for this session（允许本次会话）或 Deny（拒绝）。批准对当前会话有效，在 Dispatch 生成的会话 中持续 30 分钟。

提示还显示 Claude 对该应用获得的控制级别。这些层级由应用类别固定，不可更改：

影响范围广泛的应用（如终端、Finder 或文件资源管理器、System Settings 或 Settings）在提示中会显示额外警告，让你了解批准它们会授予什么权限。

你可以在 Settings > General（在 Desktop app 下）配置两项设置：

• Denied apps（拒绝的应用）：在此处添加应用，以在提示时自动拒绝它们。Claude 可能仍会通过允许应用中的操作间接影响被拒绝的应用，但无法直接与被拒绝的应用交互。
• Unhide apps when Claude finishes（Claude 完成后取消隐藏应用）：当 Claude 工作时，你的其他窗口会被隐藏，以便它只与批准的应用交互。当 Claude 完成时，隐藏的窗口会恢复，除非你关闭此设置。

管理会话

每个会话都是独立的对话，拥有自己的上下文和变更。你可以并行运行多个会话，分支侧边对话，将工作发送到云端，或让 Dispatch 从手机为你启动会话。

使用会话并行工作

点击侧边栏中的 + New session，或在 macOS 上按 Cmd+N 或在 Windows 上按 Ctrl+N，以并行处理多个任务。按 Ctrl+Tab 和 Ctrl+Shift+Tab 在侧边栏中的会话之间循环。对于 Git 仓库，每个会话使用 Git worktrees 获得项目的独立副本，因此一个会话中的变更不会影响其他会话，直到你提交它们。

要同时查看两个会话，在 macOS 上按住 Cmd 或在 Windows 上按住 Ctrl 并点击侧边栏中的会话。该会话会在第二个窗格中打开，与你已打开的窗格并排。在分屏激活期间，点击另一个侧边栏会话会替换当前聚焦的窗格。在 macOS 上按 Cmd+\ 或在 Windows 上按 Ctrl+\ 关闭聚焦的窗格并返回单个会话。

Worktrees 默认存储在 <project-root>/.claude/worktrees/ 中。你可以在 Settings → Claude Code 下的 "Worktree location" 中将其更改为自定义目录。你还可以设置一个分支前缀，它会添加到每个 worktree 分支名称之前，这对于保持 Claude 创建的分支有序很有用。要在你完成后移除 worktree，将鼠标悬停在侧边栏中的会话上并点击归档图标。要让会话在它们的拉取请求合并或关闭时自动归档，请在 Settings → Claude Code 中开启 Auto-archive after PR merge or close。Auto-archive 仅适用于已完成运行的本地会话。

要在新的 worktrees 中包含被 gitignore 的文件（如 .env），请在项目根目录创建 .worktreeinclude 文件。

使用侧边栏顶部的控件按状态、项目或环境过滤会话，并按项目分组会话。要重命名会话，点击活动会话顶部工具栏中的会话标题。要检查上下文使用量，请参阅 检查使用量。当上下文填满时，Claude 会自动总结对话并继续工作。你也可以输入 /compact 提前触发总结以释放上下文空间。关于 compact 如何工作的详细信息，请参阅 上下文窗口。

当 Code 会话完成任务且你当前未查看该会话时，桌面应用会发送 OS 通知。

提出不干扰主会话的侧边问题

侧边对话让你可以问 Claude 一个使用会话上下文但不会向主对话添加任何内容的问题。当你想理解一段代码、检查一个假设或探索一个想法而不让会话偏离轨道时使用它。

在 macOS 上按 Cmd+; 或在 Windows 上按 Ctrl+; 打开侧边对话，或在提示框中输入 /btw。侧边对话可以读取主线程中截至该点的所有内容。完成后，关闭侧边对话并继续主会话。侧边对话在本地和 SSH 会话中可用。

查看后台任务

任务窗格显示当前会话中运行的后台工作：子代理、后台 shell 命令和 动态工作流。从 Views 菜单打开它，或将其拖入你的布局。

点击任何条目以在子代理窗格中查看其输出或停止它。要查看其他会话在做什么，请使用 侧边栏。

远程运行长时间任务

对于大型重构、测试套件、迁移或其他长时间运行的任务，启动会话时选择 Remote 而非 Local。云会话在 Anthropic 的云基础设施上运行，即使你关闭应用或关闭计算机也会继续。随时回来查看进度或将 Claude 引导到不同方向。你还可以从 claude.ai/code 或 Claude iOS 应用监控云会话。

云会话还支持多个仓库。选择云环境后，点击仓库 pill 旁边的 + 按钮将额外的仓库添加到会话中。每个仓库都有自己的分支选择器。这对于跨多个代码库的任务很有用，例如更新共享库及其使用者。

关于云会话如何工作的更多内容，请参阅 Claude Code on the web。

在其他界面中继续

从会话工具栏右下角的 VS Code 图标访问的 Continue in 菜单，让你可以将会话移动到另一个界面：

• Claude Code on the Web：将你的本地会话发送到远程继续运行。Desktop 推送你的分支，生成对话摘要，并创建一个具有完整上下文的新云会话。然后你可以选择归档本地会话或保留它。这需要干净的工作树，且对 SSH 会话不可用。
• Your IDE：在你当前的 working directory 打开你的项目到支持的 IDE 中。

来自 Dispatch 的会话

Dispatch 是 Claude 的一个持久对话，位于 Cowork 标签页中。你向 Dispatch 发送一个任务，它会决定如何处理。

任务最终成为 Code 会话有两种方式：你直接要求一个，例如 "open a Claude Code session and fix the login bug"，或者 Dispatch 判断该任务是开发工作并自行生成一个。通常会路由到 Code 的任务包括修复 bug、更新依赖、运行测试或打开拉取请求。研究、文档编辑和电子表格工作保留在 Cowork 中。

无论哪种方式，Code 会话都会出现在 Code 标签页的侧边栏中，并带有 Dispatch 徽章。当它完成或需要你的批准时，你会在手机上收到推送通知。

如果你已启用 计算机使用，Dispatch 生成的 Code 会话也可以使用它。这些会话中的应用批准在 30 分钟后过期并重新提示，而不是像常规 Code 会话那样持续整个会话。

关于设置、配对和 Dispatch 设置，请参阅 Dispatch 帮助文章。Dispatch 需要 Pro 或 Max 计划，Team 或 Enterprise 计划不可用。

Dispatch 是几种在远离终端时与 Claude 协作的方式之一。请参阅 平台和集成 将其与 Remote Control、Channels、Slack 和定时任务进行比较。

扩展 Claude Code

连接外部服务，添加可复用工作流，自定义 Claude 的行为，并配置预览服务器。要在一个地方管理连接器、技能和插件，请点击侧边栏中的 Customize。

连接外部工具

对于本地和 SSH 会话，点击提示框旁边的 + 按钮并选择 Connectors 来添加 Google Calendar、Slack、GitHub、Linear、Notion 等集成。你可以在会话之前或期间添加连接器。+ 按钮在云会话中不可用，但 routines 在创建 routine 时配置连接器。

要管理或断开连接器，请在桌面应用中前往 Settings → Connectors，或从提示框中的 Connectors 菜单选择 Manage connectors。

连接后，Claude 可以读取你的日历、发送消息、创建 issue 并直接与你的工具交互。你可以询问 Claude 你的会话中配置了哪些连接器。

连接器是带有图形化设置流程的 MCP 服务器。将它们用于与受支持服务的快速集成。对于 Connectors 中未列出的集成，通过 settings files 手动添加 MCP 服务器。你还可以 创建自定义连接器。

使用技能

技能 扩展了 Claude 的能力。Claude 在相关时自动加载它们，或者你可以直接调用一个：在提示框中输入 / 或点击 + 按钮并选择 Slash commands 浏览可用内容。这包括 内置命令、你的 自定义技能、代码库中的项目技能以及任何 已安装插件 的技能。选择一个后，它会高亮显示在输入框中。在其后输入你的任务并照常发送。

安装插件

插件 是可复用的包，为 Claude Code 添加技能、代理、hooks、MCP 服务器和 LSP 配置。你可以直接从桌面应用安装插件，无需使用终端。

对于本地和 SSH 会话，点击提示框旁边的 + 按钮并选择 Plugins 查看你已安装的插件及其技能。要添加插件，从子菜单中选择 Add plugin 打开插件浏览器，它显示来自你配置的 市场 的可用插件，包括官方 Anthropic 市场。选择 Manage plugins 来启用、禁用或卸载插件。

插件可以限定到你的用户账户、特定项目或仅本地。如果你的组织集中管理插件，这些插件在桌面会话中的可用方式与 CLI 中相同。插件对云会话不可用。关于创建你自己的插件的完整插件参考，请参阅 plugins。

配置预览服务器

Claude 自动检测你的开发服务器设置，并将配置存储在你启动会话时选择的文件夹根目录的 .claude/launch.json 中。Preview 使用该文件夹作为其工作目录，因此如果你选择了父文件夹，子文件夹中的开发服务器不会被自动检测。要使用子文件夹的服务器，请直接在该文件夹中启动会话，或手动添加配置。

要自定义服务器的启动方式，例如使用 yarn dev 而非 npm run dev 或更改端口，请手动编辑文件或点击服务器下拉菜单中的 Edit configuration 在你的代码编辑器中打开它。该文件支持带注释的 JSON。

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

你可以定义多个配置来从同一个项目运行不同的服务器，例如前端和 API。示例请参阅下方的 examples。

自动验证变更

当 autoVerify 启用时，Claude 在编辑文件后自动验证代码变更。它会截图、检查错误并确认变更有效，然后才完成回复。

Auto-verify 默认开启。通过向 .claude/launch.json 添加 "autoVerify": false 按项目禁用它，或从服务器下拉菜单中切换。

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [...]
}

禁用后，预览工具仍然可用，你可以随时要求 Claude 进行验证。Auto-verify 在每次编辑后自动执行。

配置字段

configurations 数组中的每个条目接受以下字段：

何时使用 program 与 runtimeExecutable

使用 runtimeExecutable 配合 runtimeArgs 通过包管理器启动开发服务器。例如，"runtimeExecutable": "npm" 配合 "runtimeArgs": ["run", "dev"] 运行 npm run dev。

当你有一个要直接用 node 运行的独立脚本时，使用 program。例如，"program": "server.js" 运行 node server.js。使用 args 传递额外的标志。

端口冲突

autoPort 字段控制当你的首选端口已被占用时会发生什么：

• true：Claude 自动查找并使用一个空闲端口。适用于大多数开发服务器。
• false：Claude 报错失败。当你的服务器必须使用特定端口时使用，例如用于 OAuth 回调或 CORS 白名单。
• 未设置（默认）：Claude 询问服务器是否需要该确切端口，然后保存你的回答。

当 Claude 选择不同的端口时，它通过 PORT 环境变量将分配的端口传递给你的服务器。

示例

这些配置展示了不同项目类型的常见设置：

{
  "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
    }
  ]
}

环境配置

你在 启动会话 时选择的环境决定了 Claude 的执行位置和连接方式：

• Local：在你的机器上运行，直接访问你的文件
• Remote：在 Anthropic 的云基础设施上运行。即使你关闭应用，会话也会继续。
• SSH：通过 SSH 连接到你管理的远程机器，如你自己的服务器、云 VM 或开发容器

本地会话

桌面应用并不总是继承你的完整 shell 环境。在 macOS 上，当你从 Dock 或 Finder 启动应用时，它会读取你的 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）以提取 PATH 和一组固定的 Claude Code 变量，但你在那里导出的其他变量不会被获取。在 Windows 上，应用继承用户和系统环境变量，但不读取 PowerShell 配置文件。

要在任何平台上为本地会话和开发服务器设置环境变量，打开提示框中的环境下拉菜单，将鼠标悬停在 Local 上，点击齿轮图标打开本地环境编辑器。你在此处保存的变量会加密存储在你的机器上，并适用于你启动的每个本地会话和预览服务器。你还可以将变量添加到 ~/.claude/settings.json 文件中的 env 键，尽管这些变量只到达 Claude 会话而不到达开发服务器。支持的变量完整列表请参阅 环境变量。

Extended thinking 默认启用，这可以提升复杂推理任务的性能但会使用额外的 token。要禁用 thinking，请在本地环境编辑器中将 MAX_THINKING_TOKENS 设置为 0；这对 Fable 5 无效，它始终使用 extended thinking。在 第三方提供商 上，0 会省略 thinking 参数，而 adaptive-reasoning 模型可能仍会思考。在具有 adaptive reasoning 的模型上，任何其他 MAX_THINKING_TOKENS 值都会被忽略，因为 adaptive reasoning 控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，将 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING 设置为 1 以使用固定的 thinking budget；Fable 5、Sonnet 5 和 Opus 4.7 及更高版本始终使用 adaptive reasoning，没有固定 budget 模式。

云会话

云会话在后台继续，即使你关闭应用。使用量计入你的 订阅计划限制，没有单独的计算费用。

你可以创建具有不同网络访问级别和环境变量的自定义云环境。启动云会话时选择环境下拉菜单并选择 Add environment。关于配置网络访问和环境变量的详细信息，请参阅 云环境。

SSH 会话

SSH 会话让你在远程机器上运行 Claude Code，同时使用桌面应用作为界面。这对于处理位于云 VM、开发容器或具有特定硬件或依赖项的服务器上的代码库很有用。

要添加 SSH 连接，点击启动会话前的环境下拉菜单并选择 + Add SSH connection。对话框要求输入：

• Name：此连接的友好标签
• SSH Host：user@hostname 或 ~/.ssh/config 中定义的主机
• SSH Port：如果留空默认为 22，或使用你的 SSH 配置中的端口
• Identity File：你的私钥路径，如 ~/.ssh/id_rsa。留空以使用默认密钥或你的 SSH 配置。

添加后，连接会出现在环境下拉菜单中。选择它以在该机器上启动会话。Claude 在远程机器上运行，可以访问其文件和工具。

远程机器必须运行 Linux 或 macOS。Desktop 在你首次连接时自动在远程机器上安装 Claude Code。连接后，SSH 会话支持权限模式、连接器、插件和 MCP 服务器。

为团队预配置 SSH 连接

管理员可以通过向 managed settings 文件添加 sshConfigs 来向团队成员分发 SSH 连接。以这种方式定义的连接会自动出现在每个用户的环境下拉菜单中，并显示为托管的，因此用户可以选择它们但无法在应用中编辑或删除。

以下示例预配置了一个在远程主机的 ~/projects 中打开的连接：

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

每个条目需要 id、name 和 sshHost。sshPort、sshIdentityFile 和 startDirectory 字段是可选的。用户还可以在他们自己的 ~/.claude/settings.json 中添加 sshConfigs，这是通过对话框添加的连接存储的位置。

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

管理员可以通过向 managed settings 文件添加 sshHostAllowlist 来将 Desktop 的 SSH 会话限制为经批准的主机集。设置后，用户只能连接到其解析后的主机名匹配其中一个模式的主机。将其设置为空数组以完全禁用 SSH 会话。

以下示例允许连接到 devboxes.example.com 下的任何主机以及单个指定的 bastion 主机：

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

模式不区分大小写。* 匹配任何主机，*.example.com 匹配 example.com 和任何子域名。其他内容为精确匹配。检查针对 ~/.ssh/config 解析后的主机名通过 ssh -G 运行，因此只要解析后的 HostName 匹配，就允许 Host 别名和 ProxyCommand/ProxyJump 条目。

sshHostAllowlist 仅从 managed settings 读取；用户或项目设置中的值会被忽略。只有 Claude Desktop 应用遵循此设置；Claude Code CLI 和 IDE 扩展不读取它，它也不限制通过 Bash 工具运行的 ssh 命令。它管理 Desktop 应用连接到的主机，而非网络出口，因此如果你需要硬边界，请将其与组织的网络或零信任控制配对使用。

企业配置

Team 或 Enterprise 计划的组织可以通过管理员控制台控制、托管设置文件和设备管理策略来管理桌面应用行为。

管理员控制台控制

这些设置通过 admin settings console 配置：

• Code in the desktop：控制组织中的用户是否可以访问桌面应用中的 Claude Code
• Code in the web：为组织启用或禁用 web sessions
• Remote Control：为组织启用或禁用 Remote Control
• Disable Bypass permissions mode：防止组织中的用户启用绕过权限模式

托管设置

托管设置覆盖项目和用户设置，并适用于 Desktop 中的 Claude Code 会话。你可以在组织的 managed settings 文件中设置这些键，或通过管理员控制台远程推送它们。

哪些托管设置到达 Desktop 会话取决于该会话的运行位置。模型限制如 availableModels 在 Desktop 的 Claude Code 会话中的执行方式与终端 CLI 相同；请参阅 surface coverage。

• 此机器上的本地会话：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也会在这些会话上到达 Anthropic 的 API，当会话使用组织登录或直接配置的 API 密钥认证时，遵循与终端 CLI 相同的 设置优先级。
• 云会话：在 Anthropic 管理的 VM 上运行，仅接收 server-managed settings。
• SSH 会话：会话从远程主机读取托管设置文件。Desktop 本身在创建连接时从本地机器的托管设置读取 sshConfigs 和 sshHostAllowlist。

permissions.disableBypassPermissionsMode 和 disableAutoMode 在用户和项目设置中也有效，但将它们放在托管设置中可防止用户覆盖。autoMode 从用户设置、.claude/settings.local.json 和托管设置读取，但不从已检入的 .claude/settings.json 读取：克隆的仓库不能注入自己的分类器规则。关于仅托管设置（包括 allowManagedPermissionRulesOnly 和 allowManagedHooksOnly）的完整列表，请参阅 managed-only settings。

设备管理策略

IT 团队可以通过 macOS 上的 MDM 或 Windows 上的组策略来管理桌面应用。可用策略包括启用或禁用 Claude Code 功能、控制自动更新和设置自定义部署 URL。

• macOS：通过 com.anthropic.claudefordesktop 偏好域使用 Jamf 或 Kandji 等工具配置
• Windows：通过 SOFTWARE\Policies\Claude 注册表配置

认证和 SSO

Enterprise 组织可以要求所有用户使用 SSO。计划级别的详细信息请参阅 authentication，SAML 和 OIDC 配置请参阅 Setting up SSO。

数据处理

Claude Code 在本地会话中本地处理你的代码，或在云会话中在 Anthropic 的云基础设施上处理。对话和代码上下文会发送到 Anthropic 的 API 进行处理。关于数据保留、隐私和合规性的详细信息请参阅 data handling。

部署

Desktop 可以通过企业部署工具分发：

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

关于网络配置（如代理设置、防火墙白名单和 LLM 网关），请参阅 network configuration。

完整的企业配置参考请参阅 enterprise configuration guide。

从 CLI 迁移？

如果你已经在使用 Claude Code CLI，Desktop 运行相同的底层引擎，但提供图形界面。你可以在同一个机器上同时运行两者，甚至在同一个项目上。每个都维护独立的会话历史，但通过 CLAUDE.md 文件共享配置和项目记忆。

要将 CLI 会话移入 Desktop，在终端中运行 /desktop。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥认证，也不适用于 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry。

CLI 标志等效项

此表显示桌面应用中常见 CLI 标志的等效项。未列出的标志没有桌面等效项，因为它们是为脚本或自动化设计的。

共享配置

Desktop 和 CLI 读取相同的配置文件，因此你的设置会迁移：

• 项目中的 CLAUDE.md 和 CLAUDE.local.md 文件两者都使用
• ~/.claude.json 或 .mcp.json 中配置的 MCP 服务器 在两者中都有效
• Hooks 和 技能 在设置中定义后适用于两者
• ~/.claude.json 和 ~/.claude/settings.json 中的 设置 是共享的。settings.json 中的权限规则、允许的工具和其他设置适用于 Desktop 会话。
• 模型：两者中可用的 模型 相同。在 Desktop 中，从发送按钮旁边的下拉菜单中选择模型。你可以在会话中随时从同一菜单更改模型。

功能对比

此表比较 CLI 和 Desktop 之间的核心功能。完整的 CLI 标志列表请参阅 CLI 参考。

Desktop 中不可用的功能

以下功能仅在 CLI 或 VS Code 扩展中可用，除非另有说明：

• 第三方提供商：Desktop 默认连接到 Anthropic 的 API。Enterprise 部署可以通过 managed settings 配置 Google Cloud's Agent Platform 和网关提供商。对于 CLI 中的 Amazon Bedrock 或 Microsoft Foundry，请参阅 quickstart。作为上述部分的例外，Claude Desktop on 3P 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 标签页。
• Linux（测试版）：计算机使用在 Linux 桌面应用中尚不可用。请参阅 Claude Desktop on Linux。
• 内联代码建议：Desktop 不提供自动补全风格的建议。它通过对话提示和显式代码变更工作。
• 代理团队：在 CLI 中可用的并行 Claude Code 会话互相消息传递在 Desktop 中不可用。对于单个会话内的多代理工作，请使用在 Desktop 中运行的 动态工作流。
• 终端对话框命令：在终端中打开交互面板的内置命令（如 /permissions 和 /config）在 Code 标签页中不可用，并回复 isn't available in this environment。/config 在传递 key=value 时设置一个设置，例如 /config theme=dark；只有它的 picker 表单不可用。直接在 settings files 中编辑以管理权限规则和配置，或在独立 CLI 中运行该命令。

故障排除

以下部分涵盖桌面应用特有的问题。对于聊天中出现的运行时 API 错误（如 API Error: 500、529 Overloaded、429 或 Prompt is too long），请参阅 错误参考。这些错误及其修复方法在 CLI、桌面和 Web 中相同。

检查版本

要查看你正在运行的桌面应用版本：

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

点击版本号将其复制到剪贴板。

Code 标签页中的 403 或认证错误

如果你在 Code 标签页中看到 Error 403: Forbidden 或其他认证失败：

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

启动时白屏或卡住

如果应用打开但显示白屏或无响应：

1. 重启应用。
2. 检查待更新。在 macOS 和 Windows 上，应用启动时自动更新；在 Linux 上，通过 apt 更新，如 Claude Desktop on Linux 中所述。
3. 在 Windows 上，检查 Event Viewer 中 Windows Logs → Application 下的崩溃日志。

"Failed to load session"

如果你看到 Failed to load session，选定的文件夹可能已不存在，Git 仓库可能需要未安装的 Git LFS，或文件权限可能阻止访问。尝试选择不同的文件夹或重启应用。

会话找不到已安装的工具

如果 Claude 找不到 npm、node 或其他 CLI 命令，请验证这些工具在你的常规终端中是否工作，检查你的 shell 配置文件是否正确设置了 PATH，并重启桌面应用以重新加载环境变量。

Git 和 Git LFS 错误

在 Windows 上，Git 是 Code 标签页启动本地会话的必需项。如果你看到 "Git is required"，请安装 Git for Windows 并重启应用。

如果你看到 "Git LFS is required by this repository but is not installed"，请从 git-lfs.com 安装 Git LFS，运行 git lfs install，然后重启应用。

Windows 上的 MCP 服务器不工作

如果 Windows 上的 MCP 服务器开关无响应或服务器连接失败，请检查服务器是否正确配置在你的设置中，重启应用，在任务管理器中验证服务器进程是否正在运行，并查看服务器日志以排查连接错误。

应用无法退出

• macOS：按 Cmd+Q。如果应用无响应，使用 Cmd+Option+Esc 强制退出，选择 Claude 并点击 Force Quit。
• 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 上搜索或提交 bug

报告问题时，请包含你的桌面应用版本、操作系统、确切的错误消息和相关日志。在 macOS 上，检查 Console.app。在 Windows 上，检查 Event Viewer → Windows Logs → Application。