Claude Code 怎么连接远程服务器（SSH）：桌面版加 SSH 环境，或登录服务器后在终端里直接用

本文根据 Claude Code 官方文档《Use Claude Code Desktop》《Troubleshoot installation and login》《Voice dictation》《Configure your terminal》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 代码在云服务器、开发机或有特殊硬件的机器上，想让 Claude Code 直接在那台机器上干活的人；
• 搜「claude code ssh 连接服务器」，不知道应该在本机装还是在服务器上装的人；
• SSH 连上了，但登录、复制或通知出问题的人。

结论先说

1. 官方有两种做法：①在桌面版的 Code 标签页里添加 SSH 环境，Claude Code 在远程机器上运行，你用桌面版当界面；②自己 ssh 登录服务器，在服务器的终端里安装 Claude Code 并运行 claude。
2. 用桌面版的 SSH 环境，不需要手动在服务器上装 Claude Code，官方说桌面版首次连接时会自动安装。
3. 服务器要求：Linux 或 macOS 要 x86_64 或 arm64；SSH 服务要开启 SFTP 子系统；登录不能需要交互输入（比如用 SSH agent 里的密钥）；Claude Code 装到 ~/.claude/remote/，每个连接的用户大约需要 1 GB。
4. 在服务器终端里用，登录要走「复制链接」的路线：浏览器打不开时按 c 复制登录链接，在你本机的浏览器里打开，再把页面上的代码粘贴回终端。
5. 语音输入在 SSH 会话里不能用，官方写明需要本机麦克风，见 /guides/claude-code-voice-input-dictation。

图：本站根据 Claude Code 官方文档：Use Claude Code Desktop 整理的示意图

一、做法一：桌面版添加 SSH 环境

桌面版 Code 标签页的环境类型有 Local、Cloud、SSH，Windows 上还有 WSL。步骤：

1. 在提示框下方的环境选择器里，选菜单底部的 New environment；
2. 在 New environment 对话框的 SSH 标签里，打开 Host 列表，选 Add SSH connection…，填写：

• Name：随便起个名字；
• SSH host：user@hostname，或你在 ~/.ssh/config 里定义的主机别名；
• SSH port：不填默认 22；
• SSH key (optional)：如 ~/.ssh/id_ed25519，留空则用你的 SSH 配置或 SSH agent；
• Worktree folder：如 ~/worktrees，留空用远程机器的默认位置；

1. 点 Add SSH connection；
2. 选远程机器上的文件夹，点 Create environment，然后输入任务按 Enter。

官方给了一个用 ~/.ssh/config 别名的例子：

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

在 SSH host 里直接填 devbox 即可。macOS 和 Linux 上，桌面版用你电脑上的 OpenSSH 客户端，所以 ~/.ssh/config 生效（官方要求 OpenSSH 7.6 或更新，用 ssh -V 查看）。Windows 上要满足一定条件才用系统的 OpenSSH 客户端，否则用桌面版内置客户端，内置客户端会忽略 CertificateFile，在条目设了 ProxyJump 时会失败。桌面版的整体介绍见 /guides/claude-code-desktop。

服务器要满足什么

官方的要求清单（Linux 和 macOS 服务器）：

• 系统：x86_64 或 arm64 处理器，满足 Claude Code 的系统要求；Linux 需要 glibc 2.17 或更新，或 musl；
• SFTP：SSH 服务器要提供 SFTP 子系统（sshd_config 里有 Subsystem sftp 一行），可以在本机用 sftp 连一下，看到 sftp> 提示符就是通的；
• MaxSessions 1：服务器如果设了这个，要么更新桌面版，要么改用 OpenSSH 客户端，要么调高 MaxSessions；
• 登录方式：用不需要交互的登录，如 SSH agent 里的密钥。桌面版每次连接至少要登录两次，一次性验证码会让 ! 开头的命令失败，这类命令请改在终端标签页里跑；
• 安装位置：~/.claude/remote/ 不能在 noexec 挂载上；
• 网络：服务器要能访问 Claude Code 所需的网络地址；如果服务器自己下不了，桌面版会在你电脑上下载后再上传。

用桌面版 SSH 时有哪些限制

官方列出的不可用或有变化的功能：浏览器窗格工具和开发服务器菜单不可用；「Merge when ready」在 SSH 和 WSL 会话里被禁用；创建 PR 前要自己在远程机器上装好并登录 git 和 gh；不能把 SSH 会话用 Open in > Cloud 搬到云端；网络断开时，运行中的任务可以继续，但用 Claude 账号登录时，登录过期可能让它停止。

