Claude Code Desktop 配置与使用：并行会话、Diff 审查、PR 监控与计算机控制

Claude Code Desktop 是 Claude 桌面应用中专门用于软件开发的 Code 标签页，提供图形化的 Claude Code 体验。它支持并行 Git worktree 隔离会话、可视化 Diff 内联注释与审查、实时应用预览（内嵌浏览器）、计算机控制（macOS/Windows 屏幕与应用控制）、GitHub PR 监控（自动修复与自动合并）、连接器集成（GitHub/Slack/Linear）、定时任务调度，以及本地/SSH/云端远程三种运行环境。本页覆盖所有功能配置、命令等效、企业托管设置与常见故障排查第一步操作。

Claude Desktop 有三个标签页：Chat（对话）、Cowork（Dispatch 和长时间代理工作）和 Code（软件开发）。本页是 Code 标签页的完整参考。

下载安装：

下载 macOS 版本（通用构建，Intel 和 Apple Silicon 均可）
下载 Windows 版本（x64 处理器）
Windows ARM64：下载 ARM64 安装程序
Linux 不支持桌面应用，请改用 CLI

安装后启动 Claude，登录并点击 Code 标签页。Windows 上首次打开需要安装 Git for Windows，安装后重启应用。首次使用演练见 Get started 指南。

在 Code 标签页中，每个对话是一个会话——拥有独立的聊天历史、项目文件夹和代码变更，互不影响。侧边栏列出所有会话，支持同时运行多个。在一个会话中你可以：

审查并评论 diff，然后通过 CI 监控产生的 PR
在嵌入式浏览器中预览运行中的应用，同时让 Claude 验证自身变更
排列面板——聊天、diff、预览、终端、文件编辑器并排显示
提出侧边问题，利用会话上下文但不干扰主线程
连接外部工具如 GitHub、Slack、Linear
让 Claude 打开应用并控制屏幕
在本机、云端或 SSH 环境中运行

关于定时重复工作、键盘快捷键或从手机发送任务，见对应链接。若已使用基于终端的 CLI，见 CLI 对比了解迁移内容。

开始一次会话

发送第一条消息前，在提示框区域配置以下四项：

环境：选择 Claude 运行位置——Local（本机）、Remote（Anthropic 托管云端）或 SSH 连接（你管理的远程机器）。详见环境配置。
项目文件夹：选择 Claude 操作的文件夹或仓库。远程会话可添加多个仓库。
模型：从发送按钮旁的下拉列表选择。可在会话中切换。
权限模式：从模式选择器选择 Claude 的自主程度。可在会话中切换。

输入任务后按 Enter 开始。每个会话独立跟踪自己的上下文和变更。

代码工作

给 Claude 正确的上下文，控制其自主程度，并审查变更。

使用提示框

输入要 Claude 做的事情后按 Enter 发送。Claude 读取项目文件、做变更并运行命令（取决于权限模式）。随时可打断：点击停止按钮立即中断，或输入修正后按 Enter 发送（不中断正在执行的动作）。Claude 在当前动作完成后读取修正，调整下一步。

提示框旁的 + 按钮可访问文件附件、Skills、连接器和插件。

添加文件和上下文

支持两种方式引入外部上下文：

@mention 文件：输入 @ 后跟文件名，将文件加入对话上下文。Claude 可读取和引用该文件。远程会话中不可用。
附件文件：使用附件按钮上传图片、PDF 和其他文件，或直接拖放到提示框。适合分享 bug 截图、设计稿或参考文档。

选择权限模式

权限模式控制 Claude 在会话中的自主程度——是否在编辑文件或运行命令前询问。可使用发送按钮旁的模式选择器随时切换。建议从 Ask permissions 开始，了解 Claude 的每个动作，然后切换到 Auto accept edits 或 Plan mode。

