在远程 VPS 上使用 Claude Code、Claude CLI 与 Claude Desktop——安装、登录、远程控制和文件传输完整指南

一、先分清 Claude 应用与四种远程方式

Claude Code 是 Anthropic 的编程智能体，可以读取项目、修改文件、执行命令和测试。通常所说的 Claude CLI 就是其命令行程序 claude。Claude Desktop 则包含 Chat、Cowork 和 Code 等标签，Code 已集成 Claude Code，不要求另外安装 CLI。

• SSH 到 VPS 后运行 claude：程序和项目都在 VPS，文字通过 SSH 显示在自己的电脑上。
• 本地 Claude Desktop 连接 VPS 的 SSH 环境：图形界面在本地，Claude Code 引擎在 VPS 上运行。
• Remote Control：Claude Code 在 VPS 持续运行，通过另一台电脑、手机或浏览器控制。
• Cloud Session：任务运行在 Anthropic 管理的云环境，而不是你的 VPS。
• 完整远程桌面：Windows 用 RDP、macOS 用屏幕共享、Linux 用 RDP/X2Go/VNC，除非确有需要，否则不必为 Claude 专门安装整套 GUI。

二、数据传输路径：会话同步不等于文件同步

• SSH + CLI：VPS 读取、修改文件并执行命令，本地只显示终端文字，文件不会自动同步到本地。
• 本地 Desktop + SSH：本地显示对话、权限提示和 Diff，VPS 执行 Claude Code、Git 和项目命令，远程文件仍主要保存在 VPS。
• Remote Control：VPS 执行代码和访问文件，对话与工具活动通过 Anthropic API 同步，其他设备查看和控制。
• Remote Control 连接期间，会话记录会存储在 Anthropic 服务器上用于多设备同步；代码执行和文件访问仍在 VPS。
• 因此 Remote Control 不是 VPS 到本地电脑的点对点直连，也不是完整的磁盘同步。真正的文件回传仍需 Git、SCP 或 rsync。

三、准备 VPS 与安全访问

• Claude Code 当前要求包括 4 GB 以上内存、x64 或 ARM64、HTTPS 网络和受支持地区。模型计算在云端，普通 VPS 不需要 GPU。
• 为每位使用者创建独立普通账号，不要直接用 root 运行 Claude；只使用 SSH 密钥，限制密码登录和来源 IP。
• 不开放多余的 Claude、VNC、RDP 或开发服务器端口；Remote Control 只需要出站 HTTPS。
• 项目放在普通用户有权限的目录。远程进程拥有的权限，就是 SSH 用户的权限。
• 首次连接通过服务商控制台或其他可信渠道核对主机指纹，不要设置 StrictHostKeyChecking no。

# Linux 上先检查系统、架构、内存和磁盘
cat /etc/os-release
uname -m
free -h
df -h "$HOME"

# 本地 ~/.ssh/config 示例（核对并保存主机密钥后使用）
Host vps-claude
  HostName 203.0.113.10
  User dev
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  StrictHostKeyChecking yes
  ServerAliveInterval 60
  ServerAliveCountMax 3

# 测试连接
ssh vps-claude

四、在 Linux VPS 上安装 Claude Code

• Ubuntu/Debian：先安装 curl、ca-certificates、git、tmux，再运行官方原生安装器。
• Fedora/RHEL：使用 dnf 安装相同工具；若 tmux 不在已启用仓库中，使用系统认可的仓库或 screen，不要下载不明二进制。
• Alpine：使用 musl，需要 bash、curl、libgcc、libstdc++、ripgrep 等依赖，并将 USE_BUILTIN_RIPGREP 设为 0。
• 生产环境也可使用 Anthropic 的签名 apt、dnf 或 apk 仓库，添加前核对官方签名指纹。

# Ubuntu / Debian
sudo apt update
sudo apt install -y curl ca-certificates git tmux

# Fedora / RHEL 使用：sudo dnf install -y curl ca-certificates git tmux

# 官方原生安装器（macOS、Linux、WSL 同样适用）
curl -fsSL https://claude.ai/install.sh | bash

# 重新打开终端后验证
claude --version
claude doctor

# 如果提示 command not found
export PATH="$HOME/.local/bin:$PATH"
claude --version

# 非交互式 SSH 可使用绝对路径
~/.local/bin/claude --version

# Alpine 额外依赖
apk add bash curl libgcc libstdc++ ripgrep git tmux

五、Windows Server 与 macOS 远程主机

• Claude Code CLI 支持 Windows Server 2019 及以上。在普通用户 PowerShell 中运行 irm https://claude.ai/install.ps1 | iex，再用 claude --version 和 claude doctor 验证。
• CLI 支持 Windows Server，不代表 Claude Desktop 的全部图形功能自动支持同一服务器系统；纯服务器任务优先 CLI。
• 若要让本地 Desktop 通过 SSH 连接 Windows 主机，应安装 Microsoft OpenSSH Server，并确认 SFTP 和远程进程行为。
• macOS 可使用同一个原生安装器，或 brew install --cask claude-code；它既可直接通过 SSH 使用，也可作为本地 Desktop 的远程主机。

