Claude Code 桌面应用：要什么账号、并行会话和 worktree、预览、审改动盯 PR、SSH 远程开发

这篇接着《在 VS Code、JetBrains 和桌面应用里用 Claude Code》往下讲。那一篇讲了桌面应用怎么装、开会话选哪四样、和命令行比少了什么；这一篇讲真用起来要知道的事：

订阅账号和中转站下，各能用到哪些功能；
环境变量为什么设了不生效；
并行会话、worktree，以及归档时可能丢掉没提交的改动；
预览服务器怎么配，改动怎么审，PR 怎么盯；
用它连一台远程服务器开发（SSH 会话），以及断线、合盖之后任务还在不在。

全文按 2026-10-21 的官方文档整理，桌面应用没有实测（本站的测试环境是没有图形界面的服务器），按钮和菜单的名字照文档写。

版本号有两套。 桌面应用自己的版本（比如 v2.37337.0）和 Code 标签页里那份 Claude Code 的版本（比如 2.1.304）不是一回事。前者在 About Claude 里看；后者在本地会话里输入 /status 看 Claude Code 那一行。它们各自更新，和终端里装的 claude 也互不影响。下文写“v2.x 起”的是桌面应用的版本。

一、先弄清能用到什么

桌面应用要登录 Claude 账号。 快速上手文档写明 Code 标签页要 Pro、Max、Team 或 Enterprise 订阅；Linux 那页说得更直接：用 API key 认证的，用命令行。

另一条路是第三方推理配置。 桌面应用不读 ANTHROPIC_BASE_URL，也不读 settings.json 里的网关设置。接网关要在应用里打开 Help → Troubleshooting → Enable Developer Mode，重启后多出 Developer 菜单，再进 Developer → Configure Third-Party Inference 填网关地址。在国内接中转站走的就是这条路，具体步骤见《Claude 桌面应用接入中转站》。

两种情况下能用的不一样：

	用 Claude 账号登录	走第三方推理配置（网关、中转站）
界面	v2.37337.0 起是新布局	一直是旧布局：没有保存的环境，没有会话详情面板
云端会话	有，用量算进订阅额度	环境选择器里没有 Anthropic 托管的云端环境
Remote Control、手机上看会话	有	没有
SSH 会话	有	测试版，要 v1.40609.0 起，默认关闭，要在第三方配置的 `sshHostAllowlist` 里列出允许的主机
WSL 会话	有终端和连接器（在陆续上线）	没有终端和连接器
终端里 `/desktop`、`claude --desktop` 把会话搬过来	有（macOS、x64 Windows）	没有，要 Claude 订阅登录
computer use、Dispatch	Pro、Max 有，Team、Enterprise 没有	文档没写

文档没写账号条件的功能（本地会话、diff 和评论、/code-review、预览和浏览器窗格、worktree、旁支对话、本地定时任务、盯 PR），走网关能不能用，本站没有核对到。

还有一点：桌面应用本身要能连上 Anthropic 的服务器。 文档说应用的代码和内容从 *.anthropic.com、*.claude.ai、*.claude.com 等地址加载，没说接了网关就可以不连。启动白屏，排查的第三步就是看防火墙有没有放行这些地址。

二、开会话：环境、文件夹，以及环境变量的坑

新布局里，发第一条消息前在输入框下方那一行选好环境、文件夹、权限模式和模型。环境有四种：本地、云端、SSH、WSL（Windows）。

保存的环境（v2.37337.0 起）：环境选择器底部选 New environment，在 Local、SSH 或 Cloud 标签页里填好，存起来以后一点就开会话。保存的本地或 SSH 环境连文件夹一起记住，所以用它开会话时不再显示文件夹控件。第一次用新布局时，应用会按过去一个月最常用的文件夹自动建最多 8 个，可以改可以删。

环境变量是最容易踩的坑：

