PhyAgentOS/PhyAgentOS-core

面向具身智能体的递归自进化基础设施

技术报告 · 官网 · 文档 · Discord

English · 简体中文

What · Why · v1.1.1 · 安装配置 · 仿真 Quickstart · 快速启动示例 · 文档导航

v1.1.1 · Skill 开发、执行可靠性与 Opper 网关

What · PhyAgentOS 是什么？

PhyAgentOS 是面向具身智能体的递归自进化（RSI）框架。 它将认知规划、Physical Execution 与任务验证连接为跨 Runtime 的反馈闭环，从经过验证的经验中改进 Skill 与 Lesson，并用于后续任务。

Why · 为什么选择 PhyAgentOS？

v1.1.1 更新亮点

Skill 开发、执行可靠性与 Opper 网关。 相对 v1.1.0 的主要变化：

• Opper 网关： 新增 OpenAI 兼容接入，支持 Provider 选择、环境变量凭据和原样传递模型标识。
• 本地 Skill 开发： 本地修改工作流文档和 Node 可执行文件后可带警告运行，绑定与经验仍记录实际激活的工作流哈希；显式 Node 校验和安装缓存验收保持严格。
• Action 拒绝处理： Gateway 明确在分发前拒绝的请求记为失败，不再阻塞后续重试或成功任务的最终判定；超时和远端执行不确定时仍保留原有保护。
• Piper X 开发示例： 双语 Track B 指南与独立仿真 Skill 示例覆盖模型转换、原始 Node locks、打包和历史验证记录；原始运行基线见 Piper X 指南。
• 文档整理： 合并双语手册和贡献指南，新增带实时 GIF 的 MuJoCo Quickstart，并保留评测文档入口。

查看完整更新记录和相对 v1.1.0 的全部变更。

安装与配置

先运行模型驱动的 CLI 对话，再按下文的 MuJoCo Quickstart 操控仿真机器人。准备： Python 3.11 或 3.12、Git，以及模型服务的 API Key。

1. 安装与初始化

git clone --branch v1.1.1 https://github.com/PhyAgentOS/PhyAgentOS-core.git
cd PhyAgentOS-core
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
paos onboard

Windows PowerShell 请将激活命令替换为 .venv\Scripts\Activate.ps1。

2. 配置模型

通过隐藏输入配置密钥，再选择默认 Provider：

paos provider configure openrouter
paos provider use openrouter --model anthropic/claude-sonnet-4

Docker/Secret 输入、进程启动覆盖和 /provider、/model、/effort、/status 会话命令见 Provider CLI 指南。会话切换只影响后续请求， 不改变正在执行的任务及其他会话。

{
  "agents": {
    "defaults": {
      "workspace": "~/.PhyAgentOS/workspace",
      "model": "openrouter/openai/gpt-4o-mini",
      "provider": "openrouter"
    },
    "verification": {
      "serviceEnabled": true,
      "evidenceRetention": "failed",
      "maxReplansPerEpisode": 2,
      "maxVerifierCallsPerRun": 50
    },
    "evolution": {
      "enabled": true,
      "scope": "verified_forge_lineage",
      "promotionMode": "guarded_auto",
      "minSuccessfulEpisodes": 3,
      "minLessonEpisodes": 3,
      "maxLessonsPerSkill": 8,
      "maxEvolutionCallsPerRun": 20
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "YOUR_API_KEY"
    }
  },
  "forge": {
    "requestTimeoutS": 10,
    "pollIntervalS": 0.5,
    "executionTimeoutS": 300,
    "evidence": {
      "requiredImageSources": ["front"],
      "captureTimeoutS": 5,
      "postCaptureTimeoutS": 5,
      "connectionTimeoutS": 2,
      "maxArtifactBytes": 8388608,
      "associationQuality": "best_effort"
    }
  },
  "resourceRegistry": {
    "url": "https://paos-resource-manager.dev.x-era.com"
  }
}

3. 运行第一条请求

paos status
paos agent -m "Hello! Introduce yourself."
paos agent

收到模型回复即完成核心 Agent 与模型服务的连通检查；paos agent 会打开交互式对话。执行物理任务还需要启动对应的 Skill Runtime。

