camilbenameur/remote-devbox

remote-devbox 是做什么的？

你正在搭建（或修复）一个 devbox：一台 Linux 服务器，Claude Code 会话在其中运行，而用户电脑上的 Claude Desktop 应用仅作为界面。请按顺序完成各阶段。每个阶段说明了由你完成、仅由用户完成以及如何验证成功的内容。

<skill> 指包含本文件的文件夹。

用户将获得

• Desktop 应用的 Code 标签页保持不变，但每个会话在 devbox 上通过 SSH 运行：shell、测试、安装、Python、Node、Chrome。用户电脑只负责绘制界面。
• 用户自己的订阅，而非 API 额度。Desktop 应用会传递并刷新会话的登录状态。切勿在 devbox 上设置 ANTHROPIC_API_KEY：否则计费将转移到 API。
• 两个作为 MCP 服务器的浏览器：chrome（一个共享的 Chrome，已登录用户的账户）和 playwright（每个会话独立的空白 Chrome）。虚拟屏幕（noVNC）使用户可以在其私有网络的任何浏览器中查看共享 Chrome。
• 会话在用户电脑关机后仍持续运行：devbox-relay 在后台恢复断开的 Desktop 会话，devbox-rc 托管从 claude.ai/code 或手机应用启动的会话。
• 与本地电脑相同的全局 CLAUDE.md、skills、memory 和插件钩子。

如需内部机制，请阅读 references/how-it-works.md；如果出现故障，请立即查阅 references/troubleshooting.md。

你的基本规则

• 用户负责：付款和订购、所有密码和登录（提供商、Tailscale、GitHub 设备码、Claude /login、共享 Chrome 中的网站）、在 Desktop 应用设置中的点击，以及 Tailscale 管理控制台。请一次给出精确的链接或命令，然后等待。切勿自行输入密码、卡号或一次性验证码。
• 在订购任何内容前，说明计划、价格和承诺，并得到用户的同意。
• 设置脚本是幂等的：当某个脚本失败时，阅读错误信息，修复原因，然后重新运行。
• 在 devbox 上，sudo 不需要密码。但对于脚本本身不会进行的系统更改（软件包、服务、防火墙、sshd、用户），仍需先询问用户。
• 在用户的 devbox 上操作时，切勿在不提前告知的情况下停止 devbox-* 服务、编辑 ~/.claude 或替换 ~/.local/bin 中的二进制文件：他们的会话可能正在运行。

阶段 0：检查电脑

1. 平台。Windows：脚本位于 <skill>/client/windows/（Windows PowerShell 5.1 即可）。macOS 或 Linux：<skill>/client/unix/。
2. 仅 Windows：需要 OpenSSH 客户端 9.4 或更高版本（ssh -V）。Desktop 应用需要它。如果版本较旧：winget install Microsoft.OpenSSH.Preview。
3. Claude Desktop 应用已安装并登录，且用户的计划包含 Claude Code。
4. git config --global user.name 和 user.email 已设置（脚本会将其复制到 devbox）。
5. 询问用户需要哪些可选部分：gatehaul（在 GitHub Codespaces 中运行繁重构建，-Gatehaul / --gatehaul）、共享的已登录 Chrome（默认开启）、memory 复制。

阶段 1：选择并订购服务器

参考 references/providers.md。要求：KVM 虚拟机、Ubuntu 24.04、优先 x86_64（arm64 也可用但未经完整端到端测试）、至少 8 GB 内存（并行多会话加 Chrome 需要 16 到 24 GB）、80 GB 磁盘，以及提供商提供的网页控制台（如果 SSH 被锁定，这是救援路径）。

帮助用户比较，然后如果你有浏览器，为他们打开订购页面。用户选择方案、付款并确认。如果提供商在订购时要求 SSH 密钥，请先显示它：

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -ShowKey

bash <skill>/client/unix/setup-devbox.sh --show-key

向用户索取公网 IP 和初始用户名（通常是 root；OVH 和 Oracle 上为 ubuntu）。

阶段 2：引导服务器

powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -HostAddress <IP> -InitialUser root

bash <skill>/client/unix/setup-devbox.sh --host <IP> --initial-user root

在用户可输入的终端中运行（Desktop 应用的终端面板，或请用户自行运行）。它需要用户提供三样内容：

1. 主机密钥指纹。 脚本会显示它并询问是/否。请用户将其与提供商网页控制台中 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub 的输出进行比较。
2. 初始密码，仅一次，用于授权密钥（如果在订购时提供了密钥，则跳过此步）。
3. GitHub 设备码：gh auth login 会打印一个码和一个链接。