模式	设置键	行为
Ask permissions	`default`	Claude 编辑文件或运行命令前询问。可看到 diff 并接受/拒绝。新用户推荐。
Auto accept edits	`acceptEdits`	Claude 自动接受文件编辑和常见文件系统命令（`mkdir`、`touch`、`mv`），其他终端命令仍询问。信任文件变更且希望更快迭代时使用。
Plan mode	`plan`	Claude 读取文件并运行命令以探索，然后提出计划，不修改源码。适合先审查方案的复杂任务。
Auto	`auto`	Claude 执行所有动作并做后台安全检查（验证与请求一致）。减少权限提示同时保持监督。需在 Settings → Claude Code 中启用。见可用性要求。
Bypass permissions	`bypassPermissions`	Claude 无任何权限提示运行，等同 CLI 的 `--dangerously-skip-permissions`。需在 Settings → Claude Code 中启用（允许旁路权限模式）。仅在沙箱容器或 VM 中使用。企业管理员可禁用此选项。

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

Auto 模式是研究预览功能，所有 Anthropic API 用户可用。第三方提供商上不可用。需要 Claude Sonnet 4.6、Opus 4.6 或 Opus 4.7。

复杂任务先在 Plan mode 中开始，让 Claude 制定方案后再修改。方案批准后切换到 Auto accept edits 或 Ask permissions 执行。详见先探索，再计划，后编码。

远程会话支持 Auto accept edits 和 Plan mode。Ask permissions 不可用（远程会话默认自动接受文件编辑），Bypass permissions 不可用（远程环境已沙箱化）。

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

预览应用

Claude 可启动开发服务器并打开嵌入式浏览器验证变更。适用于前端 Web 应用和后端服务器：Claude 可测试 API 端点、查看服务器日志、迭代修复发现的问题。大多数情况下，Claude 在编辑项目文件后自动启动服务器。也可随时要求 Claude 预览。默认情况下，Claude 每次编辑后自动验证变更。

预览面板也可打开项目中的静态 HTML 文件、PDF、图片和视频。在聊天中点击 HTML、PDF、图片或视频路径即可在预览中打开。

从预览面板可执行：

直接在嵌入式浏览器中与运行中的应用交互
观察 Claude 自动验证变更：截图、检查 DOM、点击元素、填写表单、修复问题
从会话工具栏的 Preview 下拉菜单启动或停止服务器
勾选 Persist sessions 跨服务器重启保留 Cookie 和 Local Storage，避免开发过程中重复登录
编辑服务器配置或一次停止所有服务器

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

清除已保存的会话数据：在 Settings → Claude Code 中关闭 Persist preview sessions。完全禁用预览：在 Settings → Claude Code 中关闭 Preview。

审查变更（Diff 视图）

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

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

macOS：Cmd+Enter
Windows：Ctrl+Enter

Claude 读取评论并做请求的修改，以新 diff 呈现供审查。

审查代码

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

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

监控 Pull Request 状态

打开 PR 后，会话中出现 CI 状态栏。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败信息。

Auto-fix：开启后，当 CI 检查失败时 Claude 自动尝试修复——读取失败输出并迭代。
Auto-merge：开启后，当所有检查通过时 Claude 自动合并 PR。合并方法为 squash。需在 GitHub 仓库设置中启用 auto-merge。

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

PR 监控需要本机安装并认证 GitHub CLI (gh)。如果未安装，Desktop 会在首次尝试创建 PR 时提示安装。

排列工作区

Code 标签页基于面板构建，可任意布局：聊天、diff、预览、终端、文件、计划、任务、子代理。拖拽面板标题可重新定位，拖拽面板边缘可调整大小。按 Cmd+\（macOS）或 Ctrl+\（Windows）关闭聚焦的面板。从会话工具栏的 Views 菜单打开更多面板。

本节的面板布局、终端、文件编辑器和视图模式需要 Claude Desktop v1.2581.0 或更高版本。打开 Claude → Check for Updates（macOS）或 Help → Check for Updates（Windows）更新。

运行命令（集成终端）

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

打开和编辑文件

在聊天或 diff 查看器中点击文件路径，在文件面板中打开。HTML、PDF、图片和视频路径改为在预览面板中打开。做即时编辑后点击 Save 写回文件。如果文件在打开后已在磁盘上变更，面板会警告并提供覆盖或放弃选项。点击 Discard 放弃编辑，或点击面板标题中的路径复制绝对路径。

文件面板在本地和 SSH 会话中可用。远程会话请让 Claude 做变更。

在其他应用中打开文件

右键点击聊天、diff 查看器或文件面板中的任意文件路径，弹出上下文菜单：

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

切换视图模式

