PandaPaw: 面向 Claude Code、Codex 和 PandaCode 的远程主机

更新于

PandaPaw 将您控制的 Windows、macOS 或 Linux 机器转变为 PandaNpc 代理主机。编码引擎、项目文件、shell 和工具仍保留在该主机上；PandaNpc 客户端让您可以从手机、浏览器或另一台桌面设备获得同步界面。

当执行工作的机器与您手持的设备不同、希望主机在客户端断开连接后继续运行，或希望多个编码引擎共享相同的基于账户的设置和代理中心配置时，请使用 PandaPaw。

PandaPaw 管理的内容

  • 远程代理连接：面向 Claude Code、OpenAI Codex 和 PandaCode。
  • 后台服务和自动启动，以便主机在正常重启后恢复。
  • 基于账户的机器授权，无需手动复制长期有效的桥接 ID、令牌或签名密钥。
  • 引擎安装协助，当缺少受支持的编码引擎时。
  • 代理中心投影，以各引擎的原生布局呈现其指导、技能、记忆和代理定义。
  • 专用设备网络，适用于通过“已连接设备”流程加入的机器。
  • 更新和卸载记录，以确保 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. 打开已连接设备。
  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，确认该机器有绿色在线指示器。在一次性或只读测试目录中启动会话，并询问：

测试提示： 打印当前工作目录并列出顶层文件。不要修改任何内容。

成功的回复所证明的不仅仅是绿色状态灯：它还验证了账户配对、中继连接、所选引擎、提供商身份验证以及工作目录映射。

对于代理中心项目，请运行：

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

这显示项目是否已绑定，以及托管配置在本地是否可用。稳定的 Git 远程仓库有助于 PandaPaw 跨机器识别同一项目。

账户授权与连接身份

pandapaw login 使用浏览器设备授权会话。批准后，主机通过 TLS 接收设备级凭据和代理中心验证密钥，将其机器配置写入 ~/.pandapaw/ 目录，注册受支持的引擎连接，并绑定可识别的 Git 项目。

仅在有意图切换账户或替换已过期的主机凭据时，才运行 pandapaw login --force。无缘无故地重新授权一台健康的机器可能会造成令人困惑的重复或替换身份。

pandapaw qr 仍然会创建短期的手动连接链接，以用于兼容性和特殊场景。它不是新主机的主要流程；已连接设备更易于审计，且不需要用户理解桥接 ID。

代理中心同步

代理中心在稳定状态下是事件驱动的：

  1. 本地托管文件的更改会被检测并发布到绑定的项目。
  2. 已签名版本通过事件流到达。
  3. 未更改的清单和内容块会被重复使用，而不是重新下载。
  4. 定期恢复检查会捕获临时断开期间错过的事件。

Claude Code、Codex 和 PandaCode 会收到单独的投影，因为它们期望不同的目录和指令格式。PandaCode 在组装新的会话提示之前准备最新的已验证版本，因此启动时拉取的配置可能会影响该会话。

如果代理中心暂时不可用，引擎将继续使用最后验证的本地版本。网络故障不应静默地用未验证的内容替换已签名的配置。

常用命令

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 … 检查单个项目的代理中心状态
pandapaw update --restart 验证、安装并激活最新的 PandaPaw 版本
pandapaw uninstall 谨慎地移除 PandaPaw 管理的服务和文件

当命令或界面与旧截图或教程不一致时，请查阅 PandaPaw 版本历史。

安全边界

  • 远程操作者可以使用所选代理会话允许的任何工具和工作目录。远程访问并非自动只读。
  • 不要让一次性设备命令、手动连接链接、提供商密钥和账户令牌出现在日志和截图中。
  • 不要仅仅为了让 PandaPaw 可访问而打开入站路由器端口。
  • 从已连接设备中移除您不再拥有的主机。
  • 在允许编辑或 shell 命令之前，审查工具批准并验证工作目录。
  • 共享实时连接时，接收方会消耗主机所有者的引擎配额，并且可以在主机上操作。请先阅读连接共享。

故障排除

安装后找不到 `pandapaw`

打开一个新的终端，以便重新加载用户的 PATH。通常位置是 macOS/Linux 上的 ~/.local/bin 和 Windows 上的 %LOCALAPPDATA%\Programs\pandapaw。在重新运行安装程序之前，确认文件是否存在。

安装成功，但没有出现机器

运行 pandapaw status。如果机器没有账户授权，请运行 pandapaw login。如果使用了准备好的一次性密钥，请创建新密钥，而不是重试已使用的命令。

机器出现但保持离线

确认主机处于唤醒状态且可访问互联网。在本地检查 PandaPaw 状态。公司代理或防火墙必须允许出站 HTTPS/WebSocket 路径；入站端口无法解决出站连接被阻止的问题。

主机在线，但 Claude Code 或 Codex 不响应

配对主机并不会对每个模型提供商进行身份验证。在本地打开引擎，或按照远程会话中显示的登录提示操作。同时确认所选模型在该账户中可用，且其使用限额尚未耗尽。

会话在错误项目中打开

结束测试，选择预期的绝对工作目录，并在批准工具之前让代理打印该目录。PandaPaw 不会猜测您指的是哪个仓库，也不会在引擎自身的权限模型之外添加文件系统沙箱。

代理中心更改未出现

在正确的 Git 根目录下运行 pandapaw agent status --root /path/to/project。确认项目已绑定、主机已登录，并且本地文件属于托管投影的一部分。在调查期间保留最后验证的版本，而不是删除受管目录。

更新和卸载

pandapaw update --restart 下载当前二进制文件，验证其 SHA-256 校验和，替换已安装的副本，并重启托管服务以使新版本生效。现有账户配对将被保留。

pandapaw uninstall 使用安装清单来移除 PandaPaw 创建的项目。已存在的兼容 Claude Code、Codex、PandaCode 或 Node 安装将被有意保留。卸载后，如果该主机不再受信任，请将其从已连接设备中移除。