PandaPaw：適用於 Claude Code、Codex 和 PandaCode 的遠端主機

更新於

PandaPaw 可將您所控制的 Windows、macOS 或 Linux 機器轉變為 PandaNpc 代理主機。編碼引擎、專案檔案、Shell 與工具都保留在該主機上；PandaNpc 用戶端讓您可以從手機、瀏覽器或其他桌面裝置取得同步化的介面。

當執行工作的機器與您手中的裝置不同、當您希望主機在用戶端中斷連線後仍持續運作，或當多個編碼引擎應共用相同的帳號式設定與 Agent Center 組態時，請使用 PandaPaw。

PandaPaw 管理內容

  • 遠端代理連線：適用於 Claude Code、OpenAI Codex 和 PandaCode。
  • 背景服務與自動啟動：讓主機在正常重新開機後可以恢復運作。
  • 以帳號為基礎的機器授權：無需手動複製長效 Bridge ID、權杖或簽署金鑰。
  • 引擎安裝協助：當支援的編碼引擎遺失時。
  • Agent Center 投影：以每個引擎的原生版面呈現其指引、技能、記憶體與代理定義。
  • 私人裝置網路：適用於透過 Connected Devices 流程加入的機器。
  • 更新與解除安裝的紀錄管理：讓 PandaPaw 之前既有的工具得以保留。

PandaPaw 本身並不提供模型訂閱。Claude Code、Codex 和 PandaCode 仍使用其引擎所設定的提供者憑證與限制。

遠端執行方式

flowchart LR Client["PandaNpc client\nweb · iOS · desktop · Chrome"] -->|outbound authenticated session| Relay["PandaNpc relay"] Host["PandaPaw host"] -->|outbound authenticated session| Relay Host --> Claude["Claude Code"] Host --> Codex["Codex"] Host --> PandaCode["PandaCode"] Claude --> Project["Local project and tools"] Codex --> Project PandaCode --> Project

兩端皆會發起對外連線，因此一般的家庭或辦公室設定不需要輸入方向的防火牆規則、公用 IP 位址、路由器連接埠轉發，或公開暴露的 SSH 伺服器。中繼站傳輸訊息、狀態與核准；工具執行則在主機上進行。

如果主機休眠、關機或失去對外網路路徑，已儲存的連線仍會保留在您的帳號中，但在主機恢復之前無法執行工作。

支援的主機平台

主機平台 套件 備註
Windows x64 原生執行檔與使用者層級服務 在 PowerShell 中執行安裝程式
macOS（Apple Silicon 或 Intel） 通用 PandaPaw 應用程式/二進位檔 同一個套件支援兩種架構
Linux x86_64 原生二進位檔與使用者服務 適用於常見的 glibc 基礎發行版

PandaNpc 檢視用戶端具有更廣泛的平台矩陣。在選擇用戶端與主機套件時，請參閱 安裝 PandaNpc 與 PandaPaw。

建議安裝方式

  1. 登入 PandaNpc。
  2. 開啟 Connected Devices。
  3. 選擇 新增裝置。系統會發出一組一次性金鑰，對話框會顯示針對偵測到之作業系統的一條指令。
  4. 將該指令複製到主機並在主機上執行。
  5. 如果您希望對話框自動偵測新機器，請保持對話框開啟。

預先準備的金鑰是單次使用。請複製完整指令、保持機密，如果金鑰過期或已被兌換，請產生新的金鑰。

純 macOS/Linux 安裝程式

當您想要使用瀏覽器授權而非預先準備的金鑰時，請使用此表單：

bash
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

純 Windows PowerShell 安裝程式

powershell
iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

純安裝程式會執行 pandapaw login。請在它開啟的瀏覽器頁面中核准該機器。如果授權中斷，二進位檔與服務仍可安裝；稍後執行 pandapaw login 以完成帳號連線。

驗證主機

首先檢查主機本身：

bash
pandapaw status

然後開啟 PandaNpc Agent 並確認機器有綠色的線上指示。在可拋棄或唯讀的測試目錄中啟動一個工作階段，然後詢問：

測試提示： 列印目前的工作目錄並列出頂層檔案。請勿修改任何內容。

成功的回覆證明的遠不止綠色狀態燈：它驗證了帳號配對、中繼連線、所選引擎、提供者驗證以及工作目錄的對應。

若是 Agent Center 專案，請執行：

bash
pandapaw agent status --root /absolute/path/to/project

這會顯示專案是否已綁定，以及受管理的組態是否可在本機使用。穩定的 Git 遠端可協助 PandaPaw 在不同機器之間識別相同的專案。

帳號授權與連線識別

pandapaw login 使用瀏覽器的裝置授權工作階段。在您核准之後，主機會透過 TLS 接收裝置範圍的憑證與 Agent Center 驗證金鑰，將其機器組態寫入 ~/.pandapaw/，註冊支援的引擎連線，並綁定可識別的 Git 專案。