视图模式控制聊天记录中显示的细节量。从发送按钮旁的 Transcript view 下拉菜单切换，或按 Ctrl+O（macOS/Windows）循环。

模式	显示内容
Normal	工具调用折叠为摘要，完整文本响应
Verbose	每个工具调用、文件读取和中间步骤
Summary	仅 Claude 的最终响应和变更

调试 Claude 为什么采取某个操作时使用 Verbose。运行多个会话并希望快速扫描结果时使用 Summary。

键盘快捷键

按 Cmd+/（macOS）或 Ctrl+/（Windows）查看 Code 标签页中所有快捷键。Windows 上使用 Ctrl 代替 Cmd。会话切换、终端切换和视图模式切换在所有平台上都使用 Ctrl。

快捷键	操作
`Cmd` `/`	显示键盘快捷键
`Cmd` `N`	新建会话
`Cmd` `W`	关闭会话
`Ctrl` `Tab` / `Ctrl` `Shift` `Tab`	下一个或上一个会话
`Cmd` `Shift` `]` / `Cmd` `Shift` `[`	下一个或上一个会话
`Esc`	停止 Claude 的响应
`Cmd` `Shift` `D`	切换 diff 面板
`Cmd` `Shift` `P`	切换预览面板
`Cmd` `Shift` `S`	选择预览中的元素
`Ctrl` `	切换终端面板
`Cmd` `\`	关闭聚焦的面板
`Cmd` `;`	打开侧边对话
`Ctrl` `O`	循环视图模式
`Cmd` `Shift` `M`	打开权限模式菜单
`Cmd` `Shift` `I`	打开模型菜单
`Cmd` `Shift` `E`	打开推理力度菜单
`1`–`9`	选择打开菜单中的项

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

检查用量

点击模型选择器旁的用量圆环，查看当前上下文窗口使用情况和当期的计划用量。上下文使用量按会话计；计划用量在所有 Claude Code 表面共享。

让 Claude 使用你的计算机

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

计算机使用是 macOS 和 Windows 上的研究预览功能，需要 Pro 或 Max 计划。Team 或 Enterprise 计划不可用。Claude Desktop 应用必须正在运行。

计算机使用默认关闭。需要在设置中开启后 Claude 才能控制屏幕。macOS 上还需授予辅助功能和屏幕录制权限。

与沙箱 Bash 工具不同，计算机使用在真实桌面上运行，可访问你批准的任何内容。Claude 检查每个动作并标记屏幕内容中的潜在提示注入，但信任边界不同。最佳实践见计算机使用安全指南。

计算机使用何时适用

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

如果为服务配置了连接器，Claude 使用连接器。
如果任务是 shell 命令，Claude 使用 Bash。
如果任务是浏览器工作且已设置 Claude in Chrome，Claude 使用该工具。
如果都不适用，Claude 使用计算机使用。

按应用访问层级进一步加强此优先级：浏览器限于仅查看，终端和 IDE 限于仅点击，即使在计算机使用活跃时也引导 Claude 使用专用工具。屏幕控制留给其他工具无法触及的内容，如原生应用、硬件控制面板、移动模拟器或没有 API 的专有工具。

启用计算机使用

计算机使用默认关闭。如果要求 Claude 做需要此功能的事情而它已关闭，Claude 会提示可在设置中启用。

确保运行最新版本 Claude Desktop。从 claude.com/download 下载或更新，然后重启应用。
在桌面应用中进入 Settings > General（在 Desktop app 下），找到 Computer use 开关并打开。Windows 上开关立即生效，设置完成。macOS 上继续下一步。如果看不到开关，确认使用的是 macOS 或 Windows 并有 Pro 或 Max 计划，然后更新并重启应用。
macOS 上，在开关生效前需授予两项系统权限：
- Accessibility（辅助功能）：允许 Claude 点击、键入和滚动
- Screen Recording（屏幕录制）：允许 Claude 查看屏幕内容 Settings 页面显示每个权限的当前状态。如果被拒绝，点击徽章打开对应的系统设置面板。

应用权限

Claude 首次需要使用某个应用时，会话中会出现提示。点击 Allow for this session 或 Deny。批准有效期为一整个会话（或 Dispatch 生成的会话为 30 分钟）。

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

层级	Claude 能做什么	适用范围
仅查看	可在截图中看到应用	浏览器、交易平台
仅点击	可点击和滚动，不能输入或使用键盘快捷键	终端、IDE
完全控制	点击、输入、拖拽、使用键盘快捷键	其他所有应用

具有广泛访问权限的应用（如终端、Finder/文件资源管理器、系统设置/Settings）会在提示中显示额外警告，让你知道批准它们会授予什么。

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

Denied apps：添加应用后直接拒绝，无需提示。Claude 可能通过允许的应用间接影响拒绝的应用，但不能直接与被拒绝的应用交互。
Unhide apps when Claude finishes：Claude 工作时会隐藏其他窗口，以便只与批准的应用交互。Claude 完成后恢复隐藏的窗口，除非关闭此设置。

管理会话

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

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

要同时查看两个会话，在 macOS 上按住 Cmd 或 Windows 上按住 Ctrl 并点击侧边栏中的会话。会话会在第二个面板中打开，与你已打开的面板并列。当分割激活时，点击另一个侧边栏会话会替换当前聚焦的面板。按 Cmd+\（macOS）或 Ctrl+\（Windows）关闭聚焦的面板并回到单个会话。

Worktrees 默认存储在 <project-root>/.claude/worktrees/。可在 Settings → Claude Code 的 “Worktree location” 中更改为自定义目录。还可设置分支前缀，该前缀会添加到每个 worktree 分支名称前，有助于保持 Claude 创建的分支有序。完成工作后，将鼠标悬停在侧边栏中的会话上并点击归档图标以删除 worktree。要自动在 PR 合并或关闭后归档会话，在 Settings → Claude Code 中开启 Auto-archive after PR merge or close。auto-archive 仅适用于已完成的本地会话。

要将 .gitignore 中的文件（如 .env）包含到新 worktrees 中，在项目根目录创建 .worktreeinclude 文件。详见复制被 Gitignored 的文件到 worktrees。

会话隔离需要 Git。大多数 Mac 默认包含 Git。在终端运行 git --version 检查。Windows 上 Code 标签页需要 Git：下载 Git for Windows，安装后重启应用。如果遇到 Git 错误，在 Cowork 标签页中让 Claude 帮助排查设置。

使用侧边栏顶部的控件按状态、项目或环境筛选会话，并按项目分组。要重命名会话，点击活动会话工具栏顶部的会话标题。要检查上下文使用量，见检查用量。当上下文填满时，Claude 会自动压缩对话并继续工作。也可输入 /compact 提前触发压缩以释放上下文空间。压缩如何工作详见上下文窗口。

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

提出侧边问题而不中断主线程

侧边对话可让你向 Claude 提问，使用会话上下文但不向主对话添加任何内容。当你想理解一段代码、验证某个假设或探索一个想法而不改变会话方向时使用。

按 Cmd+;（macOS）或 Ctrl+;（Windows）打开侧边对话，或输入 /btw。侧边对话可读取主线程到该点的所有内容。完成后关闭侧边对话，从离开处继续主会话。侧边对话在本地和 SSH 会话中可用。

查看后台任务

任务面板显示当前会话中运行的后台工作：子代理、后台 shell 命令和工作流。从 Views 菜单打开或拖入布局。

点击任何项可在子代理面板中查看输出或停止它。要查看其他会话在做什么，使用侧边栏。

远程运行长时间任务

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

远程会话还支持多个仓库。选择云端环境后，点击仓库标签旁的 + 按钮添加更多仓库。每个仓库有自己的分支选择器。适合跨多个代码库的任务，如更新共享库及其使用者。

远程会话如何工作详见 Claude Code on the web。

在其他表面继续

会话工具栏右下角的 VS Code 图标的 Continue in 菜单可将会话移动到其他表面：

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

Dispatch 启动的会话

Dispatch 是 Cowork 标签页中常驻的 Claude 对话。你向 Dispatch 发送任务，它决定如何处理。

任务可通过两种方式变成 Code 会话：你直接要求（如"打开一个 Claude Code 会话并修复登录 bug"），或 Dispatch 判定是开发工作并自动生成。通常路由到 Code 的任务包括修复 bug、更新依赖、运行测试或打开 PR。研究、文档编辑和电子表格工作留在 Cowork。

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

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

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

Dispatch 是远离终端时与 Claude 工作的几种方式之一。与 Remote Control、Channels、Slack 和定时任务的比较见平台和集成。

扩展 Claude Code

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

连接外部工具

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

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

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

连接器是带图形化设置流程的 MCP 服务器。用于快速集成受支持的服务。对于 Connectors 未列出的集成，通过设置文件手动添加 MCP 服务器。也可创建自定义连接器。

使用 Skills

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

安装插件

插件是可复用包，为 Claude Code 添加 Skills、代理、钩子、MCP 服务器和 LSP 配置。可在桌面应用中安装插件，无需终端。

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

插件可限定作用于用户账户、特定项目或仅本地。如果组织集中管理插件，这些插件在桌面会话中与 CLI 中一样可用。远程会话中插件不可用。完整插件参考（包括创建自己的插件）见插件。

配置预览服务器

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

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

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

可定义多个配置以从同一项目运行不同服务器，例如前端和 API。见下面的示例。

自动验证变更

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

自动验证默认开启。在每个项目中通过将 "autoVerify": false 添加到 .claude/launch.json 禁用，或从 Preview 下拉菜单切换。

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

禁用后预览工具仍可用，可随时要求 Claude 验证。自动验证在每次编辑后使其自动发生。

配置字段

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

字段	类型	描述
`name`	string	此服务器的唯一标识符
`runtimeExecutable`	string	要运行的命令，如 `npm`、`yarn` 或 `node`
`runtimeArgs`	string[]	传给 `runtimeExecutable` 的参数，如 `["run", "dev"]`
`port`	number	服务器监听的端口。默认 3000
`cwd`	string	相对于项目根目录的工作目录。默认项目根目录。使用 `${workspaceFolder}` 显式引用项目根目录
`env`	object	额外的环境变量键值对，如 `{ "NODE_ENV": "development" }`。不要在此放密钥（文件会提交到仓库）。向开发服务器传递密钥，请在本地环境编辑器中设置
`autoPort`	boolean	端口冲突处理方式。见下
`program`	string	用 `node` 运行的脚本。见何时使用 `program` vs `runtimeExecutable`
`args`	string[]	传给 `program` 的参数。仅在设置 `program` 时使用

何时使用 `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 环境变量将分配的端口传递给服务器。

