PhyAgentOS — 配置指南

配置文件位置

~/.PhyAgentOS/config.json 是默认配置文件，由 paos onboard 自动创建。

CLI 参数→ config.json→ 内置默认值

优先级顺序：CLI 参数 总是覆盖 配置文件 的值，配置文件覆盖 内置默认值。

自定义配置路径：设置 PAOS_CONFIG 环境变量指向其他配置文件。export PAOS_CONFIG=/path/to/my_config.json

`agents.defaults`

Agent 默认设置：模型选择、工作区路径、对话轮次限制和生成温度。

"agents": {
  "defaults": {
    "model": "openrouter/openai/gpt-4o-mini",
    "workspace": "~/.PhyAgentOS/workspace",
    "max_turns": 50,
    "temperature": 0.7
  }
}

字段	类型	说明
`model`	string	LLM 模型标识符，格式为 `provider/model-name`。示例：`openrouter/openai/gpt-4o-mini`、`openai/gpt-4o`、`azure/gpt-4`
`workspace`	string	默认工作区目录路径。`~` 会被展开为用户主目录。
`max_turns`	int	每个任务的最大 Planner-Critic 循环次数。作为安全限制防止无限循环。
`temperature`	float	LLM 采样温度（0.0–2.0）。越低越确定性，越高越有创造性。

`providers`

配置 LLM API 提供商。至少要配置一个 provider，Agent 才能正常工作。

OpenRouter

"providers": {
  "openrouter": {
    "api_key": "sk-or-v1-..."
  }
}

OpenAI

"providers": {
  "openai": {
    "api_key": "sk-..."
  }
}

Azure

"providers": {
  "azure": {
    "api_key": "...",
    "api_base": "https://your-resource.openai.azure.com",
    "api_version": "2024-02-15-preview"
  }
}

自定义（兼容 OpenAI）

"providers": {
  "custom": {
    "api_key": "...",
    "api_base": "https://your-llm-service.example.com/v1"
  }
}

必填字段

每个 provider 都需要 api_key。自定义 provider 还需要 api_base — 即兼容 OpenAI 接口的服务端点 URL。

多 Provider

可以同时配置多个 provider。Agent 根据模型前缀匹配对应的 provider（例如 openrouter/ → openrouter 配置）。

`tools`

启用或禁用 Agent 可调用的各个内置工具。禁用来使用的工具可以缩小模型的决策空间。

"tools": {
  "execute_robot_action": true,
  "target_navigation": true,
  "read_file": true,
  "write_file": true,
  "check_workspace": true,
  "update_task": true,
  "search_lessons": true,
  "get_time": true
}

工具	说明
`execute_robot_action`	将动作分发到 `ACTION.md` 供看门狗执行
`target_navigation`	利用感知反馈导航到可视目标
`read_file`	读取工作区中的任何文件（ENVIRONMENT.md、TASK.md 等）
`write_file`	写入或更新工作区文件
`check_workspace`	列出工作区中所有文件及其最后修改时间戳
`update_task`	更新 TASK.md 中的任务状态和子任务进度
`search_lessons`	在 LESSONS.md 中搜索历史失败模式
`get_time`	获取当前系统时间，用于带时间戳的动作

安全说明：所有工具的操作范围限定在工作区目录内。Agent 无法读取或写入配置的工作区目录之外的文件。

`embodiments`

配置机器人部署模式。Single 模式运行单台机器人；Fleet 模式协调多台机器人并共享状态。

单机模式

"embodiments": {
  "mode": "single"
}

单机模式无需其他配置。默认工作区管理一台机器人。使用一个 --driver 参数启动看门狗。

Fleet 模式

"embodiments": {
  "mode": "fleet",
  "shared_workspace": "/tmp/paos_fleet/shared",
  "instances": [
    {
      "robot_id": "go2_edu_001",
      "driver": "go2_edu",
      "workspace": "/tmp/paos_fleet/robot_a"
    },
    {
      "robot_id": "franka_001",
      "driver": "rekep_real",
      "workspace": "/tmp/paos_fleet/robot_b"
    }
  ]
}

字段	类型	说明
`mode`	string	`"single"` 为单台机器人；`"fleet"` 为多机器人协同
`shared_workspace`	string	仅 Fleet 模式。持有全局 ENVIRONMENT.md、TASK.md、ORCHESTRATOR.md、LESSONS.md 的共享工作区路径
`instances`	array	仅 Fleet 模式。机器人实例数组，每个包含 `robot_id`、`driver` 和 `workspace`
`instances[].robot_id`	string	该机器人的唯一标识符。用于路由动作和追踪状态
`instances[].driver`	string	该机器人实例使用的驱动名称
`instances[].workspace`	string	该机器人用于 ACTION.md 和 EMBODIED.md 的专属工作区路径

`channels`

配置网关服务的外部消息渠道。每个渠道可实现与 Agent 的远程交互。

Telegram

"channels": {
  "telegram": {
    "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "chat_id": "-1001234567890"
  }
}

Slack

"channels": {
  "slack": {
    "bot_token": "xoxb-...",
    "channel": "#robot-control"
  }
}

飞书 (Lark)

"channels": {
  "feishu": {
    "app_id": "cli_a...",
    "app_secret": "..."
  }
}

渠道	必填字段	备注
`telegram`	`bot_token`, `chat_id`	从 @BotFather 获取 bot token
`slack`	`bot_token`, `channel`	在 api.slack.com/apps 创建 Slack 应用
`feishu`	`app_id`, `app_secret`	在飞书开放平台创建飞书机器人

`gateway`

配置网关服务参数：HTTP 监听地址、端口和 API 请求超时时间。

"gateway": {
  "port": 8080,
  "host": "0.0.0.0",
  "request_timeout": 30
}

字段	类型	默认值	说明
`port`	int	8080	HTTP 服务器监听端口
`host`	string	0.0.0.0	HTTP 服务器绑定地址。如需仅本地访问，使用 `127.0.0.1`
`request_timeout`	int	30	等待 LLM API 响应的最长秒数

最小配置模板

可直接复制粘贴的起点。将占位值替换为你实际的 key 和路径。

单机模式（最小配置）

{
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-4o-mini",
      "workspace": "~/.PhyAgentOS/workspace",
      "max_turns": 50
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "YOUR_OPENROUTER_API_KEY"
    }
  },
  "tools": {
    "execute_robot_action": true,
    "read_file": true,
    "write_file": true,
    "check_workspace": true
  },
  "embodiments": {
    "mode": "single"
  }
}

Fleet 模式（最小配置）

{
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-4o-mini",
      "workspace": "/tmp/paos_fleet/shared",
      "max_turns": 50
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "YOUR_OPENROUTER_API_KEY"
    }
  },
  "tools": {
    "execute_robot_action": true,
    "read_file": true,
    "write_file": true,
    "check_workspace": true
  },
  "embodiments": {
    "mode": "fleet",
    "shared_workspace": "/tmp/paos_fleet/shared",
    "instances": [
      {
        "robot_id": "go2_edu_001",
        "driver": "go2_edu",
        "workspace": "/tmp/paos_fleet/robot_a"
      },
      {
        "robot_id": "franka_001",
        "driver": "rekep_real",
        "workspace": "/tmp/paos_fleet/robot_b"
      }
    ]
  }
}