桌面应用不一定继承你 shell 里的变量。 macOS 上从程序坞或访达启动时，只读 shell 配置文件里的 PATH 和一组固定的 Claude Code 变量；Windows 上继承用户和系统变量，不读 PowerShell 的配置文件。会话找不到 npm、node 时，先确认普通终端里能用、PATH 设对了，然后重启桌面应用。
给本地会话设变量：在保存的本地环境里加，一行一个 KEY=value，只有从这个环境开的会话拿得到。旧布局没有保存的环境，用本地环境编辑器（悬在 Local 上点齿轮），存的值在本机加密保存。所有本地会话都要的写进 ~/.claude/settings.json 的 env，但文档说，如果应用启动会话时环境里已经有这个变量，settings.json 里的值会被忽略。
有些变量应用自己设，你设什么都没用。 文档举了两个，并说“不止这两个”：API_TIMEOUT_MS，本地会话一律是 900000，也就是 15 分钟，要更长只能改用命令行；ANTHROPIC_BASE_URL，用 Claude 账号登录时一律是 Anthropic 的地址，接网关用前面说的第三方推理配置。这两个无论写在 shell 配置、Windows 变量、本地环境编辑器、保存的环境还是 settings.json 里，都不管用。
开发服务器拿不到保存的环境和 settings.json 里的变量。 给开发服务器的密钥，在 macOS 和 Linux 上写进 shell 配置文件 export，在 Windows 上设成用户或系统变量，或者放进本地环境编辑器，然后重启桌面应用。

三、权限模式

模式	设置里的值	做什么
Manual	`default`	改文件、跑命令前都问；看 diff，逐处接受或拒绝
Accept edits	`acceptEdits`	自动接受改文件和 `mkdir`、`mv` 这类常见文件命令，别的命令照样问
Plan	`plan`	只读文件、跑命令来摸清情况，提方案，不改代码
Auto	`auto`	不逐个问，后台分类器检查动作是否符合你的要求。文档只说它在 Anthropic API 上对所有用户开放，没说走网关时有没有
Bypass permissions	`bypassPermissions`	基本不问。Pro、Max 要先在 Settings → Claude Code 打开 Allow bypass permissions mode，Team、Enterprise 由组织决定。文档说只在沙箱容器或虚拟机里用

几个和命令行不一样的地方：

Shift+Tab 在桌面应用里不切模式，用输入框下方的选择器，或 Cmd+Shift+M（Windows、Linux 是 Ctrl+Shift+M）。
在选择器里选的模式按文件夹记住，对这个文件夹优先于设置文件里的 permissions.defaultMode；Plan 例外，只管当前会话。
云端会话只有 Accept edits、Plan 和 Auto。
文档的建议：复杂任务先用 Plan，批准方案后再切 Accept edits 或 Manual 去做。各模式的细节见《权限模式怎么选》。

四、并行会话、worktree 和归档

同时开几个会话：侧栏 + New 或 Cmd+N，Ctrl+Tab 在会话间切换。按住 Cmd（Windows 上 Ctrl）点侧栏里的另一个会话，会在旁边的窗格里打开，两个并排看。会话做完而你没在看时，应用发系统通知。

worktree 默认是关的。 不打开时，几个会话都直接改项目文件夹，会互相踩。要隔离，开会话之前在文件夹控件里打开 Worktree（保存的环境在编辑环境时设，旧布局是输入框上方的复选框）。相关设置：

默认建在项目根目录下的 .claude/worktrees/，在 Settings → Claude Code 的 Worktree location 里改，Branch prefix 给分支名加前缀；
.env 这类被 .gitignore 忽略、新 worktree 里没有的文件，在项目根目录写一个 .worktreeinclude 把它们带进去，见《用 worktree 同时开两个会话》。

归档时可能丢掉没提交的改动。 文档的原话是先提交要留的东西。分三种情况：