示例

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

Next.js 使用 Yarn：

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

直接运行 Node.js 脚本：

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

环境配置

开始会话时选择的环境决定了 Claude 的执行位置和连接方式：

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

本地会话

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

要为所有平台上的本地会话和开发服务器设置环境变量，打开提示框中的环境下拉菜单，悬停在 Local 上，点击齿轮图标打开本地环境编辑器。此处保存的变量加密存储在机器上，应用于所有本地会话和预览服务器。也可将变量添加到 ~/.claude/settings.json 的 env 键中，但这些变量仅到达 Claude 会话，不应用于开发服务器。支持的所有变量列表见环境变量。

扩展思考默认启用，可提高复杂推理任务的性能但使用额外 token。要完全禁用思考，在本地环境编辑器中设置 MAX_THINKING_TOKENS 为 0。在具有自适应推理的模型上，任何其他 MAX_THINKING_TOKENS 值均被忽略，因为自适应推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，设置 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING 为 1 以使用固定 thinking budget；Opus 4.7 始终使用自适应推理，没有固定预算模式。

远程会话

远程会话在后台继续运行，即使关闭应用。用量计入订阅计划限额，没有单独的计算费用。

可创建具有不同网络访问级别和环境变量的自定义云端环境。开始远程会话时选择环境下拉菜单并选择 Add environment。配置网络访问和环境变量的详细信息见云端环境。

