camilbenameur/remote-devbox

remote-devbox 是做什麼的？

你正在設定 (或修復) 一個 devbox：這是一台 Linux 伺服器，用來執行 Claude Code 工作階段， 而使用者電腦上的 Claude 桌面應用程式僅作為操作介面。請依序完成各個階段。 每個階段都會說明你需要做什麼、只有使用者能做的部分，以及如何確認運作成功。

<skill> 代表包含此檔案的文件夾。

使用者將獲得的功能

• 桌面應用程式的 Code 索引標籤維持不變，但每個工作階段都在開發盒上透過 SSH 執行： shell、測試、安裝、Python、Node、Chrome。使用者電腦僅負責繪製介面。
• 使用使用者的訂閱，而非 API 點數。桌面應用程式會傳遞並重新整理工作階段的 登入狀態。切勿在開發盒上設定 ANTHROPIC_API_KEY：否則帳單將轉移至 API。
• 兩個以 MCP 伺服器形式提供的瀏覽器：chrome，一個登入使用者帳戶的共享 Chrome，以及 playwright，每個工作階段一個獨立的無痕 Chrome。一個虛擬螢幕可在使用者私有網路上透過任意 網頁瀏覽器顯示共享的 Chrome (noVNC)。
• 即使電腦關機，工作階段仍可繼續執行：devbox-relay 可在背景恢復中斷的桌面工作階段， 而 devbox-rc 可承接從 claude.ai/code 或手機應用程式啟動的工作階段。
• 與電腦上相同的全域 CLAUDE.md、技能、記憶和外掛鉤子。

當你需要了解機制時，請閱讀 references/how-it-works.md； 一旦出現故障，請立即閱讀 references/troubleshooting.md。

你的基本原則

• 使用者負責：付款和訂購、所有密碼和登入 (供應商、Tailscale、GitHub 裝置碼、Claude /login、共享 Chrome 中的網站)、 在桌面應用程式設定中的點擊，以及 Tailscale 管理主控台。給他們確切的連結或指令，一次一個， 然後等待。切勿自行輸入密碼、信用卡號或一次性驗證碼。
• 在訂購任何東西之前，說明計畫、價格和承諾，並獲得同意。
• 設定腳本具有冪等性：當一個腳本失敗時，閱讀錯誤訊息，修正原因，然後重新執行。
• 在開發盒上，sudo 不需要密碼。但仍需在使用者同意後，才能進行腳本本身不會進行的系統變更 (套件、服務、防火牆、sshd、使用者)。
• 在使用者的線上開發盒上工作時，切勿未經告知就停止 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)。桌面應用程式需要它。如果版本較舊： winget install Microsoft.OpenSSH.Preview。
3. Claude 桌面應用程式已安裝並登入，且使用者的方案包含 Claude Code。
4. git config --global user.name 和 user.email 已設定 (腳本會將它們複製到開發盒)。
5. 詢問使用者是否需要選用部分：gatehaul (在 GitHub Codespaces 中執行大型建置， -Gatehaul / --gatehaul)、共享的已登入 Chrome (預設啟用)、記憶複製。

階段 1：選擇並訂購伺服器

使用 references/providers.md。需求：KVM 虛擬機器、Ubuntu 24.04、x86_64 優先 (arm64 可用但未經端到端測試)、至少 8 GB RAM (若要執行數個並行工作階段加 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

在使用者可以輸入的終端機中執行它 (桌面應用程式的終端機面板，或請他們執行)。 它需要使用者提供三項資訊：

1. 主機金鑰指紋。 腳本會顯示它並詢問是/否。告訴使用者將它與 供應商網頁主控台輸出 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub 進行比較。
2. 初始密碼，一次，以便授權金鑰 (如果在訂購時已提供金鑰則跳過)。
3. GitHub 裝置碼: gh auth login 會產生一個碼和一個連結。

它會執行以下操作：建立金鑰 ~/.ssh/devbox_ed25519 (無密碼，桌面應用程式必須無提示連線)、 執行 host/10-root-bootstrap.sh (建立 dev 使用者並賦予 sudo 權限、僅金鑰 SSH、linger、swap、 Node、gh、Chrome、Tailscale、ufw、fail2ban、unattended upgrades、虛擬螢幕套件)、將 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. 在開發盒上：ssh -t devbox sudo tailscale up --hostname=devbox。它會顯示一個登入連結： 使用者開啟它。
3. 使用者：Tailscale 管理主控台，Machines，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 上開啟的桌面應用程式工作階段)， 它會拒絕執行。請先關閉那些工作階段。

鎖定救援：供應商網頁主控台，然後 sudo ufw allow OpenSSH。