应用问你的时候，选 Archive anyway 就是丢弃；
worktree 里只有未跟踪的新文件时，要在 Claude 在这个会话里开的 PR 合并之前提交，合并后应用可能不问就删掉它们；
其他情况，worktree 留在磁盘上，本地会话的在归档或最后一次打开后约 30 天删掉，想留就到 Archived 里 Unarchive。

Settings → Claude Code 里可以打开 Auto-archive after PR merge or close，PR 合并或关闭后自动归档（云端会话和正在跑的会话不会）。

其他几样：

旁支对话：Cmd+; 或 /btw，用当前会话的上下文回答，不进主对话。它不存盘，关掉应用就没了。
后台任务：会话里有子代理、后台命令、动态工作流时，从标题栏 ⋮ 菜单的 Background tasks 打开任务窗格，点一项看输出或停掉。
管别的会话：可以直接问“哪个会话动过 auth 的重构”“告诉 payments 那个会话 schema 改了”，它能列出、读取、给别的会话发消息、改名和归档。它只看得到桌面应用自己开的本地、SSH、WSL 会话，默认是最近活跃的 20 个，看不到终端和 VS Code 里开的。Auto 和 Bypass 模式下它归档会话不再问你。
顺手发现的问题：它会在聊天里给一个任务按钮，点了就在一个带自己 worktree 的新会话里去做，当前会话不受影响。

五、看改动、审代码、盯 PR

看改动：点会话详情面板 Changes 卡片上的 +12 -1，或标题栏的 Changes。在 diff 的任意一行上点开评论框，写完回车；多条评论写好后用 Cmd+Enter（Windows 上 Ctrl+Enter）一起提交，它读了评论再改。
提交前审一遍：输入 /code-review。本地、SSH、WSL 会话里，结果是一张按文件分组的卡片，可以 Walk through in diff 逐条在 diff 里看、对单条点 Fix this one，或者 Apply fixes 全修。做法和命令行一样，见《提交之前让 Claude Code 先审一遍》。
盯 PR：开了 PR 后它出现在 Changes 卡片里，带 CI 状态。点 PR 标题旁的 ⋮：Auto-fix 让它修失败的检查，本地会话里还会处理仓库成员新留的审查意见；Merge when ready 打开 GitHub 的自动合并（本地会话请求的是 squash merge；SSH 和 WSL 会话里这一项是灰的）。这些要本机装好并登录 GitHub 的命令行 gh；SSH 会话里推分支和建 PR 都在远程机器上跑，git 和 gh 要先在那边配好。

六、预览：让它自己开浏览器看效果

它改完前端或后端，多数时候会自己起开发服务器，在 Browser 窗格里打开、截图、看报错、点按钮验证。服务器的配置存在你开会话所选文件夹下的 .claude/launch.json，一般它自己生成，命令特殊的手动改：

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000,
      "autoPort": true
    }
  ]
}

字段	说明
`runtimeExecutable`、`runtimeArgs`	起服务器的命令和参数，比如 `npm` 加 `["run", "dev"]`
`program`、`args`	直接用 `node` 跑一个脚本时用
`port`	端口，默认 3000
`cwd`	工作目录，相对项目根目录；monorepo 里前端、API 各写一项
`env`	额外的环境变量。这个文件会提交进仓库，别放密钥（密钥的放法见第二节）
`autoPort`	端口被占时：`true` 换一个空闲端口；`false` 直接报错（OAuth 回调、CORS 白名单这种必须固定端口的用）；不写时也会换端口，但端口写死在 npm、yarn、pnpm、bun 脚本里时服务器会停着不动
`url`	预览打开的地址，比如本地 HTTPS。本机地址只能写到端口为止，不能带路径和参数，端口要和 `port` 一样。只写 `url` 不写命令，就是挂到你自己已经起好的服务器上
`autoVerify`	改完自动验证，默认开；不想每次都截图验证，设成 `false`

