PhyAgentOS — 故障排查

排查方法论

遇到问题时，按层级依次验证。不要跳过任何步骤——每一层都依赖于前一层正常工作。

1

python -c "from hal.drivers.simulation import SimulationDriver" — 验证所有依赖可解析。

2

独立启动该组件。能否在无立即崩溃的情况下达到就绪状态？

3

提供最小有效输入。能无错误地产生输出吗？

4

验证输出是否以预期格式写入正确的状态文件。

症状	原因	解决方案
`pip install` 失败	Python 版本低于 3.11	运行 `python --version` 检查。安装 Python ≥ 3.11。
`paos: command not found`	可编辑安装未生效或环境错误	在项目根目录重新运行 `pip install -e .`。用 `which paos` 验证。
Conda 环境冲突	旧环境中的依赖版本冲突	创建全新 conda 环境：`conda create -n phyagentos python=3.11` 然后重新安装。
`ModuleNotFoundError: hal`	PYTHONPATH 未包含项目根目录	确保在项目根目录下执行命令，或设置 `export PYTHONPATH=.`

症状	原因	解决方案
驱动未找到	驱动名称拼写错误或插件未注册	确认驱动名称。对于插件，运行部署脚本并检查 `PhyAgentOS_plugin.toml`。
Profile 未安装	`get_profile_path()` 返回 None 或无效路径	检查驱动的 `get_profile_path()` 实现。EMBODIED.md 文件必须存在于返回的路径。
连接超时	驱动 `connect()` 失败——网络或硬件问题	检查与机器人的网络连通性。验证驱动配置中的 IP/端口。尝试 ping 机器人。
ACTION.md 格式错误	JSON 结构无效或 `status` 不为 `"pending"`	验证 JSON 格式正确。`status` 字段必须为 `"pending"` Watchdog 才会消费该动作。
端口冲突	同一端口上运行了多个 Watchdog	每个工作区只能有一个 Watchdog 实例。使用不同工作区或 `--driver-config` 分配不同端口。

症状	原因	解决方案
LLM API 调用失败	config.json 中缺少或 `api_key` 无效	确认 `~/.PhyAgentOS/config.json` 中已设置 `api_key`。检查 LLM 提供商的 API 状态。
工具不可用	工具未在 tools 配置中注册	检查 config.json 中的 `tools` 部分。确保工具名称与注册的工具类匹配。
Critic 拒绝所有动作	EMBODIED.md 与机器人能力不匹配，或 LESSONS.md 存在阻断模式	检查 EMBODIED.md 准确性——关节范围、负载限制、工作空间边界。查看 LESSONS.md 中累积的拒绝模式。如被污染可尝试重置 LESSONS.md。
Agent 卡住/无响应	Watchdog 未运行或未消费 ACTION.md	确认 Watchdog 正在运行并消费动作。检查 ACTION.md 状态——如果卡在 `executing`，Watchdog 可能挂在一个长时间动作上。

症状	原因	解决方案
多个 Watchdog 端口冲突	两个 Watchdog 实例共用一个网络端口	使用 `--driver-config` 为每个实例分配唯一端口。每台机器人应有独立工作区。
ROBOTS.md 不更新	Watchdog 未刷新或写权限问题	重启受影响的 Watchdog。检查共享工作区目录的写入权限。
ACTION.md 目标错误	动作参数中的 `robot_id` 与目标机器人不匹配	验证每个动作的 `robot_id` 是否与目标机器人配置一致。检查 ORCHESTRATOR.md 的任务分配。
共享状态不可见	共享工作区中的 ENVIRONMENT.md 已过时或被锁定	检查共享工作区中的 ENVIRONMENT.md。确认每个 Watchdog 正在写入其 `robots.<robot_id>` 键。

症状	原因	解决方案
预检失败	传感器配置 YAML 路径不正确或标定文件缺失	确认 `configs/runtime/sensors/*.yaml` 中的路径指向真实文件。检查标定文件是否存在。
会话被标记为 `rejected`	TARGETS.md 感知配置不兼容，或技能需求未满足	检查 TARGETS.md 中的 `perception` 部分。确认 SKILLS.md 声明了技能所需的传感器。查看预检错误详情。
未生成 `episode.json`	会话未完成——在 SESSIONS.md 中检查状态	查看 SESSIONS.md 中会话的最终状态。检查 LOG.md 中的错误信息。
感知输出缺失	管线未覆盖所需的输出通道	确认感知 YAML 配置包含所有必需的输出通道。检查模型输出键是否与管线配置匹配。

当无法定位根因时，按顺序检查每个状态文件。这是最可靠的兜底调试方法。

ENVIRONMENT.md — 机器人状态是否正确？留意过时的位姿、错误的 connection_state 或缺失的传感器数据。如果状态不变，Watchdog 可能已停止更新。
ACTION.md — 是否有待处理的动作？如果队列在增长，说明 Watchdog 未消费它们。检查 Watchdog 终端是否有错误。
EMBODIED.md — profile 与真实机器人是否匹配？关节范围、控制模式和负载限制必须反映实际情况。不匹配的 profile 会导致 Critic 拒绝有效动作。
LESSONS.md — 最近有拒绝记录吗？每条拒绝包含时间戳、robot_id 和原因。扫描找规律——同一动作类型反复被拒绝意味着系统配置问题。
SESSIONS.md（仅 Runtime 路径）— 检查会话状态。如果全部为 rejected，则是预检或配置问题。如果为 timeout，检查 execute_timeout 值。
LOG.md（仅 Runtime 路径）— 查看最近的条目。LOG.md 记录每个会话的结果及错误详情。

小技巧：使用 watch -n 1 'cat ACTION.md' 实时监控文件。配合独立的 Watchdog 和 Agent 终端观察完整循环。