其他模型服务与部署方式见 用户手册 · Docker 部署.

Quickstart · 在 MuJoCo 中操控机器人

[!TIP] 开发者接入自己的机械臂：直接查看 Piper X 完整二次开发 demo。 从模型转换到 Skill 组装，跑通关节与末端位姿控制；配合 Skill 开发手册，选择配置修改、新增 profile 或独立 Node 开发。

以 robot-control-sim 为例，通过关节目标或末端位姿控制仿真 Piper 机械臂。 请先完成上方安装与模型配置。本例使用的预构建仿真 Node 面向 Linux x86_64， MuJoCo 和图像查看器需要可用的图形显示或虚拟显示环境。

1. 安装 Dora

v1.1.1 沿用 Dora CLI 0.4.1（dora-message 0.7.0）兼容基线：

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/dora-rs/dora/releases/download/v0.4.1/dora-cli-installer.sh | sh
dora --version

启动仿真 Runtime 需要 Dora；其他安装方式见 Dora 安装参考。

2. 安装 robot-control-sim

在配置中设置 resourceRegistry.url，或通过 PAOS_RESOURCE_REGISTRY_URL 指向提供 robot-control-sim 及其锁定 Node 制品的部署，再运行：

paos skill search robot-control-sim
paos skill install robot-control-sim
paos skill inspect robot-control-sim

inspect 显示已安装版本、profile 与依赖。本例使用 mujoco-piper；也可选择 mujoco-franka 或 mujoco-so101 切换机器人。独立获取的 Bundle 可用 paos skill install /path/to/robot-control-sim.tar.gz --local 安装，所锁定的 Node 也需可获取。 Core 不内置这些仿真资源。

3. 启动仿真

paos skill start robot-control-sim --profile mujoco-piper
paos skill status robot-control-sim

等待 Runtime 报告健康并打开仿真相机查看器。启动失败时，先通过 paos skill logs robot-control-sim 定位问题，再提交运动请求。

4. 按关节目标和末端位姿控制

Agent 读取 sim.get_robot_info 与实时 Tool context，确认关节、限位、坐标系和单位， 再按活动 Skill 的工作流执行。下方绝对目标适用于 mujoco-piper（arm_base / tcp）； 切换 profile 时应使用对应机器人的坐标系和可达目标。

运动演示使用 verification.mode=off，按 Tool 执行结果判断完成；语义任务验证与证据策略见 Core 开发者手册。

先尝试关节空间请求：

paos agent -m "使用 robot-control-sim 的 mujoco-piper。 \
  检查机器人信息和 Tool context，本次运动演示使用 verification.mode=off。 \
  通过 sim.set_joint_positions 将 joint1-joint6 移动到 [0.35, 0.55, -0.9, 0.15, 0.25, -0.1] rad， \
  velocity_scale 和 acceleration_scale 均为 0.2。 \
  读取动作结果、finalize 任务并简要报告。 \
  不修改文件、不使用 shell 工具；失败时直接报告。"

再尝试末端位姿请求：

paos agent -m "使用 robot-control-sim 的 mujoco-piper。 \
  检查 Tool context，本次运动演示使用 verification.mode=off。 \
  调用 sim.move_eef，将 TCP 移到 arm_base 下的位置 (0.284045, 0.007878, 0.478706) m， \
  四元数 xyzw 为 (-0.002904, 0.693239, 0.008319, 0.720654)， \
  position_tolerance_m=0.01、orientation_tolerance_rad=0.05， \
  velocity_scale 和 acceleration_scale 均为 0.2。 \
  由 motion server 求解 IK；读取动作结果、finalize 任务并简要报告。 \
  不修改文件、不使用 shell 工具；失败时直接报告。"

以上为命令与 MuJoCo 仿真的运行实录，命令画面固定保留以便阅读，并已缩短模型等待停顿。

也可运行 paos agent 进入交互控制。应能在仿真中观察到运动；以返回的执行结果和最终状态为准， 不把请求已接纳当作动作已完成。

5. 停止仿真

运动任务结束后执行：

paos skill stop robot-control-sim