Browser 窗格也能开外部网站看文档（Cmd+Shift+B）。它在外部网站上的点击、输入，不管什么权限模式都会过一遍安全分类器；第一次在某个网站上操作会问你 Allow once、Always allow 还是 Deny，子域名要分别批准。这个窗格是一个干净的浏览器，没有你平时的登录；要它以你的身份操作已登录的网站，用 Claude in Chrome 扩展。窗格 ⋮ 菜单里的 Keep cookies 可以让开发时的登录在退出应用后保留。

SSH 会话里它用不了 Browser 窗格，要看远程的页面，见下一节的端口转发。

七、SSH 会话：用桌面应用当界面，在远程服务器上开发

代码在云主机、开发容器或带特定环境的服务器上时，可以让 Claude Code 在那台机器上跑，桌面应用只当界面。新布局里：环境选择器 → New environment → SSH → Add SSH connection…，填名字、主机（user@hostname 或 ~/.ssh/config 里的 Host 名）、端口、私钥（可留空）、远程的 worktree 文件夹，再选远程机器上的项目文件夹，Create environment。第一次连接时应用自动在远程机器上装 Claude Code。

远程机器的要求（连不上时逐条查）：

要求	怎么查
x86_64 或 arm64，Linux 要 glibc 2.17 以上（或 musl）	`ldd --version`
SSH 服务开了 SFTP	本机 `sftp 主机` 能出现 `sftp>` 提示
一个连接允许多个会话	`sshd_config` 里 `MaxSessions` 别是 1，比如调到 10
家目录的 `~/.claude/remote/` 能执行程序，留约 1 GB 空间	不能在 `noexec` 挂载的盘上

模型请求是从远程机器发出去的。 这一点对走中转站的人最要紧：远程服务器自己要连得上模型接口。网关文档特别说明，网关开在你电脑的 localhost 上，SSH 会话用不了。

远程要走代理或自签证书的，写进那台机器上的 ~/.claude/settings.json：

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

只在远程的 ~/.zshrc、~/.profile 里 export 不算，SSH 会话不读这些文件，哪怕你在那台机器的终端里直接跑 claude 是好的。症状是会话卡住，或报 The connection from … to the API failed、Authentication failed，重新登录也没用。CA 证书要用 NODE_EXTRA_CA_CERTS，SSL_CERT_FILE 不认。改完几秒内生效。代理和证书的更多说明见《网络和数据》。

用你自己的 SSH 配置（macOS、Linux，v1.37937.0 起）：应用用的是本机的 OpenSSH（7.6 以上），主机里填 ~/.ssh/config 里的 Host 名，HostName、User、IdentityFile、ProxyJump、ProxyCommand 都照用，经跳板机也行。连接默认 30 秒超时，跳板机慢的在配置里给这台主机加 ConnectTimeout 120。

应用不替你转发端口和 agent。 你配置里的 LocalForward、ForwardAgent 这类在应用的连接上一律关闭。要在本机浏览器看远程 3000 端口上的页面，自己在本机终端里转发：

ssh -N -L 3000:localhost:3000 devbox

然后打开 http://localhost:3000。要在远程机器上 git push，在那边单独配好凭据。

断线、合盖之后任务还在不在（v2.31226.0 起）：Claude Code 在远程机器上一个后台程序下面跑，不依赖你的 SSH 连接，电脑睡眠、断网、退出应用后任务会继续，直到做完、需要你、或碰到限制。几个限制要知道：

