DOCUMENTATION

文档中心

从单机跑通第一次交付,再把工作派给你管理的构建机。这里也有 v0.1.6 的安装、命令和权限说明。

CURRENT v0.1.6 · 2026-11-12 · AGPL-3.0-OR-LATER

快速开始

装好后先配置模型和执行器。二进制、适配器与配置都在你自己的用户目录里,不需要 root。

01panda init

初始化节点、模型提供方与能力卡。

02panda

进入交互式 TUI 控制台。

03跑第一个任务并收回结果

在现有项目里运行测试并查看交付。

panda init 会要求选择模型提供方;本机模型与 API 都可以,不需要 GPU,守护进程空闲时常驻内存约 40MB。

跑第一个任务并收回结果

先验证模型连接,再验证执行器。一次只选择一种运行入口,避免后台进程争用端口。

  1. 运行 panda doctor,在模型设置中测试连接;确认端点、凭据和模型名属于同一服务。官方与兼容端点均可,入口模型配置不等于 agent CLI 的登录配置。
  2. 运行 panda agents,再对已安装的执行器运行 panda agents test codex(示例)。CLI 的原生端点、凭据与模型仍可使用,不要求额外的官方订阅。
  3. 打开 panda web 或进入 panda TUI,选一个你熟悉的项目目录。先在本机试一句「运行这个项目的测试,给我失败项和原始输出,不修改源码」。已知测试命令时可直接写上。
  4. 对话展示模型阶段、已返回的思考摘要和执行活动。不是所有供应商都会返回思考摘要;不要把没有摘要当作没有运行。刷新不应丢失记录与停止控制。
  5. 任务结束后检查交付报告、真实步骤、变更路径、验证结果与待确认事项。done 只表示执行结束,不等于独立验收已通过;没有验证记录会明确标注。
  6. 失败时先看具体任务的原因,再修复网络、登录、余额或执行器配置后重试。不要反复重放同一个已知失败;停止后保留部分回答,必要时从原对话继续。

用同一个任务试第二台机器

在两台设备上安装并配置 Panda。让具备项目测试环境和 Agent CLI 的构建机保持在线,先配对,再在任务中指定这台机器。确认项目上下文能传给对端,或对端已有所需工作目录。运行后在原对话检查实际执行节点、结果和验证状态。没有合适的节点时,先查明能力、权限或连接缺在哪一步。

看组网与配对步骤 →

源码更新后需重新构建并重启实际运行的 Panda 服务,再刷新浏览器。旧进程不会自动获得新逻辑;升级前保留配置与数据备份。

安装与升级

三条路径装出来的是同一样东西:一个 panda 可执行文件、智能体适配器与示例配置,全部落在用户目录。

macOS / Linux一键安装,默认最新稳定版
$curl -fsSL https://raw.githubusercontent.com/Xustalis/OpenPanda/main/scripts/install.sh | sh
Homebrewtap 与 release 同一条通道
$brew tap Xustalis/openpanda && brew install openpanda
Windows (PowerShell)PS 5.1,无 BOM,无额外前置
PS>irm https://raw.githubusercontent.com/Xustalis/OpenPanda/main/scripts/install.ps1 | iex

安装器按平台与架构取产物,校验 SHA-256、在本机 openssl 支持时验 Ed25519 签名、解压并把二进制写进 PATH。重跑同一条命令即原地升级,用户数据保留。

全部产物、校验值与安装参数 →

命令速查

最常用的几条。完整命令表由 panda help 从同一份注册表输出。

COMMAND作用
panda version --json二进制版本与数据库 schema,JSON 输出。
panda doctor诊断配置、模型端点与网络可达性。
panda nodes / panda pair查看组网节点 / 配对新设备。
panda task add --accept带可执行验收合同派一个任务。
panda model discover从本机已有配置发现可用模型行。
panda service install把控制台注册为用户级服务(launchd / systemd --user / 登录任务)。
panda update check / apply检查新版本 / 应用更新(强制验签后才换二进制)。
panda read path:line在终端里查看文件某行前后的上下文。
panda uninstall移除二进制、PATH 标记块与自启单元。

架构与信任

内核负责的四条不变量,与具体用哪个 Agent、哪个模型无关。

身份

每个节点持两把 Ed25519 密钥:稳定的签名密钥与轮换密钥。对端以签名授权,不靠 IP 互信。

传输

逐连接 AEAD 加密。链路断开时由 DTN 存储转发托管,恢复后再送。

边界

mesh / guarded / open 三档信任区,按来源逐跳钳制权限、屏幕与模型凭据。

验收

任务携带交付合同;完成判定看实际执行过的命令,以及声明的验证入口是否真的跑过。

帧格式与线协议细节见 docs/protocol.md。