只有在刻意切換帳號或更換已過期的主機憑證時，才執行 pandapaw login --force。在沒有理由的情況下重新授權健康的機器，可能會造成令人困惑的重複或取代身分。

pandapaw qr 仍會建立短期有效的手動連線連結，以用於相容性與特殊情況。它不是新主機的主要流程；Connected Devices 較容易稽核，而且不需要使用者理解 Bridge ID。

Agent Center 同步

Agent Center 在穩定狀態下是事件驅動的：

  1. 偵測本機受管理檔案的變更，並發佈到綁定的專案。
  2. 簽署的版本透過事件串流送達。
  3. 未變更的清單與內容區塊會重複使用，而不是再次下載。
  4. 定期復原檢查會捕捉暫時中斷期間遺漏的事件。

Claude Code、Codex 和 PandaCode 會接收不同的投影，因為它們預期不同的目錄與指令格式。PandaCode 在組裝新的工作階段提示之前，會準備最新的已驗證版本，因此啟動時擷取的組態會影響同一個工作階段。

如果 Agent Center 暫時無法使用，引擎會繼續使用最後驗證的本機版本。網路故障不應在未經告知的情況下，以未驗證的內容取代已簽署的組態。

實用指令

bash
pandapaw login
pandapaw status
pandapaw agent status --root /absolute/path/to/project
pandapaw update --restart
pandapaw uninstall
指令 用途
pandapaw login 授權已安裝但尚未連線到帳號的機器
pandapaw status 檢查已安裝的服務、機器連線與基本健康狀態
pandapaw agent status --root … 檢查單一專案的 Agent Center 狀態
pandapaw update --restart 驗證、安裝並啟用最新的 PandaPaw 版本
pandapaw uninstall 保守地移除 PandaPaw 管理的服務與檔案

當指令或 UI 與舊的螢幕截圖或教學不同時，請查看 PandaPaw 版本歷史。

安全界限

  • 遠端操作者可以行使所選代理工作階段允許的任何工具與工作目錄。遠端存取並非自動唯讀。
  • 請將一次性裝置指令、手動連線連結、提供者金鑰與帳號權杖遠離日誌與螢幕截圖。
  • 請勿為了讓 PandaPaw 可被連線而開啟輸入方向的路由器連接埠。
  • 將您不再擁有的主機從 Connected Devices 中移除。
  • 在允許編輯或 shell 指令之前，請檢視工具核准並驗證工作目錄。
  • 分享即時連線時，接收者會耗用主機擁有者的引擎配額，並可在主機上操作。請先閱讀 連線分享。

疑難排解

安裝後找不到 `pandapaw`

開啟新的終端機，以便重新載入使用者的 PATH。正常位置在 macOS/Linux 是 ~/.local/bin，在 Windows 是 %LOCALAPPDATA%\Programs\pandapaw。在重新執行安裝程式之前，請確認檔案存在。

安裝成功，但沒有出現機器

執行 pandapaw status。如果機器沒有帳號授權，請執行 pandapaw login。如果使用了預先準備的一次性金鑰，請建立新金鑰，而不是重試已使用的指令。

機器出現但保持離線

確認主機已喚醒且可存取網際網路。在本機檢查 PandaPaw 狀態。公司的 Proxy 或防火牆必須允許對外的 HTTPS/WebSocket 路徑；輸入方向的連接埠無法解決對外連線遭封鎖的問題。

主機在線上，但 Claude Code 或 Codex 沒有回應

配對主機不會驗證每個模型提供者。請在本機開啟引擎，或遵循遠端工作階段中顯示的登入提示。同時確認所選模型存在於該帳號，且其使用限制尚未耗盡。

工作階段在錯誤的專案中開啟

結束測試，選擇預期的絕對工作目錄，並在核准工具之前要求代理列印該目錄。PandaPaw 不會猜測您指的是哪個儲存庫，也不會在引擎自身的權限模型之外加入檔案系統沙箱。

Agent Center 變更未顯示

從正確的 Git 根目錄執行 pandapaw agent status --root /path/to/project。確認專案已綁定、主機已登入，且本機檔案屬於受管理的投影。在調查時請保留最後驗證的版本，不要刪除受管理的目錄。

更新與解除安裝

pandapaw update --restart 會下載目前的二進位檔、驗證其 SHA-256 總和檢查碼、取代已安裝的副本，並重新啟動受管理的服務，使該版本生效。現有的帳號配對會被保留。

pandapaw uninstall 使用安裝清單來移除 PandaPaw 建立的項目。原本已存在且相容的 Claude Code、Codex、PandaCode 或 Node 安裝會被刻意保留。解除安裝後，如果該主機不再受信任，請將其從 Connected Devices 中移除。