aios-management-serivce

aios-management-serivce 是 AIOS 管理控制台通过 MQTT 调用 OpenClaw 管理能力的服务。它负责执行少量稳定的管理指令，并把目录同步收敛到 catalog.snapshot，把 Token 用量同步收敛到 agent.usage.list。

职责

• 接收管理 MQTT 请求并返回统一 JSON 响应
• 管理托管 Agent 的创建、启停、删除、模型和文档
• 导出托管 Agent 工作区 zip，并上传到管理端 S3 outbox
• 管理 Agent 模板、全局 Skill、LLM Provider / Model
• 管理业务系统元数据和调用日志
• 提供目录快照一次性同步、Agent Token 用量同步、诊断、Gateway 状态和重启能力

运行要求

• Node.js >= 20
• OpenClaw 从 2026.5.28 起支持当前同步协议，部署环境不需要兼容更早版本
• 容器部署时通常由镜像启动脚本注入 AIOS_* 环境变量

常用环境变量：

AIOS_DATA_DIR="/var/aios/data"
AIOS_ONTOLOGY_DIR="/var/aios/ontology"
AIOS_OPENCLAW_HOME="/var/aios/.openclaw"
AIOS_RUN_MODE="container"
AIOS_WORKSPACE_TEMPLATES_DIR="/var/aios/workspace-templates"
AIOS_MQTT_CHANNEL_BROKER="mqtt://127.0.0.1:1883"
AIOS_MQTT_CHANNEL_USERNAME="user"
AIOS_MQTT_CHANNEL_PASSWORD="pass"
AIOS_ADMIN_INBOUND_TOPIC="aios/admin/inbound"
AIOS_ADMIN_OUTBOUND_TOPIC="aios/admin/outbound"
AIOS_AGENT_CHANNEL_INBOUND_TOPIC_TEMPLATE="aios/agent/{agentId}/inbound"
AIOS_AGENT_CHANNEL_OUTBOUND_TOPIC_TEMPLATE="aios/agent/{agentId}/outbound"
AIOS_S3_ENDPOINT="http://127.0.0.1:9000"
AIOS_S3_REGION="local"
AIOS_S3_ACCESS_KEY_ID="minio-access"
AIOS_S3_SECRET_ACCESS_KEY="minio-secret"
AIOS_S3_FORCE_PATH_STYLE="true"
AIOS_S3_ADMIN_INBOX_BUCKET="admin-in"
AIOS_S3_ADMIN_OUTBOX_BUCKET="admin-out"

启动

npm install
npm run build
npm start

全局安装后也可以直接启动：

aios-management-serivce

消息格式

请求发布到 AIOS_ADMIN_INBOUND_TOPIC：

{
  "requestId": "req-001",
  "action": "service.ping",
  "params": {}
}

响应发布到 AIOS_ADMIN_OUTBOUND_TOPIC：

{
  "requestId": "req-001",
  "action": "service.ping",
  "ok": true,
  "result": {
    "pong": true
  },
  "timestamp": "2026-06-04T00:00:00.000Z"
}

公开指令

公开 34 个指令，以 src/capabilities/registry.ts 为准：

• service.ping
• version.list
• catalog.snapshot
• agent.get
• agent.create
• agent.enable
• agent.disable
• agent.delete
• agent.usage.list
• agent.model.set
• agent.name.set
• agent.docs.update
• agent.workspace.export
• agent.template.create
• agent.template.delete
• llm.provider.create
• llm.provider.update
• llm.provider.test
• llm.provider.delete
• llm.model.create
• llm.model.test
• llm.model.update
• llm.model.delete
• skills.global.list
• skills.global.install.local
• skills.global.delete
• apps.create
• apps.enable
• apps.disable
• apps.delete
• apps.log.record
• diagnostics.run
• gateway.status
• gateway.restart

目录类读取统一使用 catalog.snapshot；管理控制台自己的列表和状态统一从本地数据库读取。catalog.snapshot 只返回同步落库所需的紧凑字段，Token 用量由 agent.usage.list 单独同步，以降低 MQTT 单条消息体积。详细请求示例见 docs/compatibility-list.md，设计说明见 docs/design.md。

导出 Agent 工作区

agent.workspace.export 用于把托管 Agent 的工作区打包为 zip 并写入 S3。请求参数：

{
  "agentId": "finance-agent",
  "bucket": "admin-out",
  "objectKey": "agent-workspace/2026-06-04/finance-agent-workspace.zip"
}

bucket 建议使用 AIOS_S3_ADMIN_OUTBOX_BUCKET。objectKey 可由调用方生成；未传入时服务会生成 agent-workspace/<date>/<uuid>-<agentId>.zip。

zip 根目录固定导出 AGENTS.md，并会在存在时包含 SOUL.md、TOOLS.md、HEARTBEAT.md、.learnings/、skills/、knowledge/。响应会返回 S3 位置、文件名、字节数、已包含条目和缺失的可选条目：

{
  "agentId": "finance-agent",
  "bucket": "admin-out",
  "objectKey": "agent-workspace/2026-06-04/finance-agent-workspace.zip",
  "fileName": "finance-agent-workspace.zip",
  "byteSize": 2048,
  "entries": ["AGENTS.md", "SOUL.md", ".learnings/LEARNINGS.md", "skills/planner/SKILL.md"],
  "missing": ["TOOLS.md", "HEARTBEAT.md", "knowledge"]
}