安裝 PandaNpc 與 PandaPaw

更新於

遠端編碼代理（coding agent）的設定有兩個獨立的部分：

  • PandaNpc 客戶端 — 用於讀取工作階段、傳送提示並核准工具的管理介面。支援 Web、iOS、Windows、macOS 與 Linux 平台。
  • PandaPaw 主機 — 在 Claude Code、Codex 或 PandaCode 實際執行的電腦上運作的背景服務。

若只要使用 PandaNpc 聊天與本機桌面功能，僅需安裝客戶端。若想連線到在另一台機器上執行的編碼代理，則需安裝兩者。

有關 Windows/macOS/Linux 應用程式在下列安裝步驟之外還提供哪些功能（包括版本歷史），請參閱 PandaNpc Desktop。

選擇要安裝的項目

情境 客戶端 PandaPaw 主機
在瀏覽器中使用 PandaNpc 聊天 開啟 Web 應用程式 不需要
在本機桌面控制代理 桌面應用程式 依所選的本機/遠端模式而定
從手機或瀏覽器控制開發機器 在檢視裝置上安裝/開啟客戶端 在開發機器上為必備
在沒有圖形桌面的伺服器上執行代理 在其他地方使用 Web、桌面或 iOS 在伺服器上為必備

若想採用最短的端對端路徑，請使用 快速入門指南。

安裝 PandaNpc 客戶端

請以 PandaNpc 下載頁面 作為目前安裝程式的唯一權威來源。請避免使用第三方下載站，因為它們可能提供過時或遭修改的套件。

Web

在目前版本的瀏覽器中開啟 pandanpc.com/agent。無需安裝任何東西。瀏覽器儲存空間會保留本機登入狀態，因此無痕/私密視窗可能會要求您重新登入。

iOS

依照下載頁面上的 App Store 連結並安裝 PandaNpc。iOS 適合在不在主機旁時查看進度、回答問題及核准工具。編碼程序仍會在已連線的主機機器上執行。有關此應用程式的涵蓋範圍（包括版本歷史），請參閱 PandaNpc for iOS。

Windows

  1. 下載目前的 Windows 安裝程式。
  2. 執行並依照安裝程式的提示操作。
  3. 從開始功能表啟動 PandaNpc。
  4. 如果 Windows 顯示發行者或信譽警告，請先確認檔案來自 pandanpc.com 再繼續。

macOS

  1. 下載 macOS .dmg。
  2. 將 PandaNpc 拖入 應用程式 資料夾。
  3. 從「應用程式」中啟動，並完成任何 macOS 安全性提示。

macOS 版本為通用版本，因此同一個套件支援 Apple Silicon 與 Intel Mac。

Linux

下載 x86_64 AppImage、將其設為可執行，然後執行：

bash
chmod +x PandaNpc_*.AppImage
./PandaNpc_*.AppImage

如果 AppImage 無法啟動，請在終端機中執行一次，並保留確切的錯誤輸出。較舊的發行版可能缺少桌面外殼所需的執行期函式庫。

在代理主機上安裝 PandaPaw

PandaPaw 目前提供 Windows x64、macOS 通用版與 Linux x86_64 的主機安裝程式。請在擁有專案檔案且應執行代理工具的電腦上執行此命令。

建議的方式是使用 已連線裝置：選擇 新增裝置，然後複製產生的一次性命令。此命令會在安裝期間將主機與您的帳戶配對。

macOS 或 Linux

使用瀏覽器授權的簡易安裝程式：

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

已準備好一次性金鑰的形式：

bash
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh -s -- --mesh pnkey-xxxx

Windows PowerShell

簡易安裝程式：

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

已準備好一次性金鑰的形式：

powershell
$env:PANDANET_KEY="pnkey-xxxx"; iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

PowerShell 的 iwr | iex 管線無法傳遞一般指令碼引數，因此 Windows 安裝程式會從 PANDANET_KEY 讀取一次性金鑰。

主機安裝程式會變更什麼

安裝程式會：

  1. 將 PandaPaw 新增至目前使用者的應用程式/bin 目錄，並在需要時更新使用者的 PATH。
  2. 註冊適當的背景服務以自動啟動。
  3. 當平台允許時，安裝缺少的受支援編碼引擎。
  4. 當系統沒有合適的版本時，提供私有的 Node.js 執行環境。
  5. 啟動帳戶授權，或兌換已準備好的裝置金鑰。
  6. 記錄它建立的檔案，以便解除安裝時能保留原本就存在的相容工具。

安裝引擎並不會自動購買或驗證模型訂閱。Claude Code 和 Codex 在首次執行時仍可能要求各自提供者的登入。

驗證安裝

安裝後開啟新的終端機並執行：

bash
pandapaw status

然後開啟 PandaNpc Agent。主機應顯示為上線。在測試專案中開始一個工作階段，並要求它回報目前的工作目錄，且不要變更任何檔案。這會驗證二進位檔、背景服務、帳戶配對、中繼連線、引擎和選取的目錄，而不只是下載步驟。

更新

桌面客戶端會在更新可用時通知您。iOS 則透過 App Store 更新。

使用下列命令更新 PandaPaw 並重新啟動其受管理的服務：

bash
pandapaw update --restart

更新程式會在取代已安裝的副本之前，針對已發布的 SHA-256 總和檢查碼驗證下載的二進位檔。您的帳戶配對與現有的連線身分都會保留。當更新程式本身無法使用時，也支援重新執行安裝命令。

解除安裝

  • Windows 客戶端： 設定 → 應用程式 → 已安裝的應用程式 → PandaNpc → 解除安裝。
  • macOS 客戶端： 結束 PandaNpc，然後將其從「應用程式」移到「垃圾桶」。
  • Linux 客戶端： 移除 AppImage 以及您為它建立的任何啟動器。
  • PandaPaw 主機： 在主機上執行 pandapaw uninstall。

PandaPaw 的解除安裝資訊清單會區分安裝程式所建立的工具與原本就存在的相容工具。它刻意採取保守作法，不會刪除已預先存在的 Claude Code、Codex、PandaCode 或 Node 安裝。

安裝問題

命令已完成，但主機未連線

執行 pandapaw login。主機安裝與帳戶授權是兩個不同階段，即使瀏覽器授權被延後或中斷，安裝程式仍可能完成。

Shell 找不到 `pandapaw`

開啟新的終端機。在 macOS/Linux 上，檢查 ~/.local/bin；在 Windows 上，檢查 %LOCALAPPDATA%\Programs\pandapaw。在確認可執行檔是否存在，且只是 PATH 過期之前，請勿重複重新安裝。

編碼引擎安裝失敗

主機安裝程式會將選用的引擎下載視為「盡力而為」，因此單一提供者中斷不會移除可正常運作的 PandaPaw 安裝。請使用該引擎的官方安裝程式來安裝或修復，正常驗證，然後再次執行 pandapaw status。

AppImage 或桌面應用程式無法開啟

請確認您下載的套件適用於正確的架構，然後從終端機啟動它以取得第一個錯誤。連絡支援時請附上該錯誤與您的作業系統版本；通常，已關閉視窗的螢幕擷取畫面不足以診斷缺少執行期函式庫的問題。

如需主機特定的連線檢查，請繼續參閱 PandaPaw 指南 或 常見問題。