用 Claude 账号登录的，别指望它通宵跑。 登录凭证只在应用开着、连着时续期，断开后可能几分钟就过期，任务随之停下（做过的留在远程机器上，回来发消息能接着做）。必须过夜的，保持电脑醒着、联网、应用开着，或者改用云端会话。
Windows 上的桌面应用一退出就接不回任务，任务期间别退出。走第三方配置、版本早于 v2.42304.0 的，macOS 和 Linux 上也一样。
远程机器重启，或系统在 SSH 断开时清掉你的进程（systemd-logind 的 KillUserProcesses），任务就结束了。
不在时它要你批准的操作，会在远程机器上一直等着；想少卡住，离开前选合适的权限模式，或在远程的 ~/.claude/settings.json 里配好放行规则和通知用的 hooks。
用 worktree 的会话，断开时改文件可能失败（每次等约 30 秒）。Linux 和 macOS 远程机器上多数情况能继续，例外包括：应用用的是内置的 SSH 客户端（Windows 上走第三方配置时默认如此）；macOS 远程机器上，仓库或 worktree 的路径里有中文这类非 ASCII 字符的文件夹名。
别在远程机器上对正在跑的那个对话再 claude --resume，两个进程会写同一个对话。

远程机器上的文件：应用在每个连过来的用户家目录下放了 ~/.claude/remote/（后台程序、Claude Code、日志、复制过去的插件）和 ~/.claude/uploads/（你附的文件）。进程以你 SSH 登录的那个用户运行，不需要 sudo，它能做的就是这个用户能做的。会话结束后进程不会自己退，要在连着的时候归档会话；彻底卸掉，先退出应用，再结束 pgrep -fl "$HOME/.claude/remote/" 列出的进程，删掉 ~/.claude/remote/。

服务器装了 fail2ban 之类的：应用连接失败后会探测 SSH 端口，日志里可能出现几条“登录前就断开”的连接（比如 2 分钟内 8 次）。没被封就不用管；被封了，文档给了各个 OpenSSH 版本的日志特征和放行办法。

八、窗格、查看模式和快捷键

对话、diff、浏览器、终端、文件、计划、任务、子代理几个窗格可以拖着排，也能把 diff 或终端弹成独立窗口放到另一块屏幕上。终端窗格在会话的工作目录里打开，和 Claude 用的是同一个环境。文件窗格里能直接改本地会话的文件（.mcp.json、.claude/settings.json 这类是只读的），云端、SSH、WSL 会话里只能看。右键任何文件路径可以 Open in 用 VS Code、Cursor 等打开。

查看模式：Ctrl+O 在 Normal、Thinking、Verbose 之间切换，排查它为什么做了某个动作用 Verbose。

快捷键（macOS；Windows 和 Linux 上 Cmd 换成 Ctrl，Cmd+Option 换成 Alt；切换会话、开关终端、切查看模式三类在所有平台都用 Ctrl）：