SSH 会话

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

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

Name：连接的友好标签
SSH Host：user@hostname 或在 ~/.ssh/config 中定义的主机
SSH Port：默认 22 或从 SSH config 读取
Identity File：私钥路径，如 ~/.ssh/id_rsa。留空使用默认密钥或 SSH config

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

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

为团队预配置 SSH 连接

管理员可通过将 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 字段可选。用户也可将 sshConfigs 添加到自己的 ~/.claude/settings.json 中（通过对话框添加的连接存储在此处）。

限制用户可连接的 SSH 主机

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

以下示例允许连接到 devboxes.example.com 下的任何主机以及一个命名的堡垒主机：

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

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

sshHostAllowlist 仅从受管设置读取；用户或项目设置中的值被忽略。仅 Claude Desktop 应用遵守此设置；Claude Code CLI 和 IDE 扩展不读取它，且它不限制通过 Bash 工具运行的 ssh 命令。它控制 Desktop 应用连接哪些主机，而非网络出口，因此如果需要硬边界，请与组织的网络或零信任控制配合使用。

企业配置

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

管理控制台控制

以下设置通过管理设置控制台配置：

Code in the desktop：控制组织中用户是否可在桌面应用中访问 Claude Code
Code in the web：为组织启用或禁用Web 会话
Remote Control：为组织启用或禁用远程控制
Disable Bypass permissions mode：防止组织中用户启用旁路权限模式