脚本执行内容：创建密钥 ~/.ssh/devbox_ed25519（无密码短语，Desktop 应用必须无需提示即可连接）、运行 host/10-root-bootstrap.sh（创建 dev 用户并赋予 sudo 权限、仅密钥 SSH、linger、swap、Node、gh、Chrome、Tailscale、ufw、fail2ban、无人值守升级、虚拟屏幕软件包）、将 Host devbox 块添加到 ~/.ssh/config、测试连接、将 SSH 限制为仅 dev 用户、运行 host/20-user-setup.sh（uv、Claude Code CLI、可选的 gatehaul、MCP 服务器、~/.local/bin 工具、虚拟屏幕服务、中继服务和钩子），然后同步 Claude 配置（阶段 6）。

验证：ssh devbox 'claude --version; claude mcp list; systemctl --user is-active devbox-vnc devbox-chrome devbox-relay'。

阶段 3：私有网络，然后关闭公网 SSH

1. 用户：在电脑上安装 Tailscale 并登录（winget install tailscale.tailscale、Mac App Store 或 tailscale.com/download）。
2. 在 devbox 上：ssh -t devbox sudo tailscale up --hostname=devbox。它会打印一个登录链接：由用户打开。
3. 用户：进入 Tailscale 管理控制台，Machines，选择 devbox，禁用密钥过期。否则 devbox 会在 180 天后离开网络，只剩下提供商控制台可用。
4. 在 ~/.ssh/config 中，将 devbox 块的 HostName 设置为 devbox（MagicDNS）或 ssh devbox tailscale ip -4 返回的地址。验证 ssh devbox true。
5. 关闭公网 SSH：ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'。如果有未通过 Tailscale 连接的 SSH 会话（包括在公网 IP 上打开的 Desktop 应用会话），脚本会拒绝执行：请先关闭这些会话。

锁定救援：使用提供商网页控制台，然后执行 sudo ufw allow OpenSSH。

阶段 4：连接 Desktop 应用

用户在 Desktop 应用中：点击 Code 标签页，提示框下方的环境菜单，选择 新环境，SSH（标签可能随版本移动）：

字段	值
SSH 主机	devbox（取自 ~/.ssh/config）
SSH 密钥	留空
工作目录	~/worktrees
会话文件夹	~/dev/<project>

首次连接时，应用会在 devbox 的 ~/.claude/remote/ 下安装自己的引擎并显示主机密钥：指纹与阶段 2 中相同。该环境中的会话将在 devbox 上运行。SSH 会话中没有浏览器面板：请改用端口转发（见“日常使用”）。

阶段 5：已登录的 Chrome

1. ssh devbox devbox-browser login（Chrome 会在没有调试端口的情况下重启，因为 Google 通常拒绝在带有调试端口的 Chrome 中登录）。
2. 用户在 tailnet 中的机器上打开 http://devbox:6080/vnc.html。密码：ssh devbox devbox-browser password。如果没有 Tailscale：ssh -N -L 6080:localhost:6080 devbox 然后打开 http://localhost:6080/vnc.html。
3. 用户登录代理应使用的网站。建议避免登录银行和任何注入指令可能造成经济损失的网站：因为每个会话都可以驱动这个浏览器。
4. ssh devbox devbox-browser normal 将浏览器交还给代理（调试端口 9222，仅本地监听）。

验证：在 devbox 会话中，要求 chrome MCP 打开一个用户已登录的网站，并确认用户账户可见，但不要读取隐私内容。任务栏图标和屏幕的右键菜单可以打开这个 Chrome；它也是 devbox 的默认浏览器。

阶段 6：镜像本地 Claude 环境

目标：devbox 上的会话行为与电脑上的相同。

1. 全局 CLAUDE.md 和 skills：

   powershell -ExecutionPolicy Bypass -File <skill>\client\windows\sync-claude-config.ps1 -Memory
   

   bash <skill>/client/unix/sync-claude-config.sh --memory
   

   脚本将 <skill>/templates/host-header.md（devbox 上的差异内容：路径、浏览器、屏幕、连续性、sudo 规则）添加到本地的 ~/.claude/CLAUDE.md 之前，合并 ~/.claude/skills（排除 .venv、node_modules、.git），并使用 -Memory 参数将本地项目文件夹（-LocalDevDir，默认为 ~/Documents/dev）的自动记忆复制到 devbox 上 ~/dev 的记忆中。每当本地 CLAUDE.md 或 skills 发生变化时重新运行此脚本。编辑标头模板，而不是 devbox 上的副本，因为后者会被覆盖。
