PhyAgentOS — 命令行参考

`paos onboard`

初始化一个新的 PhyAgentOS 工作区。创建配置文件和工作区目录，并生成所有协议 Markdown 文件。

paos onboard

参数	类型	说明
`--workspace PATH`	string	自定义工作区路径。默认：`~/.PhyAgentOS/workspace`
`--force`	flag	强制覆盖已有工作区文件，无需确认提示

生成的文件：

~/.PhyAgentOS/config.json — 系统配置
ENVIRONMENT.md — 环境状态真相源
EMBODIED.md — 机器人能力画像
ACTION.md — 动作派发队列
LESSONS.md — 失败经验记录

提示：升级 PhyAgentOS 后重新运行 paos onboard 可将配置模板更新到最新版本。

`paos agent`

启动交互式 Agent（Track A）。Planner-Critic 循环在此运行，读取环境状态并向 Track B 派发动作。

paos agent

参数	类型	说明
`-m "消息"`	string	单次模式：发送一条指令后退出。不加此参数则进入交互式 REPL 模式。
`--model 模型名`	string	覆盖 LLM 模型。示例：`--model openrouter/anthropic/claude-sonnet-4`
`--workspace 路径`	string	自定义工作区路径。默认从 `config.json` 读取

交互模式

默认模式。Agent 显示提示符（>）等待自然语言任务输入。会话持续到 Ctrl+C 或 /exit。

单次模式

使用 -m 参数用于脚本化和自动化。Agent 处理一条指令后退出——非常适合 CI 流水线和批量测试。

paos agent -m "移动到厨房，描述你看到的东西。" --model openrouter/openai/gpt-4o-mini

`paos gateway`

启动长期运行的网关服务。提供渠道集成（Telegram、Slack、飞书）和基于心跳的 Agent 循环调度。

paos gateway

参数	类型	说明
`--port PORT`	int	HTTP 服务器端口。默认：8080
`--host HOST`	string	HTTP 服务器绑定地址。默认：0.0.0.0

网关集成外部消息渠道，可在收到消息时触发 Agent。在 ~/.PhyAgentOS/config.json 的 channels 键下配置渠道。

使用场景：将网关部署在云服务器上，通过 Telegram 或 Slack 从任何地方控制你的机器人。

`python hal/hal_watchdog.py`

启动硬件看门狗（Track B）。轮询 ACTION.md 中的待处理动作，并将其分派到指定的驱动程序。

python hal/hal_watchdog.py --driver simulation

参数	类型	说明
`--driver 驱动名`	string	必填。选择驱动。内置：`simulation`、`rekep_sim`。外部：`rekep_real`、`go2_edu`
`--gui`	flag	启用 GUI 窗口，实时可视化仿真场景
`--interval 秒`	float	检查 `ACTION.md` 的轮询间隔。默认：1.0
`--driver-config 路径`	string	驱动专属 YAML/JSON 配置文件的路径。示例：`--driver-config configs/drivers/go2_edu.yaml`
`--workspace 路径`	string	覆盖工作区目录。默认从 `config.json` 读取
`--robot-id ID`	string	指定要控制的机器人。Fleet 模式下必填。示例：`--robot-id go2_edu_001`

# 仿真模式，带 GUI 和更快轮询
python hal/hal_watchdog.py --driver simulation --gui --interval 0.5

# 真机模式，带自定义配置
python hal/hal_watchdog.py --driver rekep_real --driver-config configs/drivers/franka.yaml --robot-id franka_001

`python scripts/run_runtime_watchdog.py`

启动 Runtime 看门狗（V2 基于会话的执行器）。读取 SESSIONS.md 并将会话分派到对应的 SkillRuntime 和 TargetAdapter。

python scripts/run_runtime_watchdog.py --workspace /tmp/paos_runtime

参数	类型	说明
`--workspace PATH`	string	Runtime 工作区路径。必填。
`--once`	flag	对所有待处理会话执行一次遍历后退出。不加此参数则看门狗在轮询循环中持续运行。
`--environment-workspace PATH`	string	环境状态的独立工作区。Fleet 模式下，当环境维护在共享工作区而非 per-robot 会话工作区时使用。

Fleet 模式：使用 --environment-workspace 指向持有全局 ENVIRONMENT.md 的共享工作区。每台机器人的看门狗从共享环境读取，但将会话写入自己的专属工作区。

`python scripts/init_runtime_workspace.py`

初始化一个 Runtime 工作区，包含基于会话执行所需的所有配置文件和目录结构。

python scripts/init_runtime_workspace.py --workspace /tmp/paos_runtime

参数	类型	说明
`--workspace PATH`	string	创建 Runtime 工作区的路径。必填。

生成的结构：

TARGETS.md — Runtime Target 注册表
SKILLS.md — Runtime Skill 注册表
SESSIONS.md — 会话队列
configs/runtime/ — 传感器与感知 YAML 配置

`python scripts/deploy_rekep_real_plugin.py`

部署 ReKep 真机插件，用于机械臂（Dobot、Franka 等）的自然语言抓取。

python scripts/deploy_rekep_real_plugin.py --repo-url https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.git

参数	类型	说明
`--repo-url URL`	string	ReKep 插件仓库地址。除非已设置默认值，否则必填。
`--with-solver`	flag	同时安装 ReKep 约束求解器，用于高级抓取姿态优化
`--no-install-deps`	flag	跳过 Python 依赖安装（用于自行管理依赖的情况）
`--ref BRANCH`	string	要检出的 Git 分支或标签。默认：`main`

部署后：使用 python hal/hal_watchdog.py --driver rekep_real 启动看门狗以使用该插件。

常用组合速查表

四种常见启动场景及各终端需要执行的确切命令。

场景	终端 1（Track B / 看门狗）	终端 2（Track A / Agent）
单机仿真	`cd PhyAgentOS python hal/hal_watchdog.py --driver simulation --gui`	`cd PhyAgentOS paos agent`
单机真机	`cd PhyAgentOS python hal/hal_watchdog.py --driver rekep_real --driver-config configs/drivers/franka.yaml`	`cd PhyAgentOS paos agent --model openrouter/anthropic/claude-sonnet-4`
Fleet 模式	`# 机器人 A python hal/hal_watchdog.py --driver go2_edu --robot-id go2_edu_001 --workspace /tmp/paos_fleet/robot_a # 机器人 B python hal/hal_watchdog.py --driver franka --robot-id franka_001 --workspace /tmp/paos_fleet/robot_b`	`cd PhyAgentOS paos agent --workspace /tmp/paos_fleet/shared`
Runtime 会话测试	`python scripts/init_runtime_workspace.py --workspace /tmp/paos_runtime_smoke python scripts/run_runtime_watchdog.py --workspace /tmp/paos_runtime_smoke --once` 单个终端：初始化工作区后执行一次遍历。会话 `sess_dummy_smoke` 运行并报告成功。