受管设置

受管设置覆盖项目和用户设置，并在 Desktop 生成 CLI 会话时应用。可在组织的受管设置文件中设置这些键，或通过管理控制台远程推送。

键	描述
`permissions.disableBypassPermissionsMode`	设为 `"disable"` 禁止用户启用 Bypass permissions 模式。
`disableAutoMode`	设为 `"disable"` 禁止用户启用 Auto 模式。从模式选择器中移除 Auto。也接受在 `permissions` 下。
`autoMode`	自定义 Auto 模式分类器在整个组织中信任和阻止的内容。见配置 Auto 模式。
`sshConfigs`	预配置 SSH 连接，出现在环境下拉菜单中。用户无法编辑或删除受管连接。
`sshHostAllowlist`	限制 SSH 会话到其解析后的主机名与某个模式匹配的主机。空数组禁用 SSH 会话。仅从受管设置读取。
`managedMcpServers`	向第三方部署中的所有用户推送 MCP 服务器配置。每个条目指定传输方式 (`"http"`、`"sse"` 或 `"stdio"`)、连接细节以及可选的 `toolPolicy` 映射（限制用户可调用该服务器中的哪些工具）。仅在第三方 (3P) Desktop 部署中可用。

部署到每台机器磁盘上的受管设置文件适用于 Desktop 会话。通过管理控制台远程推送的受管设置当前仅到达 CLI 和 IDE 会话，因此对于 Desktop 部署，请通过 MDM 分发文件或使用上面的管理控制台控制。

permissions.disableBypassPermissionsMode 和 disableAutoMode 也适用于用户和项目设置，但放在受管设置中可防止用户覆盖。autoMode 从用户设置、.claude/settings.local.json 和受管设置中读取，但不会从检入的 .claude/settings.json 中读取：克隆的仓库不能注入自己的分类器规则。完整的管理专用设置列表（包括 allowManagedPermissionRulesOnly 和 allowManagedHooksOnly）见管理专用设置。

设备管理策略

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

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

认证与 SSO

Enterprise 组织可要求所有用户使用 SSO。见认证了解计划级详细信息，见设置 SSO 了解 SAML 和 OIDC 配置。

数据处理

Claude Code 在本地会话中本地处理代码，或在远程会话中在 Anthropic 云端基础设施上处理。对话和代码上下文发送到 Anthropic 的 API 进行处理。数据保留、隐私和合规性的详细信息见数据处理。

部署

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

macOS：通过 MDM（如 Jamf 或 Kandji）使用 .dmg 安装程序分发
Windows：通过 MSIX 包或 .exe 安装程序部署。Enterprise 部署选项（包括静默安装）见部署 Windows 版 Claude Desktop

网络配置（代理设置、防火墙白名单、LLM 网关）见网络配置。

完整的企业配置参考见企业配置指南。

从 CLI 迁移？

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

要将 CLI 会话移入 Desktop，在终端运行 /desktop。Claude 保存会话并在桌面应用中打开，然后退出 CLI。此命令在 macOS 和 Windows 上可用（当使用 Claude 订阅登录时）。不适用于 API 密钥认证或 Bedrock、Vertex、Foundry。

何时使用 Desktop 与 CLI：需要在一个窗口中管理并行会话、并排排列面板或视觉审查变更时使用 Desktop。需要脚本化、自动化或偏好终端工作流时使用 CLI。