六、无浏览器 VPS 上的登录与凭据

• 进入项目目录运行 claude，复制终端显示的登录 URL 到自己电脑的浏览器完成授权。
• 如果浏览器无法连接 VPS 的本地回调地址，会显示登录代码，将代码粘贴回 VPS 的 Paste code here if prompted。
• 使用 /status 检查认证，/logout 退出，/login 重新登录。Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账号，免费 claude.ai 套餐不包含它。
• ANTHROPIC_API_KEY 与 Claude 订阅是不同的认证和计费方式，不要把真实密钥写入仓库、Dockerfile、截图或 shell 历史。
• claude setup-token 适合 CI 和脚本，但令牌只能发起模型请求，不能建立 Remote Control 或获取 claude.ai 连接器。
• Linux 凭据通常位于 ~/.claude/.credentials.json，权限为 0600，不要上传或公开同步。

# 在 Bash 中交互读取 API Key，避免真实密钥进入命令历史
read -rsp "Anthropic API key: " ANTHROPIC_API_KEY; echo
export ANTHROPIC_API_KEY
claude

# 只检查凭据文件权限，不读取内容
stat -c '%a %U %n' ~/.claude/.credentials.json

七、用 tmux 保持 VPS 会话

• 创建会话：tmux new -s claude-vps。
• 在 tmux 中进入项目并运行 claude。
• 先按 Ctrl+B，再按 D，离开但保持进程运行。
• 重新连接后使用 tmux attach -t claude-vps 恢复，tmux ls 查看会话。
• 需要一次性把文字结果保存到本地时，可通过非交互式 SSH 执行 claude -p 并重定向输出。

tmux new -s claude-vps
cd /srv/my-project
claude

# 重新连接后
tmux attach -t claude-vps
tmux ls

# 在 VPS 执行摘要任务，结果保存到自己的电脑
ssh vps-claude 'cd /srv/my-project && ~/.local/bin/claude -p "Summarize this project"' > ./project-summary.md

八、用 Remote Control 从自己的设备控制 VPS

Remote Control 只发起出站 HTTPS，不需要开放入站端口。对话、回复和工具活动经 Anthropic API 同步并存储，代码与文件仍留在 VPS。附件可上传到 VPS，常见位置为 ~/.claude/uploads/；生成的项目文件仍需通过 Git、SCP 或 rsync 取回。

• 要求 Pro、Max、Team 或 Enterprise 订阅，以及完整的 claude.ai /login。API Key、setup-token、Bedrock、Vertex、Foundry 和某些自定义 API Base URL 不适用。
• VPS 必须保持开机，claude 进程必须持续运行；组织管理员也可能禁用该功能。
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_GROWTHBOOK 等设置可能影响功能，订阅登录被 API Key 覆盖时先 unset 再重新 /login。
• 服务器模式使用 claude remote-control；同时保留本地交互使用 claude --remote-control "VPS Project"；已有会话中输入 /remote-control。
• 首次确认后，终端显示会话 URL 和二维码，可在自己的浏览器打开 claude.ai/code 或用 Claude App 连接同一账号。
• 多个会话同时修改项目时可考虑 --spawn worktree，减少同目录冲突。

tmux new -s claude-remote
cd /srv/my-project

# 服务器模式
claude remote-control

# 多会话使用独立 worktree
claude remote-control --spawn worktree

# 保留 VPS 终端交互，同时允许其他设备连接
claude --remote-control "VPS Project"

九、推荐图形方案：本地 Claude Desktop 连接 VPS

Desktop 会把回复、工具输出、权限提示和 Diff 流式传回本地，但编辑和 Git 操作仍在 VPS。长时间任务还受凭据续期、VPS 重启、KillUserProcesses、Desktop 更新和工具在线状态影响；自己的电脑必须关机时，优先 Cloud Session，而不是假设 Desktop SSH 一定能整夜运行。

• 在自己的电脑安装官方 Claude Desktop 并登录，打开 Code 标签；macOS、Windows 和 Ubuntu/Debian Linux beta 均可，无需另外安装 Node.js 或 CLI。
• 打开环境选择器 → New environment → SSH → Add SSH connection…。
• 填写 Name、SSH host（user@hostname 或 ~/.ssh/config 中的 Host）、SSH port、可选的本地私钥路径和 Worktree folder。
• 选择远程项目目录并 Create environment。第一次连接时，Desktop 会在 VPS 的 ~/.claude/remote/ 安装引擎和辅助程序，不需要 sudo。
• 每位连接用户约需 1 GB 空间，主目录必须可写、可执行且不能是 noexec。
• VPS 需要 SSH + SFTP、正常 shell、网络、Git，以及一个连接承载多个会话；MaxSessions 1 会导致失败。