普通停止会先根据配置的工作区恢复保留的执行引用。 也可使用 paos skill reconcile robot-control-sim --workspace /path/to/workspace 显式重试恢复。 无法确认终态的动作仍受保护；--force 表示明确授权终止 runtime。 每轮 runtime 使用独立的 Dora flow 名称，可通过 paos skill status 查看。 平台限制见运行恢复与进程归属。

在此基础上二次开发

• TrackB 框架说明：整体架构、仓库目录与节点协议。
• Skill 开发手册：修改 profile、增加 profile，以及独立开发 Node 并组装 Skill。
• Piper X 二次开发 demo：为 robot-control-sim 接入另一种机械臂，包含模型转换与两种控制方式。
• Bundle 与 Tool 接入参考：manifest 字段、打包和本地安装。

会话记忆与恢复

contextWindowTokens 仅控制归档阈值，不代表模型上下文上限；非正值关闭自动归档。当进程已加载 LiteLLM 时，请求会按其本地 catalog 解析配置中的模型 ID（包括原生 anthropic/、openai/ 前缀），在已知模型窗口中预留输出空间，并保留最近一轮完整对话。网关路由必须有自己的 catalog 条目，不继承原生模型窗口。仅运行 custom / openai_responses 的进程不会为此检查额外加载 LiteLLM；若其他路径也未加载它，catalog 请求窗口保护不会启用，但分块归档仍然有效。未知部署别名不会被归档阈值强行限制请求窗口。如果已知窗口容不下当前轮次或固定指令，PAOS 会说明原因，保留原始会话。图片按每张约 2,048 tokens 的额度估算，不再把 base64 当作文本计数；实际视觉用量因模型和分辨率而异。

记忆归档采用自动工具选择，严格校验 save_memory 的返回结果；返回纯文本时仅追加一次格式重试。超大历史按预算分片处理，在预算允许时优先保留完整消息，并持久化进度以支持失败续跑。归档失败会显示在回复中，自动重试暂停 60 秒。/new 首先将完整原始会话备份到 <workspace>/sessions/archives/；即使模型归档失败，仍会开启新会话并告知备份路径。原始备份保留对话和待完成的归档检查点，供后续恢复；备份不等于已完成记忆摘要。

更多示例

文档导航

News · 最新动态

2026-10-23 · v1.1.1 发布： 新增 Opper 网关，完善本地 Skill 开发和 Action 拒绝处理，并补充双语 Track B 与 Piper X 开发指南。查看发布说明与安装包。

2026-10-10 · GOSIM Shenzhen 2026： PhyAgentOS 入选 Spotlight，并将在开源机器人分论坛做主题分享。查看活动公告与现场信息。

查看完整更新记录。

参与贡献与社区

请先阅读贡献指南与开发手册，建议优先参与 TrackB 的 Node、Skill 和机器人/环境接入开发。资源平台的外部贡献提交及已有登记仓库修改暂未开放，需等待审批服务完成并开放后支持；现阶段可进行本地开发验证，具体范围与源码评审流程见贡献指南。

python -m pip install -e ".[dev]"
pytest
ruff check PhyAgentOS tests
python -m compileall -q PhyAgentOS tests

Discord · X · Bilibili · LinkedIn · 小红书

引用与致谢

如果 PhyAgentOS 对你的研究有帮助，欢迎引用我们的技术报告。

@article{liu2026phyagentos,
  title={PhyAgentOS: A Self-Evolving Operating System for Embodied Agents with Decoupled Cognitive Planning and Physical Execution},
  author={Liu, Yang and Chen, Weixing and Song, Xinshuai and Pu, Tao and Mo, Siwen and Bai, Yongjie and Chen, Zihao and Sun, Qianran and Zhong, Liruo and Shen, Ying and others},
  journal={arXiv preprint arXiv:2607.16636},
  year={2026}
}

感谢 MuJoCo、ROS、各开放基准的维护者，以及所有 PhyAgentOS 贡献者。

由 中山大学 HCP 实验室、鹏城实验室 与 拓元智慧 联合开发。

     

_{MIT License · Copyright © 2025–2026 PhyAgentOS}