深入阅读

核心概念

读文档和 status.md 时反复出现的九个词,先在这里对齐含义。

TERM 含义
节点 / node 一台跑着 panda 的机器,持两把 Ed25519 密钥与一张能力卡;每个节点都能是派发根,没有主节点。
能力卡 / capability card 节点自动声明的硬件、已装 Agent 与执行器清单;调度器按它做硬过滤,panda card 可编辑并热重载。
适配器 / adapter adapters/*.py 里的桥接脚本,把某个 agent CLI 的 argv、环境与输出统一成内核能驱动的协议。
信任区 / trust tier mesh / guarded / open 三档,按对端身份钳制委派暴露面与入站准入;是本机单方面断言。
tier-1 / tier-2 命令的两级判定:可逆操作自主执行,不可逆操作默认拒绝或转人工审批。
交付合同 / accept panda task add --accept 附带的成功定义,编排者在 agent 结束后自己跑检查并比对基线。
DTN bundle 链路断开时暂存、恢复后再投递的加密签名消息单元;篡改过的 bundle 不会被送达。
lane / 作用域 同项目并行任务按 path scope 分道,不相交的兄弟任务各跑一份隔离 worktree。
plan 多阶段、可跨设备的流水线,阶段之间靠产物接线;panda plan show <id> 查看每段状态。

配置与文件

所有状态都在用户目录里,卸载默认不动用户资产。路径按平台不同,命令不依赖安装位置。

FILE 内容
config.yaml 节点名、模型提供方、监听地址、网络与信任档;共享密钥不要写在这里。
capabilities.yaml 本机可用的原生命令、Agent 与硬件执行器,以及各自的 tier 声明。
USER.md / MEMORY.md 双层记忆:用户偏好与项目事实分开存,随委派任务一起打包给执行端。
SKILL.md 从跑通的工作流蒸馏出来的可复用剧本,panda skill 可浏览、导入与安装。
openpanda.db 纯 Go SQLite(WAL 模式)存任务、会话、审计链与节点目录;schema 版本由 version --json 可读。
.openpanda/ 工作区模式下的运行时暂存目录;git 仓库会自动写进 .git/info/exclude,不碰用户的 .gitignore。

完整路径按平台:macOS ~/Library/Application Support/openpanda,Linux ~/.local/share/openpanda,Windows %LOCALAPPDATA%\openpanda-data。

适配器清单

内置十个适配器加一个通用桥,对应仓库 adapters/ 下的实际文件。缺失的 agent 不会被选中。

ADAPTER 驱动
claude_code.py Claude Code
codex.py OpenAI Codex CLI
opencode.py OpenCode
grok_build.py Grok Build
deepseek_harness.py DeepSeek Harness
antigravity.py Antigravity
hermes.py Hermes
pi.py Pi
zcode.py ZCode
openclaw.py OpenClaw
generic.py 任意走 stdin/stdout 的无头 CLI;_harness.py 是共用协议骨架

panda agents 列出本机已装与缺失的 agent,并给出缺失项的安装命令。

组网与配对

每台设备先 panda init,然后任选一条路径把第二台机器加进来。

01panda pair <addr>panda pair confirm

一台发起并显示短配对码,另一台核对同一个码确认;共享密钥经加密通道下发,不用手抄。

02panda nodespanda nodes admit <id>

同一局域网内自动发现待准入设备,按指纹确认入伙;panda nodes verify 可把 Ed25519 指纹钉死。

03panda nodes trust <id> mesh|guarded|open

给对端钉信任档,钳制发给它的委派暴露面与从它进来的准入策略。

非回环监听必须配置 shared_secret 或 OPENPANDA_SHARED_SECRET,否则 daemon 拒绝启动。把 mesh 扩展到不完全受控的机器之前,先读安全与信任页。

故障排查

先跑 panda doctor,它会把配置、端点、模型、适配器与数据库健康逐行列出来。

  • 模型显示「key 已配置」却连不上:用 doctor 的端点行确认 EffectiveBaseURL 是否被解析器拒绝;拒绝执行的分支一定有一句对应的解释。
  • 数据库报 schema version 比二进制更新:说明跑过非 release 分支的构建,先备份再回退,别直接删库。
  • Windows 上证书吊销检查失败(0x80092012):系统自带 curl 走 Schannel 强制验吊销,CRL/OCSP 不可达即失败,用 --ssl-no-revoke。
  • Windows 拿不到系统代理:Go 的 ProxyFromEnvironment 不读「Internet 选项」,需要显式设置 HTTPS_PROXY 环境变量。
  • update check 成功而 update apply 失败:能连 api.github.com 但连不上 release-assets.githubusercontent.com,用镜像或 OPENPANDA_UPDATE_BASE。