# 通过跳板机的 ~/.ssh/config 示例
Host devbox
  HostName devbox.internal.example.com
  User dev
  ProxyJump bastion.example.com

# Desktop 的 SSH host 可填写 devbox
# Windows 的客户端行为不同，ProxyJump 需按版本检查 system-openssh 要求

# 独立测试 SFTP
sftp vps-claude

十、确实要在 VPS 图形桌面中运行 Claude Desktop

• Linux Desktop beta 要求 Ubuntu 22.04+ 或 Debian 12+、x86_64/arm64、图形桌面和可用密钥环；这与 CLI 的系统要求不同。
• 不要以 root 启动 claude-desktop；密钥环被锁定时，登录状态可能无法保存。
• Cowork 还需要 QEMU、KVM、/dev/kvm 等虚拟化条件。很多 VPS 不支持嵌套虚拟化，此时使用 Code 标签或 CLI，不要强行配置 Cowork。
• Windows 图形主机通过受保护的 RDP 安装和登录，RDP 3389 不应对全网开放。
• macOS 通过屏幕共享安装和登录，VNC 5900 应使用 VPN 或 SSH 隧道，不要直接暴露公网。

# Ubuntu / Debian 添加 Claude Desktop 官方仓库
sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc   https://downloads.claude.ai/claude-desktop/key.asc

gpg --show-keys /usr/share/keyrings/claude-desktop-archive-keyring.asc
# 指纹：31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE

echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main"   | sudo tee /etc/apt/sources.list.d/claude-desktop.list

sudo apt update
sudo apt install claude-desktop
claude-desktop

# 将远程 VNC 映射到本地（不要把 5900 暴露到公网）
ssh -L 127.0.0.1:5900:127.0.0.1:5900 vps-claude

十一、把信息、文件和 Web 预览带回自己的电脑

• 小文本结果：通过 SSH 读取并重定向到本地文件。
• 上传和下载单文件：使用 scp；目录增量同步使用 rsync，初次不要加 --delete。
• 代码项目优先用 Git 保留历史、Diff 和回滚能力，不要反复复制整个目录。
• Remote Control 上传的附件可到达 VPS，但生成文件仍应通过 Git、SCP 或 rsync 取回。
• Web 应用预览使用 SSH 本地端口转发，不需要把开发端口开放到公网。

# 小文本下载
ssh vps-claude 'cat /srv/my-project/result.md' > ./result.md

# 上传文件到 VPS
scp ./input.zip vps-claude:/srv/my-project/

# 从 VPS 下载文件
scp vps-claude:/srv/my-project/result.md ./result.md

# 上传目录内容
rsync -av --partial --progress ./my-project/ vps-claude:/srv/my-project/

# 下载目录内容
rsync -av --partial --progress vps-claude:/srv/my-project/ ./my-project/

# 在 VPS 检查代码改动
git status
git diff

# VPS 的 127.0.0.1:3000 映射到本地相同地址
ssh -L 127.0.0.1:3000:127.0.0.1:3000 vps-claude
# 然后访问 http://127.0.0.1:3000

十二、容器、跳板机和受限网络

• Dev Container 可使用官方 Claude Code Feature，并通过命名卷持久化认证和设置；不要把凭据写入镜像或执行包含凭据的 docker commit。
• 不要挂载宿主机整个 ~/.ssh，优先短期令牌或 secret 管理；项目目录与 Claude 配置目录分开考虑。
• 没有公网 IP 时，Remote Control 仍只需出站 HTTPS；SSH 可使用跳板机、WireGuard、Tailscale 或企业 VPN。
• Linux VPS 需要代理或企业 CA 时，可在 ~/.claude/settings.json 设置 HTTPS_PROXY 和 NODE_EXTRA_CA_CERTS；Desktop SSH 不一定读取 ~/.bashrc。
• 不要为了绕过证书问题关闭 TLS 验证。

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

// devcontainer.json 中持久化配置的示例
"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
}

十三、安全与故障排查清单

• 浏览器登录完成但终端未完成：复制浏览器显示的登录代码到 VPS，SSH/容器中的本地回调经常不可达。
• claude 不存在：检查 ~/.local/bin 是否在 PATH，使用 claude doctor，非交互式 SSH 使用绝对路径。
• Remote Control 提示需要订阅认证：检查 API Key、CLAUDE_CODE_OAUTH_TOKEN、setup-token、第三方提供商、自定义 Base URL 和组织策略，然后完整 /login。
• Desktop 能 SSH 登录但创建环境失败：检查 SFTP、MaxSessions、主目录权限、noexec、磁盘、出站网络和远程 settings.json 代理。
• SSH 断开后任务消失：检查是否使用 tmux、KillUserProcesses、VPS 重启、凭据续期和辅助程序替换。
• 生产 VPS 不建议使用 --dangerously-skip-permissions。初次使用选择 Manual 或 Plan，只授予任务需要的权限。
• 若需要电脑关机后仍持续执行，使用 Cloud Session 或专门设计的服务器端任务与凭据续期机制。