FAQ
常见问题
先判断你的任务是否需要 Panda,再了解如何沿用已有的 Agent、连接第二台设备和检查交付。
入门
已经在用 Agent 或 harness,什么时候值得加 Panda?
现有 Agent 或 harness 已经能办完的任务,继续用它就好。值得加 Panda 的时候,是工作要在你管理的不同设备和 Agent 之间交接,你还希望在同一处收回结果、看清验证和卡点。Panda 不要求换掉现有 Agent,也不要求把调度交给厂商托管。
装好之后第一步做什么?
跑 panda init 生成 config.yaml 与能力卡,节点名自动取主机名,只问是否现在配置模型;然后 panda 进 TUI,或 panda web 开控制台。panda doctor 随时自检 PATH、配置、数据库、适配器与 agent CLI。
panda 和 panda daemon 什么关系?
裸 panda 是交互式使用;panda daemon 是后台常驻进程,负责调度、心跳与提醒,也接收远程委派。注意 panda web 自己会起一个完整节点并占用 7836/7837,同一台机器再起 daemon 会争抢端口,日常选一个入口即可。
需要 GPU 或额外的模型额度吗?
不需要 GPU。路由、监督与验收都用你已经配置的模型提供方,本机模型或 API 都可以;守护进程空闲时常驻内存约 40MB,几乎不占 CPU。
数据会不会经过你们的服务器?
不会,也没有「我们的服务器」。节点之间 P2P 直连,会话内容按信任档逐跳钳制,断网时走 DTN 存储转发;唯一离开节点的是你自己配置的模型调用。
模型配置
支持哪些模型服务?
任何 OpenAI 兼容或 Anthropic 兼容端点,api_type 填 anthropic(Messages 协议)或 openai(Chat Completions 协议)。v0.1.1 起入口客户端还原生支持 OpenAI Responses 与 Google Gemini。
报错「未配置模型 API key」?
三选一:panda init 引导填写、panda web 设置页保存(热生效,无需重启)、或环境变量 OPENPANDA_MODEL_API_KEY。
报错「模型接口不存在」?
base_url 或 model 名称写错。用控制台设置页的「测试连通」逐项排查;Anthropic 兼容端点不带 /v1 后缀。
额度用完了任务会中断吗?
不会。多模型注册表带健康熔断,额度耗尽或凭据失效(401/403)会自动注入备用模型;入口模型还带指数退避重试,持续限流才会停下。
智能体与适配器
什么是 agent 适配器?
OpenPanda 自己不执行长程任务,而是委派给设备上装好的 agent CLI;adapters/*.py 是统一协议的桥接脚本。panda agents 查看本机已装与缺失的 agent,并给出缺失项的安装命令。
支持哪些 Agent?
内置 10 个适配器:Claude Code、Codex、OpenCode、Grok Build、DeepSeek Harness、Antigravity、Hermes、Pi、ZCode、OpenClaw;另有一个 generic 通用桥,可接任意走 stdin/stdout 的无头 CLI。
某个 agent 没装,还能用吗?
能。不装也完全可用:调度器只把任务路由到声明了该 agent 的设备,在能力卡里删掉对应条目即可。require 声明是硬过滤条件。
凭证怎么给 agent?
默认 injection.model: auto——agent 自带登录态就直接用,没有自有凭证的复用 panda 配置的模型。用 panda config set injection auto|always|never 切策略,panda agents 会标出各适配器的注入支持。
任务与调度
任务一直 pending?
依次检查:daemon 是否在跑(panda nodes 看 running 列)、能力卡是否存在(panda doctor 的 adapters 行)、目标 agent 是否已安装。
什么是 tier-2 授权?
命令分两级:tier-1 可逆(读文件、跑构建)默认放行;tier-2 不可逆(git push、删除)默认拒绝,需要 panda ask --authorize、REPL /authorize 或能力卡声明。被拒的任务进 review 队列并说明原因。
任务进了 review 状态?
不可逆操作或超出预算的监督循环会暂停等人审批:panda queue 查看,panda approve <id> / reject <id> 决定,Web 控制台任务卡上有同样的按钮。
一件事要跨几台机器做怎么办?
那是 plan 而不是单个任务:几个前后相接的阶段,每段路由到适合它的机器,被依赖阶段的产物自动打包搬到下一段。panda plan example 生成模板,panda plan run x.yaml --dry-run 先看路由;也可以直接一句话让入口模型自己拆。计划的任何阶段都不携带 tier-2 同意。
什么是 scope drift?
入口模型为每个任务声明允许操作的文件范围;执行中越界写文件会被拦截并转 review。合法操作被误拦时,检查任务描述里是否明确列出了要改的文件路径。
会话与交互
什么是侧边对话?
/side(或 /btw)在线程旁开一个独立会话:拿到与主线程相同的工具面,动作照常过权限与审批门,但问答不写回主线程。会话存在节点上,刷新、换设备甚至面板重启后都还在。
想撤销一轮里的文件改动?
/rewind 列出该会话的检查点,选中后恢复快照里的跟踪文件、删除快照之后新建的未跟踪文件,并把 transcript 截断到对应轮次。被 .gitignore 的构建产物不会被删。
回复里的文件路径能点吗?
能。控制台把可识别的工作区路径渲染成链接,点击在旁侧只读查看器打开并滚到行;终端里 panda read path:line 同样查看,/edit path:line 交给编辑器。
会话上下文能存多久?
会话按线程保存在节点的数据目录。上下文超出预算时只压缩给模型回放的摘要,原始消息仍保留;供应商已返回的思考摘要与部分回答会随操作进度保存,刷新后继续显示,停止按钮仍针对同一次操作。旧版本已删除的消息或从未保存的思考无法补回;长线程可用 panda session fork 分叉。
多设备与安全
多台设备怎么组网?
每台设备 panda init 后两条路径任选:蓝牙式配对(panda pair <addr> 发起并显示短码,另一台 panda pair confirm 核对同一码,共享密钥经加密通道自动下发),或 LAN 发现加指纹准入(panda nodes 列出待准入设备,panda nodes admit <id> 按指纹确认,nodes verify 钉死 Ed25519 指纹)。
为什么对外监听启动被拒绝?
安全约束:非回环监听必须配置 shared_secret(或 OPENPANDA_SHARED_SECRET),否则 daemon 拒绝启动。回环监听不受限,且 Web 面板会自动生成临时 token。
同一台机器能跑两个节点吗?
同一节点身份有单例锁,第二个 daemon 会诊断后退出。需要多身份时用 VM 节点(node.kind: vm 加显式 node.identity)。
能让它看屏幕、点鼠标吗?
能,但有边界。带桌面会话的节点广告 hardware:screen_capture 与 hardware:gui_input(后者因不可逆属 tier-2),无头守护进程不广告这两项。屏幕内容只在 mesh 档链路上移动,非 mesh 来源的截屏任务在准入即拒;macOS 还需要「录屏」「辅助功能」授权。
数据与维护
数据存在哪里?
用户级目录,与安装位置无关:macOS ~/Library/Application Support/openpanda,Linux ~/.local/share/openpanda,Windows %LOCALAPPDATA%\openpanda-data。memory/、projects/、skills/ 是用户资产,卸载默认保留。
如何升级?
panda update check / apply(或 panda upgrade)走验签通道;一键脚本用户直接重跑安装命令也可以,配置、会话与数据保留。降级会被拒绝:解包后比对新二进制的迁移上限与数据目录 schema。
如何彻底卸载?
panda uninstall 白名单删除并自动备份;--purge 连用户数据一起删,--backup-only 只归档不删除,--dry-run 只看计划不动手。
Web 控制台打不开或 token 丢了?
回环模式重新 panda web 即可,URL 自带临时 token,前端读取后立刻从地址栏清除。对外监听需要 OPENPANDA_PANEL_TOKEN;所有 /api/* 请求仅接受 Authorization: Bearer 头,URL 里的 ?token= 会被拒绝。