CLI 标志对应

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

CLI	Desktop 对应
`--model sonnet`	发送按钮旁的模型下拉菜单
`--resume`, `--continue`	点击侧边栏中的会话
`--permission-mode`	发送按钮旁的模式选择器
`--dangerously-skip-permissions`	Bypass permissions 模式。在 Settings → Claude Code 中启用 “Allow bypass permissions mode”。企业管理员可禁用此设置。
`--add-dir`	远程会话中用 + 按钮添加多个仓库
`--allowedTools`, `--disallowedTools`	无每会话对应项。设置文件中的权限规则仍然适用。
`--verbose`	Verbose 视图模式（Transcript view 下拉菜单）
`--print`, `--output-format`	不可用。Desktop 仅交互模式。
`ANTHROPIC_MODEL` 环境变量	发送按钮旁的模型下拉菜单
`MAX_THINKING_TOKENS` 环境变量	在本地环境编辑器中设置。见环境配置。

共享配置

Desktop 和 CLI 读取相同的配置文件，因此你的设置可延续：

项目中的 CLAUDE.md 和 CLAUDE.local.md 文件两者均使用
~/.claude.json 或 .mcp.json 中配置的 MCP 服务器 两者均有效
设置中定义的 Hooks 和 Skills 均适用
~/.claude.json 和 ~/.claude/settings.json 中的设置共享。权限规则、允许的工具等设置应用于 Desktop 会话。
模型：两者均提供 Sonnet、Opus 和 Haiku。在 Desktop 中，从发送按钮旁的下拉菜单选择。可在会话中切换模型。

MCP 服务器：桌面聊天应用与 Claude Code：为 Claude Desktop 聊天应用在 claude_desktop_config.json 中配置的 MCP 服务器与 Claude Code 是分开的，不会出现在 Code 标签页中。要在 Claude Code 中使用 MCP 服务器，在 ~/.claude.json 或项目的 .mcp.json 中配置。详见 MCP 配置。

功能比较

此表比较 CLI 与 Desktop 的核心功能。完整 CLI 标志列表见 CLI 参考。

功能	CLI	Desktop
权限模式	所有模式包括 `dontAsk`	Ask permissions、Auto accept edits、Plan mode、Auto 和通过 Settings 的 Bypass permissions
`--dangerously-skip-permissions`	CLI 标志	Bypass permissions 模式，在 Settings → Claude Code 中启用
第三方提供商	Bedrock、Vertex、Foundry	默认 Anthropic API。Enterprise 部署可配置 Vertex AI 和网关提供商。见企业配置指南。
MCP 服务器	在设置文件中配置	本地/SSH 会话的连接器 UI，或设置文件
插件	`/plugin` 命令	插件管理器 UI
@mention 文件	基于文本	带自动补全；仅本地和 SSH 会话
文件附件	不可用	图片、PDF
会话隔离	`--worktree` 标志	自动 worktrees
多会话	单独终端	侧边栏标签页
定时任务	Cron 任务、CI 流水线	定时任务
计算机使用	通过 `/mcp` 在 macOS 上启用	macOS 和 Windows 上的应用和屏幕控制
Dispatch 集成	不可用	侧边栏中的 Dispatch 会话
脚本和自动化	`--print`、Agent SDK	不可用

Desktop 中不可用的功能

以下功能仅在 CLI 或 VS Code 扩展中可用：

第三方提供商：Desktop 默认连接到 Anthropic 的 API。Enterprise 部署可通过受管设置配置 Vertex AI 和网关提供商。Bedrock 或 Foundry 请使用 CLI。
Linux：桌面应用仅适用于 macOS 和 Windows。Linux 上使用 CLI。
内联代码建议：Desktop 不提供自动补全式建议。通过对话式提示和显式代码变更工作。
代理团队：多代理编排通过 CLI 和 Agent SDK 使用，不在 Desktop 中。
终端对话命令：在终端中打开交互面板的内置命令（如 /permissions、/config、/agents、/doctor）在 Code 标签页中不可用，会回复 isn't available in this environment。直接编辑设置文件管理权限规则和配置，或在独立 CLI 中运行命令。

故障排查

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

检查版本

查看桌面应用版本：

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

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

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