二、做法二：自己 SSH 登录服务器，在终端里用

不想用桌面版时，就是普通的 ssh user@host 登录服务器，然后按官方的安装方法装 Claude Code，各平台怎么装见 /guides/claude-code-install-methods-git-npm-official。Linux、macOS 上官方的安装脚本是：

bash
curl -fsSL https://claude.ai/install.sh | bash

装完运行 claude，需要登录时走下面的流程。

登录：官方在认证排查里写明，没有浏览器、或浏览器登录后报 localhost 连接错误时，可以这样做：

1. 在登录提示处按 c 复制登录链接（用 claude auth login 则复制它打印的链接）；
2. 在你本机的浏览器里打开链接并登录，页面上会显示一个代码，而不是跳回 localhost；
3. 把代码粘贴到终端里 Paste code here 开头的提示处。

如果粘贴没有反应，官方建议用终端的另一种粘贴快捷键，或者直接用 claude auth login，它从标准输入读取粘贴的代码。

服务器要求：官方说 Claude Code 至少需要 4 GB 内存，安装本身约需要 512 MB 空闲内存。内存小的 VPS 上，安装可能被系统杀掉并报 Killed，对应的处理见 /guides/claude-code-install-slow-stuck-failed。

凭据存在哪：Linux 上登录凭据存在 ~/.claude/.credentials.json，权限 0600。这是官方对凭据位置的说明，由此可以推断：在别人也能登录的共用服务器上登录自己的账号要谨慎（这是本文的提醒，官方没有就此单独写建议）。

三、SSH 下常见问题

图：本站根据 Claude Code 官方文档：Use Claude Code Desktop 与 Troubleshoot installation and login 整理的示意图

第一次连接弹出主机指纹确认。 官方说：弹出 Connect to <host> for the first time? 或 Review new key 时，要拿你在这台机器上自己查到的指纹，而不是通过正在检查的这条连接去核对，一致才选 Trust and connect 或 Trust new key，否则选 Cancel。

连不上 API、报证书错误。 官方说 shell 配置里的 HTTPS_PROXY 这类变量不会传给 SSH 会话。要在远程机器的 ~/.claude/settings.json 里的 env 下添加，CA 证书用 NODE_EXTRA_CA_CERTS：

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

这只适用于你的网络本来就要求走公司代理的情形。

复制的内容进不了本机剪贴板。 Claude Code 在远程机器上运行时，无法调用你本机的剪贴板工具，/copy 会通过 OSC 52 转义序列让终端去写剪贴板，是否生效取决于终端。官方说 iTerm2 默认忽略，需要在 Settings > General > Selection 里打开 Applications in terminal may access clipboard；macOS 自带的终端 Terminal.app 不支持。替代办法是 /copy 选择框里按 w 写入文件。官方原文在 Troubleshooting 页。

远程会话怎么收到「Claude 做完了」的提醒。 官方说桌面通知能通过 SSH 到达你的本机：Ghostty 和 Kitty 无需额外设置，iTerm2 需要在 Settings > Profiles > Terminal 里开启 Notification Center Alerts 并启用 Send escape sequence-generated alerts。通知的完整设置见 /guides/claude-code-task-done-notification-sound-windows。

想继续在手机或别的设备上看这个会话。 官方另有 Remote Control 功能，可以在手机、平板或浏览器里继续本地会话，说明见官方 Remote Control 页面。

常见问题

Q：服务器上一定要手动装 Claude Code 吗？

用桌面版 SSH 环境不用，桌面版会自动装；自己登录服务器用终端就要自己装。

Q：服务器在内网、连不上外网怎么办？

官方说，桌面版在服务器自己下载不了时，会在你电脑上下载再上传到服务器。但 Claude Code 运行时仍需要访问官方要求的网络地址，具体清单见官方的 Network configuration 页面。

Q：SSH 过程中断开会怎样？

官方说桌面版里运行中的任务可以在断开期间继续，但用 Claude 账号登录时，登录过期可能让任务停止；重连后若 Claude 没有自动继续，发一条消息，它会从已保存的对话历史接着做。

相关教程

• /guides/claude-code-getting-started：Claude Code 入门
• /guides/claude-code-common-errors：常见报错

参考资料

• Claude Code 官方文档：Use Claude Code Desktop — https://code.claude.com/docs/en/desktop
• Claude Code 官方文档：Troubleshoot installation and login — https://code.claude.com/docs/en/troubleshoot-install
• Claude Code 官方文档：Voice dictation — https://code.claude.com/docs/en/voice-dictation
• Claude Code 官方文档：Configure your terminal — https://code.claude.com/docs/en/terminal-config