2. 需要设置的 skills：对于每个同步的 skill，检查 SKILL.md 中的 Python 环境（requirements.txt、pyproject.toml）、Node 包、二进制文件和 Windows 路径。在 devbox 上重建环境并修正路径。询问用户后，安装他们需要的系统工具（例如 ffmpeg）。
3. 插件：Desktop 应用会在 SSH 会话中安装用户的插件，但它们的钩子不会在 SSH 会话中运行。对于每个已启用且包含 hooks/hooks.json 的插件，将其源代码克隆到 devbox 的 ~/.claude/hooks-thirdparty/<plugin>，保持相同的提交，并将其钩子合并到 devbox 的 ~/.claude/settings.json 中，将 ${CLAUDE_PLUGIN_ROOT} 替换为该文件夹，并将解释器调整为 Linux 格式（python 改为 python3）。使用 jq 进行合并；保留现有的 devbox-relay guard SessionStart 钩子。在启用前阅读钩子脚本。
4. MCP 服务器：比较本地和 devbox 上的 claude mcp list。重新添加在 Linux 上有意义的用户级 stdio 服务器。claude.ai 连接器跟随账户：无需操作。
5. 项目：使用 gh repo clone 克隆到 ~/dev/<name>。复制重要的未提交或未跟踪的本地文件（仅在有用户同意时复制 .env 文件），安装依赖项，运行轻量测试。如果安装了 gatehaul，繁重的构建应通过 gatehaul 在 Codespaces 中进行。
6. 无需用户在场的长时间迁移：如果需迁移的内容较多，请编写工作列表，然后使用 references/setup-agent-prompt.md 通过 claude-task 在 devbox 上启动一个自主会话。

阶段 7：电脑关机后继续运行的会话

1. 在 devbox 上通过 CLI 登录（中继和远程控制使用此登录）：ssh -t devbox claude，然后 /login；用户打开链接并粘贴验证码；然后 /exit。
2. 中继：已由 20-user-setup.sh 启用。验证 ssh devbox devbox-relay test（所有情况均正常）和 ssh devbox devbox-relay status。
3. 远程控制服务器，需要手动执行一次，因为它会要求两次确认：ssh -t devbox 'cd ~/dev && claude remote-control'，用户回答两次 y，然后按 Ctrl+C。接着执行 ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'。在 claude.ai/code 或手机应用中，以文件夹名和主机名命名的环境（例如 dev · <hostname>）现在会在 devbox 上启动会话。选择 自动 权限模式，以便会话可以独立进行。claude.ai 可能会要求用户再次登录以验证设备。
4. 可选的真实测试（与用户一起）：在 Desktop 会话中启动一个会在权限提示处停止的小任务，用户退出 Desktop 应用，等待约 30 分钟，然后重新打开应用；日志 ~/dev/_relay/log.md 会显示中继内容，devbox 上的 claude agents 会显示 relay · <name>，重新打开的原会话会显示已被中继。

阶段 8：最终检查

运行并报告每一行：

ssh devbox 'claude --version; gh auth status 2>&1 | head -3; claude mcp list'
ssh devbox 'systemctl --user is-active devbox-vnc devbox-wm devbox-novnc devbox-panel devbox-chrome devbox-relay devbox-rc'
ssh devbox 'devbox-browser status; devbox-relay test | tail -1; free -h; df -h ~'
ssh devbox 'grep -c ANTHROPIC_API_KEY ~/.bashrc ~/.profile 2>/dev/null; sudo ufw status'

预期结果：所有服务均为 active（devbox-rc 仅在阶段 7 之后），MCP 服务器 chrome 和 playwright 已连接，无 API 密钥，ufw 仅允许 tailscale0（和 41641/udp）。然后告知用户哪些已就绪、他们仍需做什么以及如何访问每个部分。

日常使用（告知用户）

• 查看开发服务器：在 devbox 上监听 127.0.0.1:<port>，然后在电脑上运行 ssh -N -L <port>:localhost:<port> devbox，并打开 http://localhost:<port>。
• 在 tmux 中运行长时间任务：claude-task start <name> ~/dev/<project> "<prompt>" [--rc] [--mode auto]，然后使用 claude-task list | show | send | stop；tmux attach -t ct-<name>（按 Ctrl+b 然后 d 退出）。
• 将某个会话有意转入后台：claude --resume <id> --fork-session --bg --remote-control "<name>" --permission-mode auto "<prompt>"。
• 检查中继活动：ssh devbox devbox-relay status，日志位于 ~/dev/_relay/log.md。
• 更新工具：PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh。
• 已关机的服务器通常仍会计费。