如果使用 Code 标签页时看到 Error 403: Forbidden 或其他认证失败：

从应用菜单退出并重新登录（最常见的修复方法）。
确认有有效的付费订阅：Pro、Max、Team 或 Enterprise。
如果 CLI 工作但 Desktop 不工作，完全退出桌面应用（不只是关闭窗口），然后重新打开并再次登录。
检查网络连接和代理设置。

启动后空白或卡死

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

重启应用。
检查是否有待更新。应用启动时会自动更新。
Windows 上，在事件查看器的 Windows Logs → Application 中检查崩溃日志。

“Failed to load session”

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

会话找不到已安装的工具

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

Git 和 Git LFS 错误

Windows 上，Code 标签页需要 Git 才能启动本地会话。如果看到 “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 服务器不工作

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

应用无法退出

macOS：按 Cmd+Q。如果应用无响应，使用 Cmd+Option+Esc 强制退出，选择 Claude 并点击 Force Quit。
Windows：使用 Ctrl+Shift+Esc 打开任务管理器，结束 Claude 进程。

Windows 特有 issues

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

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

远程会话可能创建本机上不存在的分支。点击会话工具栏中的分支名称复制它，然后在本地获取：

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

仍然卡住？

在 GitHub Issues 搜索或提交 bug
访问 Claude 支持中心

提交 bug 时，包括桌面应用版本、操作系统、确切的错误消息和相关日志。macOS 上检查 Console.app，Windows 上检查 Event Viewer → Windows Logs → Application。

常见问题

Desktop 和 CLI 可以同时在同一项目上运行吗？

可以。两者使用相同的底层引擎，共享 CLAUDE.md 配置文件。各有独立的会话历史，但配置互通。在终端运行 /desktop 可将 CLI 会话迁移到 Desktop。

Remote 会话的费用怎么算？需另外付费吗？

远程会话用量计入你的订阅计划限额（Pro/Max/Team/Enterprise），没有单独的计算费用。具体限额见成本。

计算机使用功能怎么保证安全？会不会误操作？

计算机使用按应用分层级授权：浏览器仅查看（不能操作）、终端和 IDE 仅点击（不能输入），完全控制只留给原生 App 等。每次批准仅对当前会话有效。企业管理员可通过受管设置进一步限制或禁用此功能。最佳实践参见安全指南。

Claude Code Desktop 配置与使用：并行会话、Diff 审查、PR 监控与计算机控制 #

开始一次会话 #

代码工作 #

使用提示框 #

添加文件和上下文 #

选择权限模式 #

预览应用 #

审查变更（Diff 视图） #

审查代码 #

监控 Pull Request 状态 #

排列工作区 #

运行命令（集成终端） #

打开和编辑文件 #

在其他应用中打开文件 #

切换视图模式 #

键盘快捷键 #

检查用量 #

让 Claude 使用你的计算机 #

计算机使用何时适用 #

启用计算机使用 #

应用权限 #

管理会话 #

并行会话（Sidebar） #

提出侧边问题而不中断主线程 #

查看后台任务 #

远程运行长时间任务 #

在其他表面继续 #

Dispatch 启动的会话 #

扩展 Claude Code #

连接外部工具 #

使用 Skills #

安装插件 #

配置预览服务器 #

自动验证变更 #

配置字段 #

何时使用 program 与 runtimeExecutable #

端口冲突 #

示例 #

环境配置 #

本地会话 #

远程会话 #

SSH 会话 #

为团队预配置 SSH 连接 #

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

企业配置 #

管理控制台控制 #

受管设置 #

设备管理策略 #

认证与 SSO #

数据处理 #

部署 #

从 CLI 迁移？ #

CLI 标志对应 #

共享配置 #

功能比较 #

Desktop 中不可用的功能 #

故障排查 #

检查版本 #

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

启动后空白或卡死 #

“Failed to load session” #

会话找不到已安装的工具 #

Git 和 Git LFS 错误 #

Windows 上 MCP 服务器不工作 #

应用无法退出 #

Windows 特有 issues #

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

仍然卡住？ #

常见问题 #

Desktop 和 CLI 可以同时在同一项目上运行吗？ #

Remote 会话的费用怎么算？需另外付费吗？ #

计算机使用功能怎么保证安全？会不会误操作？ #