做什么	快捷键
看全部快捷键	`Cmd+/`
新会话 / 关闭会话	`Cmd+N` / `Cmd+W`
下一个 / 上一个会话	`Ctrl+Tab` / `Ctrl+Shift+Tab`
停止回复	`Esc`
开关 diff / Browser / 终端窗格	`Cmd+Shift+D` / `Cmd+Shift+B` / Ctrl+`
关掉当前窗格	`Cmd+\`
旁支对话	`Cmd+;`
权限模式 / 模型 / effort 菜单	`Cmd+Shift+M` / `Cmd+Shift+I` / `Cmd+Shift+E`
采用灰色的下一句建议	`Tab` 或 `→`

灰色的下一句建议是一个很短的后台请求生成的，算进用量或 API 费用；不想要，在 Settings → Claude Code 关掉 Prompt suggestions。

九、和命令行一起用

共用的：CLAUDE.md 和 CLAUDE.local.md，~/.claude.json 和 .mcp.json 里的 MCP 服务器，设置文件里的 hooks、skill 和权限规则。
桌面聊天那边的 MCP 也会加载进本地会话。 claude_desktop_config.json 里定义的服务器，本地 Code 会话也能用；和 ~/.claude.json、.mcp.json 里同名时，用 claude_desktop_config.json 的。另外 ~/.claude.json 和 .mcp.json 里有同名的 stdio 服务器时，桌面应用用 ~/.claude.json 的，和命令行的优先顺序相反。
把终端里的会话搬过来：终端里 /desktop，或 shell 里 claude --desktop --continue、claude --desktop --resume 会话ID（Claude Code 2.1.285 起，要 Claude 订阅登录）；或者在桌面应用的本地会话里输入 /resume，先把终端里那个会话关掉。
桌面应用里没有的：-p 和 --output-format 这类脚本用的参数、dontAsk 模式、代理团队（单个会话里的多代理可以用动态工作流）、行内的代码补全。/permissions 这类会打开终端面板的命令回复 isn't available in this environment，直接改设置文件。脚本和 CI 用命令行，见《把 Claude Code 接进脚本和 CI》。

十、定时任务、computer use 和 iOS 模拟器

定时任务：侧栏 Scheduled → New task，可以按小时、每天、工作日、每周跑。本地任务只在应用开着、电脑醒着时触发，错过了醒来只补最近的一次；云端任务关机也跑。和云端定时任务（原 routine）、/loop 的区别见《云端定时任务、桌面版定时任务和云端环境》。
computer use：让它打开应用、点屏幕，处理没有命令行的图形界面工具。macOS 和 Windows 上的研究预览，要 Pro 或 Max，Team、Enterprise 没有，默认关闭。它在你真实的桌面上操作，和沙箱里的命令不是一个安全级别，开之前想清楚。
iOS 模拟器窗格：macOS 上的公开测试版，它构建、运行 iOS 应用时自动打开，只在本地会话里有，不需要开 computer use。

十一、出了问题先查

现象	先做什么
Code 标签页报 `Error 403: Forbidden` 或认证失败	退出登录再登录；确认有付费订阅；命令行能用、桌面不行的，彻底退出应用再开
启动白屏或卡住	重启；装上待装的更新；公司网络看防火墙放没放行 Anthropic 的地址（第一节）
`Failed to load session`	文件夹还在不在；仓库要 Git LFS 而没装；文件权限
会话找不到 `npm`、`node`	普通终端里能用的话，查 shell 配置里的 PATH，重启桌面应用
“Git is required” 或要 Git LFS	装 Git（Windows 上装 Git for Windows），或从 git-lfs.com 装 Git LFS 后 `git lfs install`，重启应用
环境变量设了不生效	第二节：有的变量应用自己设；开发服务器不读保存的环境
SSH 登录后连接失败	卡片上点 View details，按代码查：`[SFTP_UNAVAILABLE]` 开 SFTP，`[SESSION_LIMIT]` 调 `MaxSessions`，`[ENOSPC]` 腾磁盘空间，`[CLI_UNRESPONSIVE]` 等一分钟再试
SSH 会话卡住或报连不上 API	远程机器自己连得上模型接口吗；代理和证书写进远程的 `~/.claude/settings.json` 了吗（第七节）
从命令行打开云端会话提示分支不存在	复制分支名，`git fetch origin 分支名` 再 `git checkout`

要日志：Help → Troubleshooting → Show Logs in Finder（Windows 是 File Explorer，Linux 是 File Manager），SSH 的记录在 ssh.log 里；远程那边的在 ~/.claude/remote/run/ 下的 remote-server.log。发给别人前先看一遍，可能带着主机名和路径。

这篇没有覆盖到的

全篇没有实测。 按钮、菜单和版本号照 2026-10-21 的官方文档写。
走中转站时哪些功能能用，文档只对网关和第三方部署说了一部分，没写的本站没有核对；第三方部署的完整说明在 claude.com 上另一套文档里，本站没有对照。
企业部署和管理策略（受管设置、SSO、MDM 分发、限制 SSH 主机）、Dispatch、云端会话的多仓库和 Projects 只提了名字。
Windows 远程机器上 SSH 会话的限制比 Linux 多（终端、沙箱、插件、MCP 都有出入），文档说测得也少，这里没有展开。