階段 4：連接桌面應用程式

使用者，在桌面應用程式中：Code 索引標籤，提示方塊下的環境選單，New environment， SSH (標籤在 2026 年底可能會有所變動)：

欄位	值
SSH host	devbox (來自 ~/.ssh/config)
SSH key	空白
Worktree folder	~/worktrees
Folder for a session	~/dev/<project>

首次連線時，應用程式會在開發盒上的 ~/.claude/remote/ 下安裝自己的引擎，並 顯示主機金鑰：與階段 2 中相同的指紋。該環境中的工作階段在開發盒上執行。 SSH 工作階段中沒有 Browser 窗格：請改用埠轉發 (請參閱日常使用)。

階段 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，僅限本機)。

檢查：在開發盒工作階段中，要求 chrome MCP 開啟一個使用者已登入的網站，並確認 可以看到該帳戶，但不要讀取私人內容。工作列圖示和螢幕的右鍵選單會開啟此 Chrome； 它也是開發盒的預設瀏覽器。

階段 6：鏡像本機 Claude 環境

目標：在開發盒上的工作階段表現得如同在電腦上一樣。

1. 全域 CLAUDE.md 和技能：

   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 (說明開發盒上的差異：路徑、瀏覽器、 螢幕、連續性、sudo 規則) 附加到本機 ~/.claude/CLAUDE.md 的開頭，合併 ~/.claude/skills (不含 .venv、node_modules、.git)，並使用 -Memory 將本機專案資料夾 (-LocalDevDir，預設為 ~/Documents/dev) 的自動記憶複製到開發盒上 ~/dev 的記憶中。 每當本機的 CLAUDE.md 或技能變更時，重新執行此腳本。請編輯標題範本，而不是開發盒上 會被覆寫的副本。
2. 需要設定的技能：對於每個同步的技能，在 SKILL.md 中尋找 Python 環境 (requirements.txt、pyproject.toml)、Node 套件、二進位檔和 Windows 路徑。 在開發盒上重建環境並修正路徑。在詢問後安裝它們所需的系統工具 (例如 ffmpeg)。
3. 外掛：桌面應用程式會在 SSH 工作階段中安裝使用者的外掛，但它們的鉤子不會在 那裡執行。對於每個啟用且帶有 hooks/hooks.json 的外掛，將其原始碼以相同提交版本 複製到開發盒上的 ~/.claude/hooks-thirdparty/<plugin>，並將其鉤子合併到開發盒的 ~/.claude/settings.json 中，將 ${CLAUDE_PLUGIN_ROOT} 替換為該資料夾，並將直譯器 修正為 Linux 版本 (python 改為 python3)。使用 jq 進行合併；保留現有的 devbox-relay guard SessionStart 鉤子。在啟用鉤子腳本之前，請先閱讀它們。
4. MCP 伺服器：在本機和開發盒上比較 claude mcp list。重新加入在 Linux 上有意義的 使用者範圍 stdio 伺服器。claude.ai 連接器跟隨帳戶：無需任何操作。
5. 專案：使用 gh repo clone 複製到 ~/dev/<name>。複製重要的未提交或已忽略的 本機檔案 (僅在使用者同意下複製 .env 檔案)，安裝依賴項，執行輕量測試。 大型建置應透過 gatehaul (如果已安裝) 放在 Codespaces 中。
6. 無需使用者的長時間遷移：如果有大量內容需要移動，請撰寫工作清單，然後透過 claude-task 使用 references/setup-agent-prompt.md 在開發盒上 啟動一個自主工作階段。

階段 7：電腦關機時仍繼續執行的工作階段

1. 在開發盒上進行 CLI 登入 (中繼和遠端控制會使用它)： ssh -t devbox claude，然後 /login；使用者開啟連結並貼上驗證碼；/exit。
2. 中繼：已由 20-user-setup.sh 啟用。檢查 ssh devbox devbox-relay test (所有 案例皆為 OK) 和 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>) 現在會在開發盒上啟動工作階段。在那裡為應該獨自進展的工作階段 選擇 Auto 權限模式。claude.ai 可能會要求使用者再次登入以驗證裝置。
4. 可選的真實測試，與使用者一起：在桌面工作階段中啟動一個小任務，該任務會停在一個 權限問題上，使用者退出桌面應用程式，等待約 30 分鐘，重新開啟它；日誌 ~/dev/_relay/log.md 顯示中繼，開發盒上的 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)。 然後告訴使用者哪些已準備就緒、他們還需要做什麼，以及如何存取每個部分。

日常使用 (告知使用者)

• 查看開發伺服器：在開發盒上的 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。
• 已關閉電源的伺服器通常仍會計費。