EdgeClaw 新手教程

← 返回使用指南
适用平台：OpenHarmony 标准系统（ZhihongOS · RK3588）
云平台：EdgeHub · JetLinks
依赖服务：EdgeComputer + EdgeMCP
版本信息：EdgeClaw v0.1.0

章节	内容
一、开始之前	学什么、怎么读这份文档
二、连接开发板	hdc 连接、确认三服务在跑
三、快速开始	5 分钟健康检查与第一条对话
四、对话控制设备	经 MCP 查设备、控属性
五、从 EdgeHub 扩展能力	网页截图、安装 Skill / Agent
六、工作原理	五大服务、会话、主/子智能体
七、功能一览	服务、端口、核心能力速览
八、JetLinks 端云联调	插件视角端云全链路
九、命令手册	子命令与参数说明
十、Skill 与子 Agent 深入	概念、目录结构、本地安装
十一、联邦群体智能	双板组网、远程 invoke
十二、常见问题	连不上、装不上怎么办
十三、附录	命令速查、练手 checklist

一、开始之前

1.1 这份文档帮你做什么

EdgeClaw 是跑在 OpenHarmony 板子上的 AI 管家：你用自然语言对话，它通过 Skill、子 Agent 和 MCP 工具完成运维诊断、设备查询控制，还能从 EdgeHub 在线扩展能力。

按下面顺序读，可以从零完成一次完整体验：

第二章：hdc 连板子，确认 edgeclaw_service 与依赖服务在运行
第三章：健康检查 + 第一条对话，约 5 分钟跑通
第四章：用对话查询 IoT 子设备（经 EdgeMCP → EdgeComputer）
第五章：从 EdgeHub 安装 Skill / 子 Agent，扩展板端能力
第六章：理解五大服务、会话与主/子智能体——读懂前几章在干什么
第九章：需要查某个子命令或参数时当字典用

第三章跑通后，就可以边做边回头看第六章；不必一次读完。

1.2 你需要准备

项目	说明
开发板	已烧录含 EdgeClaw 的 ZhihongOS 镜像
宿主机	已安装 `hdc`，能 `hdc shell` 进板子
LLM API Key	对话功能需在 `model_factory.json` 配置（见 2.6 节）；`health`、`schema` 等不依赖 LLM
基础命令	会复制粘贴 Shell；JSON 输出看得懂字段名更好
可选	已读 EdgeComputer 教程并完成连云，第四章控设备更顺畅

1.3 CLI 名称与全局约定

官方命令是 edgeclaw（无下划线）。查用法：

bash

edgeclaw --version
edgeclaw schema
edgeclaw schema chat

环境	标识	说明
宿主机	`【宿主机】`	`hdc shell`、`hdc file send` 等
板端	`【板端】`	先 `hdc shell`，再执行 `edgeclaw`

全局选项必须放在子命令前面（OHOS 板端约定）：
bash
# ✅ 正确
edgeclaw --format json health

# ❌ 错误
edgeclaw health --format json

二、连接开发板

ZhihongOS 开机后，edgeclaw_service、edgemcp、edgecomputer_service 会由系统自动拉起，一般无需手动 service_control start。本章确认你能连上板子、三服务在线，再进入第三章对话实验。

2.1 宿主机连接开发板

bash

# 【宿主机】
hdc list targets
hdc shell

确认设备在线后再进入板端 shell。多设备时可用 hdc -t <serial> shell 指定目标。

2.2 确认三服务已运行

出厂镜像在系统启动时会自动拉起 edgecomputer_service、edgemcp、edgeclaw_service，教程无需手动 service_control start。hdc shell 进入板端后，先确认三服务在线：

bash

# 【板端】
edgeclaw --format json health --all
# 期望：aggregate_ready=true

ps -ef | grep -E 'edgeclaw_service|edgemcp|edgecomputer_service' | grep -v grep
# 期望：三个进程均存在，edgeclaw_service 用户为 system

若 aggregate_ready=false，再查第十二章常见问题；必要时才使用 service_control 重启（见 9.14、12.2 节）。

2.3 第一步验证

日常操作只需使用 edgeclaw 命令，无需记忆配置文件或日志在板端的存放路径（排障时可参考第十二章）。

bash

edgeclaw --version
edgeclaw --format json health
edgeclaw schema

示例输出（health 关键字段）：

json

{
  "ok": true,
  "health": {
    "status": "ok",
    "version": "0.1.0",
    "mcp_configured": true
  }
}

2.4 版本确认

bash

edgeclaw --version
# 期望：0.1.0

2.5 网络与云平台

EdgeHub 与 JetLinks 默认指向 zhihongos.cn：

bash

param get persist.edge.cloud.base_url
# 期望：https://zhihongos.cn/edgehub 或相关云地址

板端需能访问：

https://zhihongos.cn/edgehub（Skill / Agent 下载）
https://zhihongos.cn/iot/api（JetLinks REST，可选）
zhihongos.cn:1883（JetLinks MQTT，可选）
LLM Provider API（如 DeepSeek，需在 model_factory.json 配置）

2.6 模型 API Key 配置

编辑 /system/etc/edgeclaw/model_factory.json（需 remount 后推送）：

json

{
  "providers": {
    "deepseek": {
      "api_key": "sk-你的密钥",
      "base_url": "https://api.deepseek.com/v1",
      "model": "deepseek-chat"
    }
  },
  "default_provider": "deepseek"
}

未配置有效 API Key 时，edgeclaw run / chat 可能失败，但 health、schema、mcp list 等不依赖 LLM 的命令仍可正常执行。

2.7 环境自检（可选）

在板端依次执行以下命令，确认三服务就绪：

bash

edgeclaw --format json health
edgeclaw --format json health --all
edgecomputer --format json service status
edgemcp health --format json

health --all 中 aggregate_ready=true 即表示 edgecomputer、edgemcp、edgeclaw 链路正常。

三、快速开始

目标：5 分钟内完成健康检查并跑通第一条对话。

以下流程约 5 分钟，对应评测用例 #3–#5、#22。

3.1 第一步：健康检查

bash

# 【板端】
edgeclaw --format json health

期望输出（实测）：

json

{
  "command": "health",
  "health": {
    "cron_running": false,
    "harness_dir": "/data/service/el1/public/edgeclaw",
    "mcp_configured": true,
    "status": "ok",
    "version": "0.1.0"
  },
  "ok": true
}

关键字段：

字段	期望	含义
`ok`	`true`	CLI 与服务通信正常
`health.status`	`ok`	服务自身健康
`health.version`	`0.1.0`	当前版本
`health.mcp_configured`	`true`	已加载 mcp_service.json

3.2 第二步：聚合依赖检查

bash

edgeclaw --format json health --all

期望输出关键字段（实测 pass）：

json

{
  "aggregate_ready": true,
  "edgecomputer": {
    "connected": true,
    "device_count": 3,
    "fallback_used": true,
    "ipc_ok": true
  },
  "edgemcp": {
    "bridge_connected": true,
    "mcp_listening": true,
    "mcp_port": 9720,
    "reachable": true,
    "tool_count": 5
  },
  "ok": true
}

字段	期望	说明
`aggregate_ready`	`true`	三服务链路就绪
`edgecomputer.ipc_ok`	`true`	EdgeComputer IPC 可达
`edgemcp.bridge_connected`	`true`	MCP 桥接已连接
`edgemcp.tool_count`	`5`	edge-device 五大工具已注册

若 aggregate_ready 为 false，请检查启动顺序（第二章）及第十二章常见问题。

3.3 第三步：单轮对话

bash

edgeclaw run "1+1等于几"

期望输出（实测）：

[status] Starting ReAct loop
1+1等于**2**。

如果还需要别的帮助，随时说。

run 为无状态单轮执行，不写入 sessions/，适合脚本与 CI 探活。

3.4 第四步：多轮对话

日常排查、IoT 问答需要记住上文时，用 chat 并指定会话名（-s）。同一 session_key 的多条消息会写入 sessions/，下一轮自动带上历史。

bash

# 第一轮：建立会话
edgeclaw chat -s quickstart -m "你好，你能做什么？"

# 第二轮：同一会话，模型记得上一轮内容
edgeclaw chat -s quickstart -m "请检查当前系统信息"

# 第三轮：追问上文（无需重复背景）
edgeclaw chat -s quickstart -m "把刚才的检查结果用三句话总结"

期望现象：

三条命令共用 -s quickstart，无需每次重述背景
第三轮应能引用第二轮的系统信息，而不是重新答「我不知道你指什么」
会话目录：/data/service/el1/public/edgeclaw/sessions/quickstart/

也可进入交互模式（不加 -m，在终端里连续输入，输入 exit 或 quit 退出）：

bash

edgeclaw chat -s quickstart

命令	会话	典型场景
`run "..."`	无	脚本探活、单次问答
`chat -s <key> -m "..."`	有	多轮追问、IoT 对话
`chat -s <key>`	有	终端里连续聊

3.5 第五步：查看能力目录

bash

edgeclaw --format json skill list
edgeclaw --format json agent list
edgeclaw --format json mcp tools edge-device

至此，你已完成 EdgeClaw 最小可用验证。

3.6 期望结果

检查项	命令	期望
CLI 版本	`edgeclaw --version`	`0.1.0`
服务健康	`health`	`ok: true`，`health.status: ok`
三服务聚合	`health --all`	`aggregate_ready: true`
单轮对话	`run "1+1等于几"`	有自然语言回复
多轮记忆	同 `-s` 连续 `chat`	能引用上一轮内容
MCP 工具	`mcp tools edge-device`	列出 5 个工具

任一检查失败，先回到第二章确认服务，再查第十二章。

四、对话控制设备

目标：用自然语言查询板端 IoT 子设备（需 EdgeComputer 已连云并加载插件，见 EdgeComputer 教程第三、四章）。

4.1 MCP 是什么？

MCP（Model Context Protocol）将外部能力封装为工具（Tool），LLM 通过 function calling 调用。EdgeClaw 作为 MCP Client，可连接多个 MCP Server。

4.2 mcp_service.json 配置与热更新

MCP 服务声明在 mcp_service.json 中。运行时生效路径（CLI 读写、服务加载）：

/data/service/el1/public/edgeclaw/mcp_service.json

出厂镜像也可能在 /system/etc/edgeclaw/mcp_service.json 提供默认模板；板端联调以 harness 数据目录 下文件为准。

json

{
  "servers": [
    {
      "name": "edge-device",
      "url": "http://edge-device-mcp.local:9720/mcp",
      "transport": "streamable_http",
      "timeout": 30
    },
    {
      "name": "12306-mcp",
      "url": "https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp",
      "transport": "streamable_http",
      "timeout": 30
    }
  ]
}

edge-device 的 url 保持与出厂配置一致即可；edge-device 为系统内置服务，不可删除。

推荐：用 CLI 管理 MCP（热更新，无需重启）

自 v0.1 起，修改 MCP 配置后可通过 热加载 立即生效，无需 service_control restart edgeclaw_service。mcp add / mcp remove 写盘后自动触发运行时重载；活跃 chat 会话的 system prompt 会同步更新 MCP 工具列表。

bash

# 添加外部 HTTP MCP（支持 --spec 传入 mcpServers JSON）
edgeclaw --format json mcp add \
  --spec '{"mcpServers":{"12306-mcp":{"type":"streamable_http","url":"https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp"}}}' \
  --force

# 或分开指定 name / url
edgeclaw --format json mcp add --name 12306-mcp \
  --url https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp --force

# 删除（edge-device 受保护，无法删除）
edgeclaw --format json mcp remove 12306-mcp

# 手动重载（直接编辑 mcp_service.json 后执行）
edgeclaw --format json mcp reload

mcp add / mcp remove 成功时返回示例字段：

字段	含义
`connected`	本次热加载后成功连上的服务名列表
`tool_count`	运行时连接池可见工具总数
`sessions_patched`	是否已 patch 正在推理的活跃会话 prompt
`warning`	如 `service offline, reload pending` 表示写盘成功但 harnessd 不可达，待服务恢复后执行 `mcp reload`

验证连接：

bash

edgeclaw --format json mcp list --runtime   # 文件配置 + 运行时连接状态
edgeclaw --format json mcp status edge-device
# 期望：connected=true, tool_count=5

人机可读表格输出（板端终端推荐）：

bash

edgeclaw --format table mcp list --runtime
edgeclaw --format table mcp status 12306-mcp
edgeclaw --format table mcp reload

仍须重启的场景

仅当 harnessd / edgeclaw_service 进程本身异常 或修改 settings.json、model_factory.json 等非 MCP 配置时，才需要 service_control restart edgeclaw_service。单纯增删 MCP Server 不必重启。

4.3 edge-device 五大工具

实测 edgeclaw --format json mcp tools edge-device 返回 5 个工具：

#	工具名	限定名	只读	功能
1	`list_devices`	`mcp__edge-device__list_devices`	✓	列出所有子设备
2	`get_device_properties`	`mcp__edge-device__get_device_properties`	✓	读取设备属性
3	`set_device_properties`	`mcp__edge-device__set_device_properties`	✗	写入设备属性
4	`invoke_device_function`	`mcp__edge-device__invoke_device_function`	✗	调用设备功能
5	`get_device_capabilities`	`mcp__edge-device__get_device_capabilities`	✓	查看物模型能力摘要

推荐调用顺序：

list_devices → get_device_capabilities → get/set/invoke

get_device_capabilities 返回属性 ID、中文名、类型、读写权限、枚举选项，是写操作前的必要步骤。

4.4 通过对话调用 MCP

上一节介绍了 edge-device 的 5 个工具名；本节说明如何在自然语言对话里触发它们。EdgeClaw 主智能体在 ReAct 循环中会根据你的描述，自动选择 MCP 工具并填入参数，你无需手写 JSON-RPC。

调用链路：

用户消息 → 主智能体推理 → function calling 选工具
  → EdgeClaw MCP Client → edgemcp:9720 → EdgeComputer → 设备插件

前置条件（缺一不可）：

检查项	命令	期望
三服务就绪	`edgeclaw --format json health --all`	`aggregate_ready=true`
MCP 已连接	`edgeclaw --format json mcp status edge-device`	`connected=true`, `tool_count=5`
子设备已注册	`edgecomputer devices`	至少有一条记录（如 `edge-linux-001`）

方式一：在消息里点名 MCP 工具（适合学习、复现）

LLM 调用时使用的限定名格式为 mcp__<服务名>__<工具名>，edge-device 服务对应前缀 mcp__edge-device__。在 -m 里写清楚工具名和参数，模型会按 function calling 规范发起调用。

bash

# 第一步：列出子设备（只读，最安全）
edgeclaw chat -s iot-demo -m \
  '请调用 mcp__edge-device__list_devices 列出所有子设备'

这条命令做什么：创建/复用会话 iot-demo，主智能体解析消息后调用 list_devices，返回 EdgeComputer 已注册的 device_id 列表。终端里除最终自然语言回答外，可能看到 [status] 类进度行，表示正在执行工具。

bash

# 第二步：读取指定设备的属性（需已知 device_id）
edgeclaw chat -s iot-demo -m \
  '请调用 mcp__edge-device__get_device_properties，device_id=edge-linux-001, property_ids=["cpu_usage","disk_usage"]'

这条命令做什么：在同一会话 iot-demo 里，根据上一步得到的 device_id 读取属性。property_ids 必须是物模型里存在的 ID；若不确定，可先让模型调用 get_device_capabilities 查看可用属性（见 7.3 推荐顺序）。

bash

# 第三步（可选）：多轮追问，无需重复 device_id
edgeclaw chat -s iot-demo -m '刚才那个设备的 load_avg 是多少？'

这条命令做什么：利用 sessions/iot-demo/ 里已保存的 transcript，模型记得上下文中的设备和前次查询结果，可能直接补调 get_device_properties 或引用已有数据。

方式二：用自然语言描述意图（适合日常使用）

不必背工具名，直接说你想做的事即可，主智能体会自行选择 list_devices → get_device_properties 等工具链：

bash

edgeclaw chat -s iot -m "列出所有子设备，并读取 edge-linux-001 的 CPU 和磁盘使用率"

与方式一的区别：你不需要写 mcp__edge-device__ 前缀；模型根据工具描述自动匹配。适合运维口语化提问，但排障时方式一更容易对照「哪一步工具调用失败」。

方式三：委派 edge_computer 子 Agent（适合端云联调）

内置子 Agent edge_computer 熟悉 JetLinks、edgecomputer 配置与 edge-device MCP，适合较长 IoT 任务：

bash

edgeclaw chat -s iot -m \
  "请委派 edge_computer 子智能体，列出所有子设备并读取 edge-linux-001 的 cpu_usage"

这条命令做什么：主智能体通过 agent 工具把任务交给 edge_computer，由子 Agent 在其 worker 线程里独立完成多步 MCP 调用，结果以 tool 消息合并回主会话。适合「查设备 + 解释云侧状态」一类复合问题。

方式	优点	适用
点名工具	步骤清晰，便于对照日志	学习、写教程、精确复现
自然语言	口语化，上手快	日常运维
委派子 Agent	多步推理、端云知识内置	IoT 全链路、复杂查询

写操作注意：set_device_properties、invoke_device_function 会改设备状态或触发功能，生产环境建议先在测试会话里用 get_device_capabilities 确认属性 ID 与权限，并留意 settings.json 中的 permission_mode。

4.5 使用 edgemcp 直接调试

edgemcp 是 EdgeMCP 服务的板端 CLI（EdgeMCP）。当对话里 MCP 行为异常时，用它可以绕过 EdgeClaw 和 LLM，直接在 MCP Server 层验证「工具能否调通、EdgeComputer 是否有数据」。

与 EdgeClaw 命令的分工：

命令	视角	作用
`edgeclaw mcp list --runtime`	EdgeClaw 客户端	看运行时连接池状态（推荐）
`edgeclaw mcp status`	EdgeClaw 客户端	CLI 独立 HTTP 探测 URL 可达性
`edgeclaw mcp reload`	EdgeClaw 客户端	热重载 mcp_service.json 到连接池
`edgeclaw mcp tools`	EdgeClaw 客户端	看工具列表与 schema
`edgemcp health`	EdgeMCP 服务端	看 9720 监听、桥接、工具注册
`edgemcp tools call`	EdgeMCP 服务端	直接执行一次 tools/call

edgemcp health — 服务自身是否就绪

bash

edgemcp health --format json

作用：一次性检查 MCP HTTP 是否在 9720 监听、能否完成 MCP 握手、与 EdgeComputer 的 IPC 桥是否连通、5 个工具是否已注册。不经过 EdgeClaw，是排障链路的第二层（第一层是 edgeclaw health --all）。

字段	含义	异常时可能原因
`reachable`	TCP 9720 可达	`edgemcp` 未启动或端口被占
`mcp_listening`	MCP 协议 initialize 成功	配置错误或进程崩溃
`bridge_connected`	已连 EdgeComputer 且 list_devices 探活成功	`edgecomputer_service` 未起或 IPC 失败
`tool_count`	注册工具数	正常应为 5
`device_count`	子设备数量	为 0 时先加载 `linux_device` 等插件

edgemcp tools list — 查看服务端工具定义

bash

edgemcp tools list --format json

作用：等价于 MCP 协议的 tools/list，返回每个工具的 name、description、inputSchema。用于确认参数名（如 device_id、property_ids）是否与文档一致，编写 tools call 时不至于传错字段。

edgemcp tools call — 直接调用单个工具

bash

# 列出子设备（无参数）
edgemcp tools call list_devices --format json

# 读取属性（复杂参数用 --args 传 JSON）
edgemcp tools call get_device_properties \
  --device-id edge-linux-001 \
  --args '{"property_ids":["cpu_usage","disk_usage","load_avg"]}' \
  --format json

作用：等价于 MCP 的 tools/call，在板端直接拿到 JSON 结果。若这里成功而 edgeclaw chat 失败，问题多半在 EdgeClaw 侧（mcp_service.json、LLM、会话配置）；若这里也失败，应查 EdgeComputer 插件与设备注册。

建议调试顺序：

1. edgemcp health          → 服务与桥接是否正常
2. edgemcp tools call list_devices → 是否有子设备
3. edgemcp tools call get_device_properties → 单设备数据是否正常
4. edgeclaw mcp list --runtime  → 运行时连接池是否 connected
5. edgeclaw mcp reload          → 配置变更后同步连接池（若需要）
6. edgeclaw chat ...            → 全链路 + LLM 是否正常

若 edgemcp 正常 而 EdgeClaw mcp status 失败，检查 mcp_service.json 是否与出厂配置一致，并执行 edgeclaw mcp reload；仍失败时再 service_control restart edgeclaw_service。

4.6 EdgeClaw 侧：MCP CLI 命令

以下命令从 EdgeClaw 客户端 管理 MCP 配置与连接，回答「配置里写了哪些服务」「运行时连上了没有」「对面暴露了哪些工具」。

命令	作用	是否探测连通
`mcp list`	读取 `mcp_service.json` 中的服务列表	否
`mcp list --runtime`	列表 + harnessd 运行时连接状态	是（读连接池）
`mcp status <name>`	独立 HTTP 探测指定 MCP（CLI 侧）	是
`mcp tools <name>`	列出该 MCP 暴露的工具元数据	是
`mcp add`	写入配置并热加载	写盘后自动 reload
`mcp remove <name>`	删除配置并热加载（`edge-device` 不可删）	写盘后自动 reload
`mcp reload`	从磁盘重载配置到运行时连接池	是
`mcp install <spec>`	经 harnessd 安装（含 stdio 等形态）	安装后自动 reload

--format 支持 json（脚本默认）与 table（终端可读表格）。

mcp list / mcp list --runtime

bash

# 仅文件配置
edgeclaw --format json mcp list

# 含运行时 connection_state（推荐联调时使用）
edgeclaw --format table mcp list --runtime

--runtime 输出示例：edge-device 可能为 failed（edgemcp 未就绪），12306-mcp 为 connected。

mcp tools — 查看工具目录

bash

edgeclaw --format json mcp tools edge-device
edgeclaw --format table mcp tools 12306-mcp

作用：读取 MCP 服务注册的工具元数据，含限定名（如 mcp__edge-device__list_devices）、描述、inputSchema。对话前可先执行一次，确认工具齐全。

mcp status — 探测实时连接（CLI 独立探测）

bash

edgeclaw --format json mcp status edge-device

作用：CLI 直接向 mcp_service.json 里的 URL 发起 HTTP 握手探测，不经过 harnessd 连接池。适合确认 URL 可达；与 mcp list --runtime 对照可区分「配置写了但运行时未连上」与「URL 本身不可达」。

注意：chat 内实际调用走的是 harnessd 运行时连接池。若 mcp status 成功但 chat 报 MCP client not connected，应执行 edgeclaw mcp reload 或重新 mcp add，无需重启服务。

实测输出示例：

json

{
  "command": "mcp.status",
  "connected": true,
  "ok": true,
  "server_name": "edge-device",
  "tool_count": 5,
  "url": "http://edge-device-mcp.local:9720/mcp"
}

字段	含义	排障提示
`ok`	命令本身是否执行成功	`false` 时看 CLI 报错或服务是否在线
`connected`	MCP 握手是否成功	`false` 时对照 7.5 `edgemcp health`
`server_name`	配置中的服务名	须与 `mcp list` 里 `name` 一致
`tool_count`	客户端看到的工具数	应为 5；为 0 常表示连接未完成
`url`	实际连接的 MCP 地址	应与 `mcp_service.json` 中 `edge-device` 条目一致

4.7 分层健康检查与对照排障

IoT 链路跨三个服务，健康状态分散在不同命令里。本节说明每条健康命令查什么、何时用哪条。

edgeclaw health --all 中的 edgemcp 段

bash

edgeclaw --format json health --all

作用：从 EdgeClaw 进程内聚合探测 EdgeComputer + EdgeMCP，适合「一键看三服务是否联调就绪」。其中 edgemcp 对象与单独执行 edgemcp health 字段相近，但由 EdgeClaw 侧发起，可发现「edgemcp 本机正常、EdgeClaw 连不上」这类跨进程问题。

health --all 里 edgemcp 段实测示例：

json

{
  "bridge_connected": true,
  "device_count": 0,
  "mcp_endpoint": "/mcp",
  "mcp_host": "127.0.0.1",
  "mcp_listening": true,
  "mcp_port": 9720,
  "reachable": true,
  "service": "edgemcp",
  "tool_count": 5
}

字段	含义
`aggregate_ready`（顶层）	三服务整体是否就绪，联调 IoT 时看此项
`mcp_host` / `mcp_port`	EdgeMCP 服务端监听地址（本机 9720）
`mcp_endpoint`	HTTP 路径，一般为 `/mcp`
`device_count`	经桥接看到的子设备数；为 0 不一定是故障，可能尚未加载插件

三条健康命令对照

命令	检查范围	典型用途
`edgeclaw health --all`	EdgeClaw + EdgeComputer + EdgeMCP 聚合	每日开机探活、第三章快速开始
`edgeclaw mcp list --runtime`	EdgeClaw 运行时连接池状态	增删 MCP 后验证热加载
`edgeclaw mcp status edge-device`	CLI 独立 HTTP 探测	确认 URL 可达
`edgeclaw mcp reload`	重载 mcp_service.json 到连接池	手工改文件后执行
`edgemcp health`	EdgeMCP 服务 + 桥接 + 工具注册	对话失败时确认 MCP 层是否正常

常见现象速查

现象	优先检查	处理方向
`aggregate_ready=false`	`health --all` 各段哪一项为 false	按 EdgeComputer → EdgeMCP → EdgeClaw 顺序重启
`edgemcp health` 正常，`mcp status connected=false`	`mcp_service.json`、edgemcp	先 `mcp reload`；仍失败再 `service_control restart edgeclaw_service`
`mcp list --runtime` 已 connected，`chat` 报 not connected	运行时连接池未同步	`edgeclaw mcp reload`（无需重启）
`mcp status` 正常，`chat` 不调工具	LLM 配置、会话消息	检查 `model_factory.json`；改用 7.4 方式一点名工具
`tools call list_devices` 为空	EdgeComputer 插件	`edgecomputer plugin load linux_device` 等
`tool_count` 不是 5	edgemcp 初始化	重启 `edgemcp`与 `edgeclaw_service`

更完整的跨服务排障见第十二章。

五、从 EdgeHub 扩展能力

目标：在板端从 EdgeHub 市场安装一个 Skill 和一个子 Agent，并在对话中确认 catalog 已更新。

5.1 EdgeHub 是什么？

EdgeHub 是 Skill 与子 Agent 的在线市场（https://zhihongos.cn/edgehub）。板端通过 skillhub / agenthub 子命令搜索、下载、安装，无需手动 hdc file send tar 包。

5.2 查看 EdgeHub 地址（可选）

出厂镜像已预置 EdgeHub 市场地址，日常使用 skillhub / agenthub 搜索安装即可，无需关心地址写在哪个配置文件里。

若下载失败，或想确认当前指向哪台市场服务器，在板端执行：

bash

param get persist.edge.cloud.base_url

正常应返回类似 https://zhihongos.cn/edgehub 的 URL。该参数由系统在镜像或产线阶段写入，教程用户一般不需要也不建议自行改配置；排障时对照上述命令结果与网络连通性即可（见 5.6 节及第十二章）。

API 路径说明：Agent 市场走 /api/web/agents；Skill 搜索走 Web API。板端 edgeclaw agenthub 与 skillhub 已封装具体路径，用户无需手动拼接。

5.3 EdgeHub 网页界面操作图解

5.3.1 进入市场与搜索 Skill

打开首页，点击顶部 「技能搜索」，或直达 https://zhihongos.cn/edgehub/skills
在搜索框输入关键词（如 hello），回车或点搜索

技能搜索列表 — 卡片标题即 slug，右下角为最新版本

搜索 hello — 筛选出 skillhub-hello

从列表读取 Skill 标识：

页面位置	示例	用途
卡片标题（`h3`）	`skillhub-hello`	slug，用于 `skillhub install`
`@global` 旁命名空间	`global`	市场命名空间，安装时可写 `edgehub/skillhub-hello`
卡片右下角版本徽标	`v1.0`	`-v` 参数，如 `-v v1.0` 或 `-v 1.0.0`

点击卡片进入详情（URL 形如 /edgehub/space/global/skillhub-hello）。

5.3.2 Skill 详情：复制安装命令

详情页上半部分展示标题、canonical ID（可复制）与简介；向下滚动到 「安装」 面板。

Skill 详情页 — 标题与 canonical ID

Skill 标识区域 — 标题 slug 与 edgehub/ 前缀的 canonical ID

安装面板 — 可直接复制到板端执行

安装命令获取步骤：

在详情页找到 「安装」 标题下的灰色命令框

复制整行，实测示例：

bash

edgeclaw skillhub install edgehub/skillhub-hello -v v1.0

在板端 hdc shell 中粘贴执行

标识对照（以 skillhub-hello 为例）：

字段	页面位置	值	板端用法
slug	详情标题	`skillhub-hello`	`skillhub install skillhub-hello`
canonical ID	标题下方，带「复制」按钮	`edgehub/skillhub-hello`	`skillhub install edgehub/skillhub-hello`（推荐与网页一致）
版本	安装面板 / 右侧元数据	`v1.0`	`-v v1.0`
命名空间	左上角标签	`global`	CLI 自动解析，一般无需手写

两种 slug 写法等价：skillhub-hello 与 edgehub/skillhub-hello 指向同一包。

5.3.3 搜索与安装 Agent

点击顶部 「智能体搜索」，或直达 https://zhihongos.cn/edgehub/agents
搜索关键词（如 qa），点击目标卡片

智能体搜索列表 — 标题为运行时 name（下划线）

搜索 qa — 筛选出 qa_automation_enginer

从列表读取 Agent 标识：

页面位置	示例	用途
卡片标题	`qa_automation_enginer`	运行时 `name`，对话委派用这个
URL 路径最后一段	`qa-automation-enginer`	EdgeHub slug（连字符）
版本徽标	`v1.0`	`agenthub install ... -v v1.0`

详情页 URL 形如：/edgehub/agent/global/qa-automation-enginer。

5.3.4 Agent 详情：复制安装命令

Agent 详情页 — 含 AGENT 标签与概览

Agent 标识 — 运行时 name 与 canonical ID

Agent 安装面板

安装命令获取步骤：

滚动到 「安装」 面板

复制命令框内容，实测示例：

bash

edgeclaw agenthub install edgehub/qa_automation_enginer -v v1.0

板端执行后，用 edgeclaw agent list 确认 name 为 qa_automation_enginer

Agent 三种「名字」对照：

名称类型	示例	出现位置	何时使用
URL slug	`qa-automation-enginer`	浏览器地址栏	仅网页导航
canonical ID / 安装 slug	`edgehub/qa_automation_enginer`	详情页标题下、安装命令	`agenthub install`
运行时 name	`qa_automation_enginer`	列表卡片标题、`agent list`	对话委派、`agenthub list` 括号内

5.3.5 网页与板端 CLI 对照

操作	网页	板端等价命令
搜 Skill	技能搜索 + 关键词	`edgeclaw skillhub search hello`
装 Skill	复制安装面板命令	`edgeclaw skillhub install edgehub/skillhub-hello -v v1.0`
搜 Agent	智能体搜索 + 关键词	`edgeclaw agenthub search qa`
装 Agent	复制安装面板命令	`edgeclaw agenthub install edgehub/qa_automation_enginer -v v1.0`
确认 catalog	详情页「版本」「下载量」	`edgeclaw skill list` / `edgeclaw agent list`

无法打开网页时，板端 search 输出同样包含 slug 与版本提示（见 8.6.2 节）。

5.4 skillhub — 技能市场操作详解

skillhub 是 EdgeClaw 访问 EdgeHub Skill 市场的子命令组。它在 edgeclaw_service 进程内完成 HTTP 搜索、下载 zip、解压到 data/installed/，并热更新运行时 Skill catalog，一般无需重启服务，也无需 hdc file send 手动传包。

5.4.1 命令一览

edgeclaw skillhub
├── search <关键词> [--json]     # 在市场搜索 Skill
├── install <slug> [选项]        # 下载并安装
├── list [--agent <name>]        # 列出已通过 EdgeHub 安装的 Skill
└── delete <slug>                # 卸载（remove 同义）

子命令	作用	是否改磁盘	是否影响对话 catalog
`search`	按关键词查市场，获取 slug 与简介	否	否
`install`	下载指定版本并解压安装	是	是（热更新）
`list`	查看 EdgeHub 安装记录（lock 文件）	否	否
`delete`	删除已安装包及记录	是	是（热更新）

与 skill list 的区别：skillhub list 只列 EdgeHub 安装过的包；edgeclaw skill list 列 内置 + 全部已安装 的运行时 catalog，是对话路由的真实依据。安装后两者都应能看到新 Skill，但管理「从市场装了啥」用 skillhub list。

5.4.2 search — 搜索技能

作用：在 EdgeHub 上按关键词模糊匹配 Skill，返回 slug、简介及安装提示。安装前必须先 search（或从网页市场查到 slug），确认包名与版本存在。

bash

# 基础搜索（人类可读输出）
edgeclaw skillhub search hello

实测输出：

You can use "edgeclaw skillhub install [skill]" to install.
skillhub-hello — 用于演示 SkillHub 技能包结构的入门技能，帮助用户快速了解 SkillHub、CLI 命令、仓库链接和文档入口。

如何读输出：

首行提示安装命令格式：edgeclaw skillhub install <slug>
每行格式：slug — 描述
从上例得到：slug = skillhub-hello

bash

# 继续搜索其他关键词
edgeclaw skillhub search build
# 可找到 build-agent-cli 等

# 脚本/自动化用 JSON 输出
edgeclaw skillhub search hello --json

场景	命令	期望
正常命中	`search hello`	至少一行 `skillhub-hello — …`
无结果	`search xyznotexist`	提示未找到（无 install 行）

搜索不安装任何东西，可反复执行。网页市场 https://zhihongos.cn/edgehub 上看到的 slug 与板端 search 结果一致。

5.4.3 install — 安装技能

作用：按 slug 从 EdgeHub 下载指定版本，解压到板端目录，注册安装记录，并触发 catalog 热更新。

基本语法：

bash

edgeclaw skillhub install <slug> [-v <版本>] [--agent <子Agent名>]

参数	必填	说明
`<slug>`	是	市场包名，来自 `search` 或网页；支持 `namespace/slug`，安装时剥命名空间，落盘用短名
`-v <版本>`	推荐	如 `1.0.0`、`v1.0`；省略时可能装最新版（视市场而定）
`--agent <name>`	否	仅挂载到该子 Agent，不进入全局 catalog

示例 1：安装到全局（教程推荐）

bash

edgeclaw skillhub install skillhub-hello -v 1.0.0

实测输出：

Downloading: https://zhihongos.cn/edgehub/api/web/skills/global/skillhub-hello/versions/1.0.0/download
Installed: skillhub-hello -> /data/service/el1/public/edgeclaw/data/installed/skills/skillhub-hello

安装后目录：

.../data/installed/skills/skillhub-hello/
├── SKILL.md
├── scripts/          # 部分包带有
├── references/
└── .skillhub/        # EdgeHub 元数据

示例 2：安装到指定子 Agent（仅 devops_enginer 可见）

bash

edgeclaw skillhub install build-agent-cli --agent devops_enginer -v v1.0

落盘路径：.../data/installed/agent-skills/devops_enginer/skills/build-agent-cli/。

安装作用域	命令特征	谁能在对话里用到
全局（默认）	无 `--agent`	主智能体及所有子 Agent（除非 Skill 限制 `allowed_agents`）
绑定子 Agent	带 `--agent devops_enginer`	仅该子 Agent 被委派时

安装后验证（建议每次都做）：

bash

edgeclaw skillhub list                              # EdgeHub 安装记录
edgeclaw --format json skill list                   # 运行时 catalog
edgeclaw chat -s demo -m "你新增了哪些 skill？"      # 对话侧确认

版本参数注意：

正确：edgeclaw skillhub install skillhub-hello -v 1.0.0
错误：edgeclaw -v 1.0.0 skillhub install ...（-v 会被 CLI 当成 --version）

5.4.4 list — 列出已安装的 EdgeHub 技能

作用：读取本机 EdgeHub 安装 lock 记录，列出通过 skillhub 安装过的 Skill 及版本，不含镜像内置的 4 个全局 Skill。

bash

edgeclaw skillhub list

输出情况	含义
`No installed skills.`	从未用 skillhub 安装，或已全部卸载
`skillhub-hello 1.0.0`	已安装 slug 与版本

bash

# 只看某子 Agent 下安装的 Skill
edgeclaw skillhub list --agent devops_enginer

卸载前用 list 确认 slug；对话能力是否还在，以 skill list 为准。

5.4.5 delete — 卸载技能

作用：删除 data/installed/ 下对应目录及 EdgeHub 安装记录，并从 catalog 热移除。

bash

edgeclaw skillhub delete skillhub-hello
# remove 与 delete 同义
edgeclaw skillhub remove skillhub-hello

验证：

bash

edgeclaw skillhub list                    # 应不再出现该 slug
edgeclaw --format json skill list         # catalog 中应移除（内置 Skill 仍在）

卸载不会删除镜像内置 Skill（system-info 等），只影响 EdgeHub/本地安装包。

5.4.6 skillhub 典型工作流

bash

# 【板端】从零安装一个 Skill 并验证
edgeclaw skillhub search hello
edgeclaw skillhub install skillhub-hello -v 1.0.0
edgeclaw skillhub list
edgeclaw --format json skill list
edgeclaw chat -s hub-test -m "请使用新安装的 skillhub-hello 能力做个自我介绍"

# 不需要时卸载
edgeclaw skillhub delete skillhub-hello

5.5 agenthub — 子智能体市场操作详解

agenthub 与 skillhub 对称，面向 EdgeHub 上的子 Agent 包（含 agent.json、AGENT.md 及可选 skills/）。安装后落盘到 data/installed/agents/，主智能体可通过 agent 工具委派新子 Agent。

5.5.1 命令一览

edgeclaw agenthub
├── search <关键词> [--json]     # 搜索子 Agent
├── install <slug> [选项]        # 下载并安装
├── list                         # 列出已通过 EdgeHub 安装的 Agent
└── delete <slug>                # 卸载（remove 同义）

子命令	作用	与 skillhub 差异
`search`	查子 Agent，输出含 `[版本]` 与运行时 `(name)`	Agent 行多显示版本与 `agent.json` name
`install`	安装到 `data/installed/agents/<name>/`	支持 `--force` 覆盖；无 `--agent` 参数
`list`	EdgeHub 安装记录	显示 slug 与运行时 name
`delete`	卸载子 Agent	同 skillhub

与 agent list 的区别：agenthub list = 市场安装记录；agent list = 内置 + 已安装全部子 Agent。对话委派时用 agent list 里的 name（如 qa_automation_enginer），不是 slug。

5.5.2 search — 搜索子智能体

作用：在 EdgeHub Agent 市场按关键词搜索，返回 slug、版本、运行时 name 与能力描述。

bash

edgeclaw agenthub search qa

实测输出：

You can use "edgeclaw agenthub install [agent]" to install.
qa-automation-enginer  [v1.0]  (qa_automation_enginer) — 端侧自动化测试工程师：OpenHarmony/Android 端 UI 自动化驱动、用例批量生成与结构化测试报告产出。触发词含 UiTest、ArkUI 测试、自动化……

如何读输出：

片段	含义	安装/委派用哪个
`qa-automation-enginer`	EdgeHub slug	`agenthub install` 的参数
`[v1.0]`	市场版本	`install -v v1.0`
`(qa_automation_enginer)`	`agent.json` 的 name	对话里「委派 xxx 子智能体」

bash

edgeclaw agenthub search automation --json
edgeclaw agenthub search nonexistent-slug-xyz   # 期望：No agents found.

5.5.3 install — 安装子智能体

作用：下载 Agent 包，解压到 data/installed/agents/<name>/，更新 catalog，可选同步联邦目录。

基本语法：

bash

edgeclaw agenthub install <slug> [-v <版本>] [--force]

参数	说明
`<slug>`	来自 search，如 `qa-automation-enginer`
`-v <版本>`	如 `v1.0`，建议与 search 输出 `[v1.0]` 一致
`--force`	已存在同 slug 时强制覆盖安装

bash

edgeclaw agenthub install qa-automation-enginer -v v1.0 --force

实测输出：

Downloading: https://zhihongos.cn/edgehub/api/web/agents/global/qa-automation-enginer/versions/v1.0/download
Installed agent: qa_automation_enginer -> /data/service/el1/public/edgeclaw/data/installed/agents/qa_automation_enginer

注意输出里的 Installed agent: qa_automation_enginer（下划线）才是运行时目录与委派名。

安装后目录示例：

.../data/installed/agents/qa_automation_enginer/
├── agent.json
├── AGENT.md
└── skills/              # 部分 Agent 包自带专属 Skill

安装后验证：

bash

edgeclaw agenthub list
edgeclaw --format json agent list
edgeclaw chat -s qa-demo -m \
  "请委派 qa_automation_enginer 子智能体，说明你能做哪些自动化测试"

5.5.4 list — 列出已安装的 EdgeHub 子智能体

作用：查看本机通过 agenthub 安装过的 Agent 及版本，不含内置的 devops_enginer、edge_computer。

bash

edgeclaw agenthub list

期望示例：

qa-automation-enginer  (qa_automation_enginer)  v1.0

格式：slug (运行时name) 版本。未安装时提示无记录。

5.5.5 delete — 卸载子智能体

作用：删除安装目录与 EdgeHub 记录，从 catalog 移除，之后无法再委派该 Agent。

bash

edgeclaw agenthub delete qa-automation-enginer
edgeclaw agenthub remove qa-automation-enginer   # 同义

bash

edgeclaw agenthub list
edgeclaw --format json agent list    # 应只剩内置 Agent

5.5.6 slug 与运行时 name 对照

EdgeHub slug（install/delete 用）	agent.json `name`（委派用）	说明
`qa-automation-enginer`	`qa_automation_enginer`	连字符常转为下划线
`skillhub-hello`	N/A（这是 Skill）	Skill slug 一般不变

易错点：对 Agent 说「委派 qa-automation-enginer」可能失败，应说「委派 qa_automation_enginer」。

5.5.7 agenthub 典型工作流

bash

# 【板端】安装 QA 子 Agent 全流程
edgeclaw agenthub search qa
edgeclaw agenthub install qa-automation-enginer -v v1.0 --force
edgeclaw agenthub list
edgeclaw --format json agent list
edgeclaw chat -s qa -m "请委派 qa_automation_enginer，只回复 OK"

# 卸载
edgeclaw agenthub delete qa-automation-enginer

5.5.8 skillhub 与 agenthub 对照速查

维度	skillhub	agenthub
安装对象	Skill（`SKILL.md`）	子 Agent（`agent.json` + `AGENT.md`）
全局安装命令	`skillhub install <slug>`	`agenthub install <slug>`
专属挂载	`--agent devops_enginer`	无（Agent 自带 `skills/`）
运行时列表	`skill list`	`agent list`
市场安装记录	`skillhub list`	`agenthub list`
对话触发	主智能体按意图加载 Skill	主智能体 `agent` 工具委派
覆盖安装	先 delete 再 install	`--force`
落盘目录	`data/installed/skills/` 或 `agent-skills/`	`data/installed/agents/`

更完整的 Skill / Agent 概念与目录结构见第十章；CLI 子命令速查见第九章 9.11、9.12。

5.6 负向用例（预期行为）

已下架 Skill（评测用例 #23）

bash

edgeclaw skillhub install user-stagingadmin/skill-creator -v v1.0

实测：HTTP 400，提示 download 失败。该 slug 已下架，教程与脚本应改用 skillhub-hello。

空搜索结果（评测用例 #24）

bash

edgeclaw agenthub search nonexistent-slug-xyz
# 期望：No agents found.

5.7 安装后热更新验证

bash

SESSION=verify-demo

edgeclaw chat -s $SESSION -m "当前有哪些 skill 和 sub-agent？"
edgeclaw skillhub install skillhub-hello -v 1.0.0
edgeclaw agenthub install qa-automation-enginer -v v1.0 --force
edgeclaw chat -s $SESSION -m "catalog 有变化吗？"
edgeclaw --format json skill list
edgeclaw --format json agent list

安装成功后自动：重载 catalog → 刷新 prompt → pushCatalogNow() 同步联邦目录。

5.8 当前可用市场包（2026-09 实测）

类型	slug	版本	说明
Skill	`skillhub-hello`	1.0.0	入门演示
Skill	`build-agent-cli`	v1.0	Agent 友好 CLI 设计
Agent	`qa-automation-enginer`	v1.0	UI 自动化测试工程师

六、工作原理

EdgeClaw 不是孤立组件。在智鸿边缘 AI 栈里，它与 EdgeComputer、EdgeMCP 等组成一条闭环：

EdgeComputer：管设备、连云、跑插件（如系统监控、Modbus、edgeclaw_session）
EdgeMCP：把 EdgeComputer 里的物模型翻译成 MCP 工具，供大模型调用
EdgeClaw：理解自然语言，编排 Skill、子 Agent 和 MCP，完成对话与设备控制

下面先看清各组件位置，再拆开三条协作链路，最后说明对话在 EdgeClaw 内部如何流转。

6.1 五大组件一览

组件	职责	与 EdgeClaw 的关系
EdgeClaw	对话编排、Skill/Agent 调度、联邦	本教程主角
EdgeMCP	把子设备列表、属性、功能封装成 MCP 工具	强依赖：控设备走 EdgeMCP，不直连 EdgeComputer
EdgeComputer	JetLinks 网关、插件采集、设备状态	设备数据来源；`edgeclaw_session` 插件供云平台回调 EdgeClaw
Edge Engine	端侧 CV / 语音推理	可选，部分 Skill 可间接使用
EdgePipe	视觉流水线	可选，与 EdgeClaw 无直接耦合

6.2 EdgeComputer 与 EdgeMCP

6.2.1 分工

组件	做什么	不做什么
EdgeComputer	维护网关与子设备；插件采集属性并上报云平台；处理云平台下行写属性/调功能	不直接对接大模型，不实现 MCP 协议
EdgeMCP	订阅设备变更；把「设备列表、读属性、写属性、调功能」封装成 5 个 MCP 工具	不自己采 Modbus/CPU 数据，不连 JetLinks MQTT

可以记：EdgeComputer 管设备真身，EdgeMCP 是给大模型用的设备接口。

6.2.2 数据流（读一条属性）

这条链路不经过 EdgeClaw。板端单独调试设备读写时，走的就是 EdgeMCP → EdgeComputer → 插件。

6.3 EdgeClaw 与 EdgeMCP：自然语言如何控设备

6.3.1 分工

组件	角色
EdgeClaw	理解用户意图，决定调哪个 Skill、子 Agent 或 MCP 工具
EdgeMCP	只认 MCP 协议，把工具调用翻译成对 EdgeComputer 的读写

EdgeClaw 不会直接连 EdgeComputer，也不会自己发 MQTT。控设备一律走：

EdgeClaw → EdgeMCP（MCP）→ EdgeComputer → 插件/子设备

6.3.2 完整对话链路

6.3.3 与 edgeclaw_session 的区别

路径	谁发起	典型场景
EdgeClaw → EdgeMCP → EdgeComputer	板端用户对话	「列出所有子设备」「读取 CPU 使用率」
JetLinks → edgeclaw_session → EdgeClaw	云平台规则或人工	云端对某会话发消息、查会话数

两条路互补：MCP 路径是 EdgeClaw 主动控设备；edgeclaw_session 是云平台主动调 EdgeClaw 会话。

6.4 edgeclaw_session 插件：云平台如何与 EdgeClaw 对话

6.4.1 插件做什么

edgeclaw_session 是 EdgeComputer 的内置设备插件（与系统监控、Modbus 等同级）。它不做 MCP，而是：

在网关上注册一个虚拟子设备（物模型含创建会话、发消息等功能）
直接连接 EdgeClaw，把 JetLinks 下发的功能调用转成会话 API
把会话数、引擎就绪状态等属性经网关 MQTT 上报云平台

6.4.2 物模型功能映射（概念）

云平台功能	作用
`create_session` / `delete_session`	创建或删除会话
`list_sessions`	列举当前会话
`send_message` / `send_message_stream`	向会话发消息，同步或流式收回复
`get_history`	拉取历史消息
`stop_turn`	停止当前生成

云端 send_message 触发的对话，内部仍可能再经 EdgeMCP 去操作 IoT——与板端对话走的是同一套 EdgeClaw 引擎，只是入口从用户终端换成了云平台。

6.4.3 云端下行示意

6.4.4 使用约束

项目	说明
部署位置	仅网关或直连设备可加载；普通子设备节点上不能用
实例数	每个网关一个插件实例，可管理多个会话
依赖	EdgeClaw 须已就绪；仅 EdgeComputer 在线不够

6.5 三条协作链路对照

链路	入口	中间层	终点	一句话
A. 设备上云	插件采集	EdgeComputer	JetLinks	CPU、Modbus 等数据进云
B. AI 控设备	用户对话	EdgeMCP	EdgeComputer → 插件	自然语言读写 IoT
C. 云控 AI 会话	JetLinks 功能调用	edgeclaw_session 插件	EdgeClaw	云端发消息、收回复

6.6 EdgeClaw 核心能力

能力域	说明
对话编排	多轮会话，ReAct 推理循环
技能扩展	内置 + EdgeHub 在线安装 Skill
子智能体	主智能体可委派专职 Agent
MCP 工具	本地设备控制 + 可接外部 MCP 服务
联邦	多块设备间远程调用 Agent
健康探针	自身及 EdgeComputer、EdgeMCP 聚合检查

6.7 组件启动顺序

出厂镜像开机时由系统自动按序拉起，日常使用无需手动干预：

EdgeComputer  →  EdgeMCP  →  EdgeClaw

EdgeComputer 先就绪：加载插件，连接云平台（若已配置）
EdgeMCP 再就绪：连上 EdgeComputer，对外提供 MCP 工具
EdgeClaw 最后就绪：连接 EdgeMCP，加载 Skill/Agent 目录

若聚合健康检查未通过，常见原因是 EdgeMCP 尚未连上 EdgeComputer，或 EdgeClaw 尚未连上 EdgeMCP。排障见第十二章。

使用 edgeclaw_session 时，还需 EdgeClaw 在线；该插件直连 EdgeClaw，与 EdgeMCP 无关。

6.8 对话在 EdgeClaw 内部如何流转

以用户发起一轮多轮对话为例，内部大致经历以下阶段：

阶段 1：接入与会话

用户输入进入 EdgeClaw；若指定了会话名，则加载或创建对应会话，并把历史消息一并交给模型。

阶段 2：组装主智能体

EdgeClaw 在调用大模型前会：

选择对话模型
连接 EdgeMCP 等 MCP 服务，刷新可用工具列表
拼接系统提示：人格说明、Skill 目录、子 Agent 目录、工具说明、记忆片段
把本轮用户消息追加进上下文

此时运行的是 主智能体（Orchestrator），负责理解意图和调度。

阶段 3：ReAct 主循环

主智能体默认走 ReAct（推理 → 行动 → 观察）：

调大模型（附带工具列表）
  → 若需要调工具（Skill / 子 Agent / MCP）→ 执行并写回结果
  → 重复，直到给出最终自然语言答复

复杂任务可切换为「先规划步骤、再逐步执行」模式；规划失败时自动退回 ReAct。

阶段 4：委派子智能体（可选）

若任务适合专职角色（如运维诊断、自动化测试），主智能体会 委派子智能体：

在后台启动子智能体 worker
子智能体按自己的工具白名单和专属 Skill 独立推理
完成后把摘要返回主智能体
主智能体整合结果，再回复用户

用户通常只看到主智能体的最终答复，不直接感知子智能体内部过程。

阶段 5：输出

助手回复以流式或一次性方式返回；多轮会话下，本轮内容会写入会话历史，下次同会话自动带上文。

6.9 主智能体与子智能体

维度	主智能体	子智能体
触发	每轮对话默认入口	仅当主智能体委派时
能力范围	全局 Skill、全部子 Agent、MCP 工具	专属 Skill + 受限工具集
会话	绑定用户会话，持久化历史	单次任务，结果合并回主会话
典型职责	理解意图、拆任务、汇总答复	深度执行：查日志、专项分析等

主智能体也可以 不委派，直接调 MCP 或 Skill 完成任务。

6.10 执行路径优先级（Local-First）

主智能体选执行路径时，默认优先用本机能力：

本机 Skill → 本机子 Agent → 本机 MCP 工具 → 联邦远程 Agent

层级	适用场景
Skill	按 SKILL.md 工作流完成单项任务
子 Agent	需要专职角色深度处理
MCP 工具	读写信道设备、调用外部服务
联邦 Agent	跨板调用对端设备上的 Agent

6.11 ReAct 与规划模式

ReAct（默认）：每轮先推理要不要调工具，执行后把结果喂回模型，直到得出最终答案。

规划模式：先让模型列出步骤再逐步执行，适合步骤多、依赖关系复杂的任务；计划解析失败时自动退回 ReAct。

上下文过长时，EdgeClaw 会自动压缩历史，避免超出模型窗口。

七、功能一览

本章是速览，便于查服务、端口与核心能力。架构细节见第六章。

7.1 五大服务一览

组件	进程 / CLI	职责	与 EdgeClaw 关系
EdgeClaw	`edgeclaw_service` / `edgeclaw`	AI 编排、对话、联邦	本教程主角
EdgeMCP	`edgemcp`	物模型 → MCP Tool	强依赖：`edge-device` MCP 是控设备的唯一正规入口
EdgeComputer	`edgecomputer_service` / `edgecomputer`	JetLinks 网关、插件、设备状态	设备数据源；`edgeclaw_session` 插件反向连回 EdgeClaw
Edge Engine	`edge_engine_service` / `edgeengine`	端侧 CV / 语音推理	可选，Skill 可间接调用
EdgePipe	`edge_pipe_service` / `edgepipe`	视觉流水线	可选，与 EdgeClaw 无直接 IPC

7.6 EdgeClaw v0.1.0 核心能力

能力域	说明	典型入口
对话编排	ReAct 循环，多轮会话	`edgeclaw chat` / `run`
技能扩展	内置 + EdgeHub 安装 Skill	`skill list` / `skillhub install`
子智能体	专职 Agent 委派	`agent list` / `agenthub install`
MCP 工具	本地 edge-device + 外部 HTTP MCP	`mcp tools`
联邦	DSoftBus + A2A 跨设备调用	`federation invoke`
健康探针	自身 + 依赖聚合检查	`health --all`

7.7 服务依赖关系

出厂镜像开机时由系统自动按序拉起三服务，日常实验无需手动启动：

edgecomputer_service  →  edgemcp  →  edgeclaw_service
  EdgeComputer          EdgeMCP         EdgeClaw

EdgeComputer 先就绪：注册 IPC，加载插件，连 MQTT（若已配置）。
EdgeMCP 再就绪：Bridge 连上 EdgeComputer，在 9720 暴露 MCP。
EdgeClaw 最后就绪：读 mcp_service.json，连 edge-device-mcp.local:9720。

若 edgeclaw health --all 中 aggregate_ready=false，常见原因：

edgemcp.bridge_connected: false → EdgeMCP 未连上 EdgeComputer
EdgeComputer 正常但 MCP 不可用 → 配置错误或需重启服务（见第十二章）

若要用 edgeclaw_session，还需 edgeclaw_service 在线；插件通过 IPC 连接，与 EdgeMCP 无关。

7.8 进程与端口速查

进程	监听 / 通信	数据目录
`edgeclaw_service`	Unix Socket（harnessd）	`/data/service/el1/public/edgeclaw/`
`edgemcp`	`127.0.0.1:9720`（MCP HTTP）	`/data/service/el1/public/edgemcp/`
`edgecomputer_service`	gRPC/IPC Unix Socket	`/data/service/el1/public/edgecomputer/`

edgeclaw_session 插件与 EdgeClaw 之间没有独立端口，走系统 IPC。

八、JetLinks 端云联调

本章从 EdgeComputer 设备插件 的角度，说明如何把 EdgeClaw 纳入 JetLinks 端云体系。EdgeClaw 本身不连 MQTT；它通过插件采集的数据、MCP 桥接、以及 edgeclaw_session 会话桥，与云平台形成三条互补链路。

配套阅读：JetLinks 控制台建产品/实例、五步连云的详细参数见 edgecomputer.md 第三、七章。本章聚焦 EdgeClaw 联调时各插件扮演什么角色、如何逐步验收。

8.1 三条链路：插件在端云中的位置

链路	方向	关键插件 / 组件	EdgeClaw 角色
A. 数据上云	板端 → 云	`linux_device`、`modbus` 等采集插件	不直接参与；为链路 B 提供设备数据源
B. AI 控设备	用户/板端 → 设备	同上插件 + `edgemcp`	主智能体经 MCP 读写信道插件管理的子设备
C. 云控 AI	云 → 板端对话	`edgeclaw_session`	云平台发 `send_message`，EdgeClaw 在会话里推理，可能再走路径 B 控设备

记忆口诀：

linux_device 等插件 = 传感器和执行器在云上的「手脚」
edgemcp = EdgeClaw 操作这些手脚的「遥控器协议」
edgeclaw_session = 云平台远程按下 EdgeClaw「对话按钮」的「云侧入口」

8.2 联调涉及的插件一览

EdgeClaw 端云联调至少涉及以下插件（均运行在 edgecomputer_service 进程内）：

插件	类型	注册的 JetLinks 子设备	与 EdgeClaw 的关系
linux_device	数据采集	`edge-linux-001`（产品 `edge-linux-child`）	属性经 EdgeMCP 暴露给 `mcp__edge-device__*`；AI 可读 CPU、磁盘等
modbus	工业采集（可选）	`child-modbus-001` 等	同上，Modbus 点位变为 MCP 可读写属性
edgeclaw_session	会话桥接	虚拟设备（产品 `edgeclaw-session-child`）	直接 IPC 连 edgeclaw_service，物模型功能映射 `CreateSession` / `Chat` 等

bash

# 查看板端已编入的插件 .so
ls /system/lib64/edgecomputer/plugins/

# 查看当前已加载插件
edgecomputer plugin list --format json

插件	是否需手动 load	说明
`linux_device`	需要 `plugin load`	培训环境连云后必加载，才有 `edge-linux-001`
`modbus`	可选 `plugin load`	需要 Modbus 场景时加载
`edgeclaw_session`	多数镜像默认已启用	云侧调 EdgeClaw 依赖此插件；确认 `plugin list` 中有即可

8.3 物模型如何流到 EdgeClaw

插件把现场数据注册为 EdgeComputer 子设备后，同一份物模型会沿两条路被 EdgeClaw 使用：

linux_device 采集 cpu_usage
  → EdgeComputer 子设备 edge-linux-001
  → MQTT 上报 JetLinks（链路 A，云上看曲线）
  → edgemcp get_device_capabilities / get_device_properties（链路 B）
  → EdgeClaw chat 自然语言读取

因此 JetLinks 产品上的属性 ID（如 cpu_usage）应与插件 plugin status 输出一致；物模型定义越清晰，EdgeClaw 通过 MCP 控制越准确（详见 edgecomputer.md 5.5 节）。

8.4 阶段 0：JetLinks 云平台准备

在板端操作前，先在 JetLinks 网页建好「户口」。浏览器打开 https://zhihongos.cn/iot（账号 admin / 密码 zhihongos）。

步骤	操作	本教程示例
1	创建网关产品	`edge-gateway`
2	创建网关实例，记录 `secure_id` / `secure_key`	`edge-gw-001`
3	创建子设备产品（Linux 监控）	`edge-linux-child`，物模型含 `cpu_usage`、`disk_usage` 等
4	创建子设备实例，父设备选网关	`edge-linux-001`
5（云控 AI）	创建 EdgeClaw 会话产品（若控制台已预置可跳过）	`edgeclaw-session-child`，含 `create_session`、`send_message` 等功能

控制台截图与字段对照见 edgecomputer.md 第四章。抄下网关凭证后进入板端配置。

8.5 阶段 1：板端连云（插件生效的前提）

插件上报与 edgeclaw_session 功能调用，都依赖网关 MQTT 已连接。在板端 hdc shell 内执行：

bash

# 1. 云平台地址
edgecomputer cloud set --host zhihongos.cn --port 1883 \
  --api-base https://zhihongos.cn/iot/api --api-user admin --api-password zhihongos

# 2. 网关身份（与 JetLinks 实例一致）
edgecomputer gateway set --product-id edge-gateway --device-id edge-gw-001 \
  --secure-id edge-secure-id --secure-key edge-secure-key-2026

# 3. 默认子设备身份（linux_device 插件会使用）
edgecomputer child set --product-id edge-linux-child --device-id edge-linux-001 \
  --device-name 'OHOS边缘节点'

# 4. 生效并重连 MQTT
edgecomputer config apply

# 5. 验收
edgecomputer cloud test --format json
edgecomputer service status --format json
# 期望：connected=true

此时尚未有业务数据：MQTT 通了，但还没加载采集插件，JetLinks 上看不到 cpu_usage 刷新。

8.6 阶段 2：加载数据插件（链路 A）

8.6.1 加载 linux_device

作用：插件在板端读 /proc、系统指标，按周期写入子设备 edge-linux-001，经网关 MQTT 推到 JetLinks。

bash

edgecomputer plugin load linux_device --format json
# 期望："loaded": true

edgecomputer plugin status linux_device --format json
# 查看物模型属性 ID 与采集周期

edgecomputer device list --format json
edgecomputer device get --device-id edge-linux-001 --format json

板端验收（插件层）：

检查项	命令	期望
插件已加载	`plugin list`	含 `linux_device`
子设备已注册	`device list`	含 `edge-linux-001`
属性有值	`device get --device-id edge-linux-001`	`cpu_usage`、`disk_usage` 等为数值

云端验收（链路 A）：

JetLinks → 设备管理 → edge-linux-001
属性页 cpu_usage 等每约 15 秒刷新

可选手动写一条属性，对照网页是否更新：

bash

edgecomputer device property set edge-linux-001 --key cpu_usage --value 45.2

8.6.2 可选：加载 modbus 插件

bash

edgecomputer plugin load modbus --format json
edgecomputer device get --device-id child-modbus-001 --format json

多一个子设备实例，链路 A/B 的 MCP 工具 list_devices 中也会多出该设备。

8.7 阶段 3：确认 EdgeClaw 三服务就绪（链路 B 前提）

AI 读控插件设备前，EdgeClaw + EdgeMCP + EdgeComputer IPC 必须就绪。三服务随系统启动，直接探活即可：

bash

edgeclaw --format json health --all

字段	期望	含义
`aggregate_ready`	`true`	三服务链路 OK
`edgecomputer.device_count`	≥ 1	插件已注册子设备
`edgemcp.tool_count`	`5`	MCP 工具齐全

再确认 MCP 客户端侧：

bash

edgeclaw --format json mcp status edge-device
# connected=true, tool_count=5

8.8 阶段 4：EdgeClaw 通过 MCP 读控插件设备（链路 B）

此链路不经过 JetLinks 下行，是板端用户（或云端会话内的 EdgeClaw）通过 MCP 操作 10.6 节插件注册的同批子设备。

bash

# 方式 1：委派 edge_computer 子 Agent（推荐，熟悉端云配置）
edgeclaw chat -s iot -m \
  "请委派 edge_computer 子智能体，检查网关是否已连接云平台，并列出所有子设备"

# 方式 2：直接读属性（依赖 linux_device 已上报过的 device_id）
edgeclaw chat -s iot -m \
  "读取 edge-linux-001 的 cpu_usage 和 disk_usage"

# 方式 3：edgemcp 直调（绕过 LLM，确认插件数据可达 MCP 层）
edgemcp tools call list_devices --format json
edgemcp tools call get_device_properties \
  --device-id edge-linux-001 \
  --args '{"property_ids":["cpu_usage","disk_usage"]}' \
  --format json

链路 B 验收逻辑：

edgemcp tools call 成功
  → 插件 → EdgeComputer 数据正常
edgeclaw chat 能读出与 device get 一致的数值
  → EdgeClaw + MCP + 插件 全通
JetLinks 网页曲线与 chat 读出值大致一致
  → 链路 A 与 B 数据同源

写操作（set_device_properties、invoke_device_function）前，先让模型调用 get_device_capabilities 确认物模型（见 4.3、4.4 节）。

8.9 阶段 5：云平台经 edgeclaw_session 调 EdgeClaw（链路 C）

8.9.1 插件做什么

edgeclaw_session 在网关上注册虚拟子设备，把 JetLinks 物模型功能 转成 EdgeClaw IPC 会话 API：

云平台功能 ID	EdgeClaw API	用途
`create_session`	`CreateSession`	创建会话，指定 `session_key`
`send_message`	`Chat`	同步发消息，拿完整回复
`send_message_stream`	`ChatStream`	流式回复，经事件上报
`list_sessions`	`ListSessions`	列举会话
`get_history`	`GetHistory`	查历史
`delete_session`	`DeleteSession`	删除会话

上报属性包括 session_count、engine_ready 等，云上看得到 EdgeClaw 是否就绪。

云端 send_message 里若问「当前 CPU 使用率」，EdgeClaw 在会话内仍会走路径 B 调 MCP，入口从板端 CLI 换成了物模型插件。

8.9.2 板端准备

bash

# 1. 确认三服务已启动（10.7 节）
edgeclaw --format json health

# 2. 确认 edgeclaw_session 插件
edgecomputer plugin list --format json | grep edgeclaw_session
# 若无，则加载：
edgecomputer plugin load edgeclaw_session --format json

# 3. 查看虚拟设备与物模型能力
edgecomputer device list --format json
edgecomputer plugin status edgeclaw_session --format json

插件通过 libedgeclaw_client 连接 edgeclaw_service，不经过 EdgeMCP 端口。edgeclaw_service 必须先于或随插件可用；仅 EdgeComputer 在线不够。

8.9.3 云平台侧操作示例

在 JetLinks 控制台找到 edgeclaw-session 相关子设备（产品 edgeclaw-session-child，具体 device_id 以 device list 为准），在功能页调试：

顺序	功能	典型入参	期望
1	`create_session`	`session_key=cloud-ops`	返回成功，板端 `sessions/cloud-ops/` 出现
2	`send_message`	`session_key=cloud-ops`, `message=列出所有子设备并读 edge-linux-001 的 cpu_usage`	返回含设备列表与 CPU 的文本
3	`list_sessions`	—	含 `cloud-ops`
4	`get_history`	`session_key=cloud-ops`	含上述问答记录

也可在 JetLinks 规则引擎 / 场景联动 中调用上述功能，实现「告警触发 → 云侧自动问 EdgeClaw」。

8.9.4 板端对照验证

云侧 send_message 执行后，板端可交叉确认：

bash

# EdgeClaw 会话目录
ls /data/service/el1/public/edgeclaw/sessions/

# 与 CLI 创建的会话行为一致
edgeclaw chat -s cloud-ops -m "刚才云端问题的补充：disk_usage 是多少？"

8.10 端到端联调检查清单

按插件视角自测，建议打勾顺序如下：

#	阶段	操作	通过标准
1	云准备	JetLinks 建网关/子设备/会话产品	实例与凭证齐全
2	连云	`cloud set` → `config apply`	`service status` → `connected=true`
3	链路 A	`plugin load linux_device`	云上看 `edge-linux-001` 属性刷新
4	三服务	启动 edgecomputer / edgemcp / edgeclaw	`health --all` → `aggregate_ready=true`
5	链路 B	`edgemcp tools call` + `edgeclaw chat`	能列出/读取插件子设备属性
6	链路 C	确认 `edgeclaw_session` + 云侧 `send_message`	云端收到 AI 回复，板端有对应 session
7	闭环	云侧让 AI「读 CPU」	回复值与 JetLinks 属性页一致

一键聚合探活：

bash

edgeclaw --format json health --all

字段	期望
`aggregate_ready`	`true`
`edgecomputer.connected`	`true`
`edgecomputer.device_count`	≥ 1（含插件子设备）
`edgemcp.tool_count`	`5`

8.11 常见问题（插件视角）

现象	可能原因	处理
云上无 `cpu_usage`	未 `plugin load linux_device`	加载插件并 `device get` 确认
`device_count=0` 但 MQTT 在线	插件未加载或未注册子设备	`plugin list` + `plugin load`
`chat` 读不到设备	链路 B 未通	先 `edgemcp tools call list_devices`
云侧 `send_message` 失败	`edgeclaw_session` 未加载或 EdgeClaw 未起	`plugin load edgeclaw_session`；确认 edgeclaw_service 状态
`engine_ready=false`	EdgeClaw 服务异常	`edgeclaw health`；重启 `edgeclaw_service`
云读 CPU 与网页不一致	采集周期延迟或问了不同 device_id	对照 `device list` 与 `get_device_capabilities`
MCP 正常但云侧无回复	仅 EdgeMCP 通，插件 IPC 不通	查 `edgeclaw_session` 日志与 edgeclaw_service

日志路径：

组件	路径
EdgeComputer / 插件	`/data/service/el1/public/edgecomputer/edgecomputer.log`
EdgeClaw	`/data/service/el1/public/edgeclaw/data/logs/edgeclaw.log`
EdgeMCP	`/data/service/el1/public/edgemcp/edgemcp.log`

更完整的连云与物模型说明见 edgecomputer.md；MCP 排障见本章前文第四章与第十二章。

九、命令手册

edgeclaw 是板端统一入口，通过 Unix Socket 连接 edgeclaw_service（edgeclaw_service）内置的 harnessd IPC。多数子命令需要服务已启动；schema、--version 等可在离线时单独使用。

格式约定：全局选项写在子命令前面。

bash

edgeclaw --format json <子命令> [子命令选项]
# ✅ 正确
edgeclaw --format json health

# ❌ 错误（--format 不会被 health 识别）
edgeclaw health --format json

脚本与自动化优先使用 --format json，便于 python3 -c "import json,sys; ..." 解析。

9.1 全局选项

选项	说明	典型场景
`--format json`	结构化 JSON 输出，`ok` 字段表示命令是否成功	脚本探活、CI、与 `jq` 配合
`--format table`	人类可读的表格（部分命令支持）	交互式终端快速浏览
`--format ndjson`	每行一条 JSON（流式命令）	对接日志管道
`--yes` / `--no-interactive`	跳过「是否确认执行」类提示	无人值守安装、批量运维
`--quiet`	减少 stderr 日志	只关心 stdout 结果时
`--verbose`	输出更详细的调试日志	排障时对照 harnessd 行为
`--harness-dir <path>`	指定 harness 数据根目录（默认 `/data/service/el1/public/edgeclaw`）	多实例调试、临时目录验证
`-h` / `--help`	打印帮助	忘记子命令参数时
`--version`	显示 CLI 版本（当前 0.1.0）	确认刷机镜像版本

9.2 命令总览

edgeclaw
├── --version                      # 查看 CLI 版本
├── schema [command_path]          # 命令自省（无需连接服务）
├── config
│   └── show                       # 读取运行时配置摘要
├── health [--all]                 # 健康检查（--all 含依赖聚合）
├── run <message>                  # 单轮无状态对话
├── chat -s <session> [-m <msg>]   # 多轮有状态对话
├── skill
│   ├── install <path>             # 从本地 tar/目录安装 Skill
│   └── list                       # 列出内置 + 已安装 Skill（运行时 catalog）
├── agent
│   ├── install <path>             # 从本地 tar/目录安装子 Agent
│   └── list                       # 列出内置 + 已安装子 Agent
├── mcp
│   ├── add [--name] [--url] [--spec] [--force]   # 添加 MCP 并热加载
│   ├── remove <name>                             # 删除 MCP 并热加载（edge-device 不可删）
│   ├── reload                                    # 从 mcp_service.json 热重载连接池
│   ├── install <spec>                            # 经 harnessd 安装（stdio / JSON 等）
│   ├── list [--runtime]                          # 列出配置；--runtime 含连接状态
│   ├── status <name>                             # CLI 侧 HTTP 探测连通性与工具数
│   └── tools <name>                              # 列出该 MCP 暴露的工具
├── memory
│   └── consolidate                # 整理会话记忆，压缩长期上下文
├── skillhub                       # EdgeHub 技能市场（搜索 / 安装 / 卸载）
├── agenthub                       # EdgeHub 子智能体市场
└── federation                     # 跨设备联邦（SoftBus + A2A）

下表按使用频率归类，便于查阅：

类别	命令	一句话说明
探活	`health` / `health --all`	确认 EdgeClaw 自身及 EdgeComputer、EdgeMCP 链路是否就绪
对话	`run` / `chat`	与 LLM 交互；`run` 无会话，`chat` 带 `session_key` 持久化历史
能力目录	`skill list` / `agent list`	查看主智能体与子智能体当前可见的全部 Skill / Agent
设备控制	`mcp list` / `mcp add` / `mcp reload` / `mcp status` / `mcp tools`	管理 MCP 配置与连接；edge-device 提供 5 个 IoT 工具
在线扩展	`skillhub` / `agenthub`	从 EdgeHub 搜索、下载、安装 Skill 与子 Agent
跨板协作	`federation`	双板组网后远程调用对端 Agent
运维	`config show` / `schema` / `memory consolidate`	查配置、查命令参数、整理长期记忆

9.3 health — 健康检查

检查 EdgeClaw 服务是否在线、配置是否加载成功。不调用 LLM，适合作为脚本第一步探活。

bash

# 仅 EdgeClaw 自身
edgeclaw --format json health

# 聚合 EdgeComputer + EdgeMCP（联调 IoT / MCP 时推荐）
edgeclaw --format json health --all

health（无 --all）关键字段：

字段	期望	含义
`ok`	`true`	CLI 与 harnessd IPC 通信正常
`health.status`	`ok`	引擎进程健康
`health.version`	`0.1.0`	当前 EdgeClaw 版本
`health.mcp_configured`	`true`	已加载 harness 目录下 `mcp_service.json`
`health.harness_dir`	数据根路径	会话、Skill、日志所在目录

health --all 额外字段：

字段	期望	含义
`aggregate_ready`	`true`	三服务（EdgeClaw + EdgeComputer + EdgeMCP）链路整体就绪
`edgecomputer.ipc_ok`	`true`	能连上 edgecomputer_service
`edgecomputer.device_count`	≥ 1	已注册子设备数量（视插件加载情况而定）
`edgemcp.mcp_listening`	`true`	EdgeMCP 在 9720 端口监听 MCP HTTP
`edgemcp.bridge_connected`	`true`	MCP 桥已连上 EdgeComputer
`edgemcp.tool_count`	`5`	edge-device 五大工具已注册

aggregate_ready 为 false 时，先按第二章检查服务启动顺序，再查第十二章常见问题。

9.4 config show — 配置摘要

读取 EdgeClaw 当前生效的运行时配置（来自 settings.json 与服务内默认值），不修改磁盘文件。

bash

edgeclaw --format json config show

实测输出示例：

json

{
  "command": "config.show",
  "config": {
    "agent_mode": "react",
    "compact_enabled": true,
    "harness_dir": "/data/service/el1/public/edgeclaw",
    "max_turns": 16,
    "permission_mode": "default",
    "worker_agent_mode": "plan_and_executor"
  },
  "ok": true
}

字段	含义
`agent_mode`	主智能体推理模式，默认 `react`（Reasoning + Acting 循环）
`worker_agent_mode`	子智能体 worker 模式，如 `plan_and_executor`
`max_turns`	单轮对话最多 ReAct 迭代次数，防止死循环
`compact_enabled`	是否启用上下文压缩
`permission_mode`	工具调用权限：`default` 写操作需确认，`full_auto` 自动批准
`harness_dir`	数据根目录，会话在 `sessions/`，Skill 在 `skills/`

修改配置需编辑 /system/etc/edgeclaw/settings.json 后 service_control restart edgeclaw_service。完整配置样例见附录 E。

9.5 schema — 命令自省

在不连接服务或编写自动化脚本前，查询 CLI 支持的子命令、参数类型及是否依赖 harnessd。

bash

# 列出全部顶层命令
edgeclaw schema

# 查看某一命令的参数定义
edgeclaw schema health
edgeclaw schema mcp.tools
edgeclaw schema federation.invoke

返回 JSON Schema 风格元数据，常见字段：

字段	含义
`name`	子命令路径，如 `mcp.tools`
`needs_harnessd`	`true` 表示必须 `edgeclaw_service` 在线
`parameters`	参数名、类型、是否必填

适合在 CI 里做「命令是否存在」的静态检查，或在升级镜像后对比 schema 是否变化。

9.6 run 与 chat — 对话命令

两类命令都会走 ReAct 主智能体，但会话持久化行为不同。

命令	会话	历史存储	适用场景
`run "<消息>"`	无	不写入 `sessions/`	脚本探活、单次问答、CI
`chat -s <key> -m "<消息>"`	有	写入 `sessions/<key>/`	多轮追问、IoT 对话、运维会话
`chat -s <key>`	有	同上	终端交互模式，连续输入，`exit` 退出

bash

# 单轮无状态（3.3 节）
edgeclaw run "1+1等于几"

# 单轮有会话（带上下文，但只发一条）
edgeclaw chat -s main -m "你好，请介绍一下你自己"

# 多轮：同一 -s 共享历史（3.4 节）
edgeclaw chat -s main -m "请检查当前系统信息"
edgeclaw chat -s main -m "把刚才的结果总结成三句话"

# 交互模式
edgeclaw chat -s main

参数说明：

参数	必填	说明
`-s <session_key>`	`chat` 必填	会话标识，字母数字与 `-` `_` 均可；同 key 复用 transcript
`-m "<message>"`	可选	单条用户消息；省略则进入交互模式

执行过程中终端可能出现 [status] Starting ReAct loop，表示进入推理循环。若需调用 MCP 或委派子 Agent，直接在自然语言中描述即可（详见第七、八章）。

依赖：run / chat 需要 model_factory.json 中配置有效的 LLM Provider；未配置时 health 仍可通过，但对话会失败。

9.7 skill — 本地 Skill 管理

Skill 是带 SKILL.md 的可复用能力包，主智能体按文档说明执行脚本或调用工具。

skill list

列出运行时 catalog：内置 Skill + 本地/EdgeHub 已安装 Skill。对话路由以这里为准，而非 skillhub list。

bash

edgeclaw --format json skill list

v0.1.0 内置 4 个：ohos-bundle、system-info、system-ops、web-search（详见 10.5 节）。

skill install

从本地 tar.gz 包或解压后的目录安装，无需联网。

bash

# 安装到全局（所有 Agent 可见）
edgeclaw skill install /data/local/tmp/my-skill.tar.gz

# 仅挂载到指定子 Agent
edgeclaw skill install /path/to/skill --agent devops_enginer

安装后目录示例：.../data/installed/skills/<name>/，含 SKILL.md、脚本与参考文档。与 skillhub install 的区别：后者从 EdgeHub 下载，前者走本地路径。

9.8 agent — 子 Agent 管理

子 Agent 是独立配置的专职智能体，主智能体通过 agent 工具委派任务。

agent list

bash

edgeclaw --format json agent list

返回内置 + 已安装子 Agent，含 name、skill_count、描述等。对话中委派时使用 agent.json 里的 name（如 devops_enginer），不是 EdgeHub slug。

v0.1.0 内置：devops_enginer（运维诊断）、edge_computer（端云 / MCP）。

agent install

bash

edgeclaw agent install /data/local/tmp/qa-agent.tar.gz

解压到 .../data/installed/agents/<name>/，包含 AGENT.md 与 agent.json。在线安装请用 agenthub install（见 5.5 节）。

9.9 mcp — MCP 连接管理

EdgeClaw 作为 MCP Client，按 mcp_service.json 连接各 MCP Server。LLM 通过 function calling 调用 MCP 暴露的工具。

配置路径：/data/service/el1/public/edgeclaw/mcp_service.json

热更新：mcp add / mcp remove / mcp install 写盘后会自动触发运行时重载（mcp.reload IPC），更新连接池与活跃会话 prompt，无需 service_control restart edgeclaw_service。手工编辑 JSON 后执行 edgeclaw mcp reload。

mcp list

读取配置文件，列出已声明的 MCP 服务。

bash

edgeclaw --format json mcp list
edgeclaw --format table mcp list --runtime   # 含运行时 connection_state

选项	说明
`--runtime`	从 harnessd 连接池读取各服务 `connection_state`（`connected` / `failed` / `dormant` 等）

--runtime 实测返回示例：

json

{
  "servers": [
    {
      "name": "edge-device",
      "url": "http://edge-device-mcp.local:9720/mcp",
      "transport": "streamable_http",
      "timeout": 30,
      "source": "runtime",
      "connection_state": "failed"
    },
    {
      "name": "12306-mcp",
      "url": "https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp",
      "transport": "streamable_http",
      "timeout": 30,
      "source": "runtime",
      "connection_state": "connected"
    }
  ],
  "total": 2
}

mcp add

向 mcp_service.json 添加 HTTP MCP 服务，写盘后自动热加载。

bash

# 方式一：--spec 传入 mcpServers 或单条 JSON
edgeclaw --format json mcp add \
  --spec '{"mcpServers":{"12306-mcp":{"type":"streamable_http","url":"https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp"}}}' \
  --force

# 方式二：--name + --url
edgeclaw --format json mcp add --name 12306-mcp \
  --url https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp --force

# 预览（不写盘）
edgeclaw --format table mcp add --name demo --url https://example.com/mcp --dry-run

选项	说明
`--name`	服务名（与 `--spec` 二选一组合）
`--url`	MCP HTTP 端点
`--transport`	默认 `streamable_http`
`--timeout`	秒，默认 30
`--spec`	JSON 字符串或 `mcpServers` 对象
`--force`	同名服务已存在时覆盖
`--dry-run`	仅预览，不写盘、不 reload

成功时除 server_name、url 外，还返回 connected、tool_count、sessions_patched 等热加载结果。

mcp remove

从配置删除 MCP 服务（edge-device 受保护，不可删除），写盘后自动热加载。

bash

edgeclaw --format json mcp remove 12306-mcp
edgeclaw --format table mcp remove 12306-mcp --dry-run

mcp reload

从磁盘重新加载 mcp_service.json 到 harnessd 运行时连接池。适用于手工编辑配置文件、或 mcp add 时 harnessd 离线导致 reload pending 的场景。

bash

edgeclaw --format json mcp reload
edgeclaw --format table mcp reload

返回示例：

json

{
  "ok": true,
  "command": "mcp.reload",
  "added": ["12306-mcp"],
  "removed": [],
  "updated": [],
  "connected": ["12306-mcp"],
  "failed": [],
  "tool_count": 8,
  "sessions_patched": true,
  "sessions_notified": 2
}

mcp status

CLI 独立 HTTP 探测指定 MCP 的连通性与工具数量（不经过 harnessd 连接池）。

bash

edgeclaw --format json mcp status edge-device
edgeclaw --format table mcp status 12306-mcp

字段	期望	含义
`connected`	`true`	URL 握手成功
`tool_count`	`5`（edge-device）	可见工具数
`error`	空	连接失败时的错误信息

mcp tools

列出某 MCP 下全部工具名、描述及 inputSchema。

bash

edgeclaw --format json mcp tools edge-device
edgeclaw --format table mcp tools 12306-mcp

mcp install

经 harnessd 安装 MCP（支持 stdio、JSON 文件、HTTPS URL 等形态），安装成功后自动热加载。

bash

edgeclaw mcp install 'stdio:/system/bin/my-mcp-server --port 9000'
edgeclaw --format json mcp install \
  --spec '{"mcpServers":{"12306-mcp":{"type":"streamable_http","url":"https://..."}}}' \
  --force

HTTP 类 MCP 也可直接用 mcp add；edge-device 由系统镜像预置，一般无需手动 install。

输出格式

`--format`	适用场景
`json`	脚本、自动化（默认）
`table`	板端终端人工查看（`mcp list` / `status` / `tools` / `reload` 等均已支持）
`auto`	TTY 下倾向 table，管道下倾向 json

9.10 memory — 记忆整理

长会话会积累大量 transcript，占用 token。memory consolidate 将 sessions/ 与 memory/ 中的上下文摘要为长期记忆，后续对话可引用压缩结果。

bash

# 整理全部会话
edgeclaw memory consolidate --scope all

# 仅整理名为 main 的会话
edgeclaw memory consolidate --scope main

# 预览将合并的内容，不写盘
edgeclaw memory consolidate --scope main --dry-run

选项	说明
`--scope all`	处理所有 session
`--scope <session_key>`	仅处理指定会话
`--dry-run`	只输出计划，不修改 `memory/`

适合运维会话、长期值班机器人等场景；短会话可不必执行。

9.11 skillhub — EdgeHub 技能市场

从在线市场搜索、下载、安装 Skill，无需 hdc file send。命令在 edgeclaw_service 内执行 HTTP 下载与解压，安装后 catalog 热更新（通常无需重启）。

子命令	语法	说明
`search`	`skillhub search <关键词>`	按关键词搜索；可加 `--json` 结构化输出
`install`	`skillhub install <slug> [-v <版本>] [--agent <name>]`	下载安装；`--agent` 表示仅挂载到该子 Agent
`list`	`skillhub list`	列出通过 EdgeHub 安装的记录（非完整 catalog）
`delete`	`skillhub delete <slug>`	卸载；`remove` 同义

bash

# 搜索入门包
edgeclaw skillhub search hello

# 安装到全局（教程推荐包）
edgeclaw skillhub install skillhub-hello -v 1.0.0

# 安装到 devops_enginer 专用目录
edgeclaw skillhub install build-agent-cli --agent devops_enginer -v v1.0

# 查看 EdgeHub 安装记录
edgeclaw skillhub list

# 验证运行时是否可见
edgeclaw --format json skill list

注意：版本用 -v 1.0.0 或 -v v1.0，不要用顶层 edgeclaw -v（会被 CLI 自身 --version 消费）。EdgeHub 地址见 5.2 节，网页安装命令见 5.3 节。

9.12 agenthub — EdgeHub 子智能体市场

与 skillhub 对称，面向子 Agent 包（AGENT.md + agent.json）。

子命令	语法	说明
`search`	`agenthub search <关键词>`	搜索子 Agent
`install`	`agenthub install <slug> [-v <版本>] [--force]`	下载安装；`--force` 覆盖已存在版本
`list`	`agenthub list`	EdgeHub 安装记录
`delete`	`agenthub delete <slug>`	卸载

bash

edgeclaw agenthub search qa
edgeclaw agenthub install qa-automation-enginer -v v1.0 --force
edgeclaw agenthub list
edgeclaw --format json agent list

EdgeHub slug（如 qa-automation-enginer）与运行时 name（如 qa_automation_enginer）可能不同；对话委派用 agent list 中的 name。

9.13 federation — 跨设备联邦

基于 DSoftBus 组网与 A2A 协议，在多块板子间同步 Agent 目录并远程调用。单板时处于 alone 阶段，仍可查询状态；双板联调见第十一章。

子命令	说明
`federation status`	本机角色（coordinator / member）、联邦阶段、路由是否就绪
`federation peers`	协调者与成员列表、在线节点
`federation list`	协调者视角的联邦 Agent 目录
`federation sync`	手动触发目录同步（组网后）
`federation invoke`	远程调用指定设备的子 Agent
`federation dump-cards`	导出本机 AgentCard（A2A 元数据）

bash

# 单机也可执行，用于确认联邦模块已启用
edgeclaw --format json federation status
edgeclaw --format json federation peers

# 双板：协调者调用成员 devops_enginer
edgeclaw --format json federation invoke \
  --device-id <成员deviceId> \
  --agent devops_enginer \
  --task "只回复 OK" \
  --timeout-ms 180000

推荐在双板环境按 11.4 节逐步完成组网与 federation invoke 验收。

9.14 服务生命周期管理

三服务默认随系统启动，仅在修改配置或排障时需要重启：

bash

# 启动 / 停止 EdgeClaw
service_control start edgeclaw_service
service_control stop edgeclaw_service

# 修改配置后重启
service_control restart edgeclaw_service

何时需要重启：

修改的文件	处理方式
`mcp_service.json`	`mcp add` / `mcp remove` / `mcp reload` 热更新，通常无需重启
`model_factory.json`	`service_control restart edgeclaw_service`
`settings.json`	`service_control restart edgeclaw_service`
EdgeHub 安装 Skill/Agent	通常无需重启（热更新）
EdgeHub 安装 MCP（`mcp install`）	通常无需重启（自动 reload）

三服务联调时，建议按 EdgeComputer → EdgeMCP → EdgeClaw 顺序启动（第二章）。

十、Skill 与子 Agent 深入

Skill 与子 Agent 是 EdgeClaw 扩展智能体能力的两种核心机制：Skill 把「怎么做」写成文档供主智能体执行；子 Agent 则是可委派的专职助手，自带工具集与专属 Skill。本章从概念、目录结构、EdgeHub 获取安装到板端验证，完整走通一条学习路径。

10.1 概念总览：Skill、子 Agent 与 MCP 的区别

EdgeClaw 主智能体（Orchestrator）收到用户消息后，可通过三条路径获取能力：

概念	载体	谁触发	粒度	典型场景
Skill	`SKILL.md`（+ 可选脚本）	主智能体或子智能体按文档执行	单一能力模块	查系统信息、跑 hilog、联网搜索
子 Agent	`AGENT.md` + `agent.json`	主智能体通过 `agent` 工具委派	完整专职智能体	运维诊断、端云 IoT、QA 自动化
MCP Tool	MCP Server 注册	LLM function calling	原子函数	`list_devices`、查 12306

记忆口诀：

Skill = 一本「操作手册」，智能体读完后用 bash 等工具照做。
子 Agent = 一个「专职同事」，主智能体把整段任务交给他，他在自己的上下文里独立完成。
MCP = 对外部系统暴露的「API 函数」，与设备、云服务对接。

主智能体默认挂载全局 Skill（如 system-info）；子 Agent 可挂载专属 Skill（如 devops_enginer 下的 hilog-diagnosis），并在 agent.json 的 skills 数组里声明。

10.2 Skill 详解：目录结构与 SKILL.md

10.2.1 Skill 是什么

Skill 是一个目录，核心是 SKILL.md：YAML frontmatter 描述元数据，Markdown 正文写清「何时用、用什么命令、注意什么」。智能体在 ReAct 循环中通过 skill 工具加载全文，或 frontmatter 里 always: true 时直接注入 system prompt。

两种挂载位置：

类型	板端路径（运行时）	谁可见
全局 Skill（内置）	`/system/etc/edgeclaw/skills/<name>/`	主智能体 + 所有子 Agent（除非 Skill 限制）
全局 Skill（EdgeHub/本地安装）	`.../edgeclaw/data/installed/skills/<name>/`	同上
子 Agent 专属 Skill	`.../agents/<agent>/skills/<name>/` 或 `.../data/installed/agent-skills/<agent>/skills/<name>/`	仅该子 Agent

镜像内置全局 Skill 示例目录（system-info，仅含一个 SKILL.md）：

/system/etc/edgeclaw/skills/system-info/
└── SKILL.md

EdgeHub 安装后的 Skill 可能更丰富（含脚本与参考文档）：

/data/service/el1/public/edgeclaw/data/installed/skills/skillhub-hello/
├── SKILL.md              # 技能定义（frontmatter + 正文，必填）
├── scripts/              # 可选：智能体可 bash 调用的脚本
├── references/           # 可选：补充参考文档
└── .skillhub/            # EdgeHub 元数据（版本、slug，安装时自动生成）

10.2.2 SKILL.md 结构示例

以内置 system-info 为例，文件开头为 frontmatter（--- 包裹的 YAML）：

markdown

---
name: system-info
description: 采集并汇报开源鸿蒙设备系统信息：硬件、OS、进程与运行状态
emoji: "💻"
always: false
os: [linux, ohos]
---

当用户询问 **OpenHarmony 端侧** 的设备状态、系统信息时，
使用 `bash` 工具执行下列命令……

## 基本系统信息
param get const.product.software.version
uname -a
……

frontmatter 字段	含义	示例
`name`	Skill 唯一标识，与目录名一致	`system-info`
`description`	简短说明，供智能体路由时匹配用户意图	采集系统信息……
`emoji`	展示用图标	`💻`
`always`	`true` 时全文预注入 prompt，无需再 `skill` 加载	`edge-device-control` 为 `true`
`os`	适用平台	`[linux, ohos]`
`allowed_agents`	可选，限制仅某子 Agent 可用	`[edge_computer]`

正文部分写可执行步骤：推荐命令、禁止事项（如 OHOS 无 python3）、输出如何汇报给用户。

子 Agent 专属 Skill 示例（devops_enginer 下的 hilog-diagnosis）：

/system/etc/edgeclaw/agents/devops_enginer/skills/hilog-diagnosis/
└── SKILL.md

markdown

---
name: hilog-diagnosis
description: 分析开源鸿蒙 hilog 日志，诊断应用崩溃、错误与系统问题
always: false
os: [linux, ohos]
---

当用户询问日志、崩溃、ANR 时，使用 `bash` 执行 `hilog`……
## OpenHarmony hilog 关键语法
hilog -T SAMGR --tail=30    # -T 是 Tag，不是 -t

10.2.3 对话中如何触发 Skill

主智能体根据 description 与用户意图自动选择 Skill，也可在消息里点名：

bash

edgeclaw chat -s demo -m "请检查当前系统信息"
# → 主智能体加载 system-info，执行 param/uname/df 等

edgeclaw chat -s demo -m "搜索一下 OpenHarmony 最新动态"
# → 加载 web-search，用 curl 联网

10.3 子 Agent 详解：目录结构与 agent.json

10.3.1 子 Agent 是什么

子 Agent 是独立配置的专职智能体：有自己的 agent.json（模型、工具、Skill 列表、超时等）、AGENT.md（角色与决策树）、以及可选的 skills/ 子目录。主智能体通过内置 agent 工具委派任务，子 Agent 在后台 worker 线程跑完 ReAct，再把结果合并回主会话。

委派示例：

bash

edgeclaw chat -s ops -m \
  "请委派 devops_enginer 子智能体，检查 edgecomputer_service 是否在运行"

主智能体识别「运维 / 服务状态」意图 → 调用 agent(devops_enginer, task=...) → 子 Agent 使用 Service Diagnosis 等 Skill 执行 pidof、hilog -T SAMGR 等 → 结构化结论返回主会话。

10.3.2 子 Agent 目录结构示例

内置 devops_enginer 完整布局（镜像路径 /system/etc/edgeclaw/agents/devops_enginer/）：

devops_enginer/
├── agent.json                    # 子智能体配置（必填）
├── AGENT.md                      # 角色说明、技能决策树（必填）
└── skills/                       # 该 Agent 专属 Skill（可选）
    ├── hilog-diagnosis/
    │   └── SKILL.md
    ├── hilog_analyzer/
    │   └── SKILL.md
    ├── service-diagnosis/
    │   └── SKILL.md
    ├── network-diagnosis/
    │   └── SKILL.md
    └── selinux-diagnosis/
        └── SKILL.md

EdgeHub 安装后的 Agent 布局（以 qa_automation_enginer 为例）：

/data/service/el1/public/edgeclaw/data/installed/agents/qa_automation_enginer/
├── agent.json
├── AGENT.md
└── skills/                       # 部分 Agent 包自带专属 Skill
    └── …

内置 edge_computer（端云 / MCP 专职）结构更精简，仅 2 个专属 Skill：

edge_computer/
├── agent.json
├── AGENT.md
└── skills/
    ├── edge-device-connect-cloud/
    │   └── SKILL.md              # JetLinks 连云、edgecomputer 配置
    └── edge-device-control/
        └── SKILL.md              # edge-device MCP 读写控制（always: true）

10.3.3 agent.json 关键字段

以 devops_enginer/agent.json 为例：

json

{
  "name": "devops_enginer",
  "description": "端侧运维工程师：Hilog/服务/网络/SELinux 诊断……",
  "version": "1.2",
  "agent_md": "AGENT.md",
  "agent_mode": "plan_and_executor",
  "max_turns": 10,
  "timeout_seconds": 600,
  "tools": ["bash", "read_file", "list_directory", "glob", "grep", "system_info", "add_memory"],
  "skills": [
    "Hilog Diagnosis",
    "hilog_analyzer",
    "Service Diagnosis",
    "Network Diagnosis",
    "SELinux Diagnosis",
    "system_info"
  ],
  "mcp_servers": [],
  "permission_mode": "default"
}

字段	含义
`name`	委派时必须用这个名（如 `devops_enginer`），不是 EdgeHub slug
`description`	供主智能体判断何时委派
`tools`	子 Agent 可用的内置工具（`bash`、`mcp`、`skill` 等）
`skills`	绑定的 Skill 显示名列表，与各 `SKILL.md` 的 `name`/标题对应
`mcp_servers`	需要的 MCP 服务名，如 `edge_computer` 填 `["edge-device"]`
`agent_mode`	子 Agent 推理模式，常见 `plan_and_executor`
`permission_mode`	工具调用是否需用户确认

AGENT.md 则写角色定位、触发关键词、技能选择决策树、报告格式，供子 Agent system prompt 引用。

10.3.4 slug 与运行时 name 的区别

EdgeHub 网页与 CLI 使用 slug（如 qa-automation-enginer，带连字符）；安装落盘后 agent.json 的 name 常为下划线形式（如 qa_automation_enginer）。对话委派、 agent list 查到的都是 name。

EdgeHub slug	agent.json `name`	对话里写
`qa-automation-enginer`	`qa_automation_enginer`	委派 `qa_automation_enginer`
`devops_enginer`（内置）	`devops_enginer`	委派 `devops_enginer`

10.4 板端目录总览

EdgeClaw 数据根目录默认为 /data/service/el1/public/edgeclaw：

edgeclaw/
├── skills/                    # 内置全局 Skill（只读，随镜像）
├── agents/                    # 内置子 Agent（只读）
│   ├── devops_enginer/
│   └── edge_computer/
├── data/
│   └── installed/
│       ├── skills/            # EdgeHub / 本地安装的全局 Skill
│       ├── agents/            # EdgeHub / 本地安装的子 Agent
│       └── agent-skills/      # 安装到指定子 Agent 的 Skill
│           └── devops_enginer/
│               └── skills/
│                   └── build-agent-cli/
└── sessions/                  # 多轮会话 transcript

命令	列出什么
`edgeclaw skill list` / `agent list`	运行时 catalog（builtin + installed），对话路由依据
`edgeclaw skillhub list` / `agenthub list`	仅 EdgeHub 安装记录（市场管理用）

安装成功后 catalog 热更新（on_install_reload: true），一般无需重启 edgeclaw_service。

10.5 内置 Skill 与子 Agent（v0.1.0）

内置全局 Skill

Skill	功能	触发示例
`ohos-bundle`	OHOS 应用包管理（`ohos bundle list/get`）	「列出已安装应用」
`system-info`	硬件、OS、进程、磁盘	「检查当前系统信息」
`system-ops`	remount、服务管理、设备维护	「重启 edgecomputer 服务」
`web-search`	curl 联网搜索	「查一下某某新闻」

bash

edgeclaw --format json skill list

内置子 Agent

Agent	专属 Skill 数	功能
`devops_enginer`	5 + `system_info`	Hilog、服务、网络、SELinux 诊断
`edge_computer`	2	JetLinks 端云、edge-device MCP 控制

bash

edgeclaw --format json agent list

edgeclaw chat -s demo -m \
  "请委派 edge_computer 子智能体，列出所有子设备"

10.6 EdgeHub 在线安装（见第五章）

网页截图、skillhub / agenthub 搜索安装、slug 与版本对照，已在 第五章 完整讲解。本节只补充本地包与 hdc 推送安装——适合自研 Skill/Agent、内网包或未上架 EdgeHub 的场景。

在线安装快速命令（详情见 5.4、5.5 节）：

bash

edgeclaw skillhub install skillhub-hello -v 1.0.0
edgeclaw agenthub install qa-automation-enginer -v v1.0

10.7 本地安装 Skill

适合自研 Skill、内网包、或未上架 EdgeHub 的包：

bash

# 从 tar.gz 安装
edgeclaw skill install /data/local/tmp/my-skill.tar.gz

# 从已解压目录安装
edgeclaw skill install /data/local/tmp/my-skill/

# 仅挂载到 devops_enginer
edgeclaw skill install /data/local/tmp/my-skill.tar.gz --agent devops_enginer

包内至少包含符合规范的 SKILL.md；目录名建议与 frontmatter name 一致。

10.7.1 hdc 推送后安装

开发机上打好包，推到板端再 skill install：

bash

# 【宿主机 PC】
hdc file send ./my-skill.tar.gz /data/local/tmp/

# 【板端】
edgeclaw skill install /data/local/tmp/my-skill.tar.gz
edgeclaw --format json skill list

10.8 本地安装子 Agent

在线安装见第五章 5.5 节。本地包安装：

bash

edgeclaw agent install /data/local/tmp/qa-agent.tar.gz
edgeclaw --format json agent list

包内须含 agent.json 与 AGENT.md。

10.8.1 卸载（EdgeHub 安装的包）

bash

edgeclaw agenthub delete qa-automation-enginer
edgeclaw --format json agent list   # 确认 catalog 已移除

10.9 安装后验证完整流程

建议在同一会话里对比安装前后 catalog 变化（安装会热更新 prompt，并可能向活跃会话注入 status 消息）：

bash

SESSION=skill-verify

# 安装前
edgeclaw chat -s $SESSION -m "当前有哪些 skill 和 sub-agent？"

# 安装 Skill
edgeclaw skillhub install skillhub-hello -v 1.0.0

# 安装 Agent
edgeclaw agenthub install qa-automation-enginer -v v1.0 --force

# 安装后再次询问（应能提到新包）
edgeclaw chat -s $SESSION -m "catalog 有变化吗？列出新增的 skill 和 agent"

# JSON 复核
edgeclaw --format json skill list | grep skillhub-hello
edgeclaw --format json agent list | grep qa_automation

检查项	命令	期望
EdgeHub 记录	`skillhub list` / `agenthub list`	出现新 slug
运行时 catalog	`skill list` / `agent list`	出现新 name
对话可用	`chat` 委派或触发	能按新能力回答

10.10 对话中的使用方式小结

目标	示例消息
触发全局 Skill	`请检查当前系统信息`
委派运维子 Agent	`请委派 devops_enginer 检查 edgecomputer 服务日志`
委派端云子 Agent	`请委派 edge_computer 列出子设备并读 cpu_usage`
使用新安装的 Agent	`请委派 qa_automation_enginer 说明你的测试能力`
安装后确认	`你新增了哪些 skill？`

主智能体根据 description 与历史消息自动路由；精确复现时可显式写出 Skill 名或子 Agent name。

10.11 权限模式

settings.json 中 permission_mode 影响 Skill / 子 Agent 执行写操作（如 system-ops 改系统、set_device_properties）时是否弹确认：

值	行为
`default`	写操作需确认（`config show` 常见默认值）
`full_auto`	自动批准工具调用（部分出厂镜像示例值）

生产环境建议保持 default，在测试会话中验证新 Skill 后再放宽。

十一、联邦群体智能

11.1 联邦原理

联邦（Federation）让多块边缘设备组成群体智能网络，通过 DSoftBus LNN 组网 + A2A（Agent-to-Agent）协议实现跨设备 Agent 调用。

概念	说明
协调者	维护联邦 Agent 目录，接收 invoke 请求
成员	注册本地 Agent，响应远程调用
自动选举	`role: auto`，按 deviceId 字典序 + 硬件 profile
A2A	Google Agent-to-Agent 协议 v1.0

11.2 federation 子命令

命令	功能
`federation status`	联邦状态（角色、阶段、在线节点）
`federation peers`	协调者与成员列表
`federation list`	联邦 Agent 目录（协调者视角）
`federation sync`	手动同步目录
`federation invoke`	远程调用指定设备 Agent
`federation dump-cards`	导出本地 AgentCards

11.3 单机实测（评测用例 #20、#21）

单板环境下联邦处于 alone 阶段，仍可查询状态：

bash

edgeclaw --format json federation status

实测关键字段：

json

{
  "federation": {
    "enabled": true,
    "configuredRole": "auto",
    "role": "coordinator",
    "federationPhase": "alone",
    "remoteDevices": 0,
    "routeReady": true,
    "online": true
  },
  "ok": true
}

bash

edgeclaw --format json federation peers

实测：localRole=coordinator，members=[]，peers 仅含自身。

11.4 双板验证（逐步操作）

本节按实验室双板联邦 E2E 验收流程编写：刷同一镜像的两块板，经 SoftBus LNN 组网、自动选举协调者/成员后，在协调者上 federation invoke 调用成员板预置 Agent。全程在 宿主机 PC 用 hdc 操作，无需额外脚本。

11.4.1 验证目标

步骤	通过标准
软总线组网	双板 `softbus_tool device-list` → `online devices: 1`
自动选举	双板 `federation peers` → 一块 `coordinator`、一块 `member`
目录同步	成员板 `federation sync` → 无报错；协调者 `federation list` → `devices` 非空
联邦列表	`catalog.devices[].agents` 含预置 Agent（`devops_enginer` / `edge_computer`）
远程调用	协调者 `federation invoke` → `status: completed`

11.4.2 前置条件

项目	要求
硬件	两块板同一局域网，PC 能 `hdc list targets` 看到两块
服务	双板 `edgeclaw_service`、`softbus_server` 已运行；禁止 `killall softbus_server`
联邦	`federation.json` 中 `enabled: true`，`role: "auto"`（出厂默认）
Agent	镜像预置 `devops_enginer`、`edge_computer`，最短路径无需 `agenthub install`
SELinux	保持 Enforcing；authCode 已预置，现场只需 `import-credential`

确认 PC 能同时看到两块板：

bash

hdc list targets

在 PC 上定义变量（替换为你自己的 hdc deviceId 与对端 IP）：

bash

BOARD_A="150100424a5444345204e55395ff7900"
BOARD_A_IP="71.255.5.138"

BOARD_B="880103534c4431323855c5eee3a04900"
BOARD_B_IP="71.255.5.49"

角色说明：哪块板是协调者由 deviceId 字典序与硬件 profile 自动选举，不要假设固定。以下以 federation peers 的 localRole 为准，将 coordinator 记为 $COORD_DEV，member 记为 $MEMBER_DEV。

11.4.3 流程总览

刷机开机 → import-credential（双板）
  → discover-start（双板）→ JoinLNN（按对端 IP 匹配索引）
  → device-list 确认 online devices: 1
  → federation peers 确认 coordinator + member
  → 成员板 federation sync
  → 协调者 federation list（非空）
  → 协调者 federation invoke → completed

步骤 1：设备互信（import-credential）

作用：建立 SoftBus 设备组信任，LNN 组网的前提。

bash

for DEV in "$BOARD_A" "$BOARD_B"; do
  hdc -t "$DEV" shell "softbus_tool import-credential"
done

期望：输出含 getTrustedDevices ... ret=0。若 deviceNum 仍为 1，可对双板各再执行一次 import。

步骤 2：启动局域网发现（discover-start）

bash

hdc -t "$BOARD_A" shell "softbus_tool discover-start"
hdc -t "$BOARD_B" shell "softbus_tool discover-start"
sleep 12

期望：StartDiscoverServer Finish。

步骤 3：加入 LNN（JoinLNN）

在成员侧查看发现列表（也可由另一块板发起，以能发现对端为准）：

bash

hdc -t "$BOARD_B" shell "softbus_tool discover-show"

在输出中找到对端 IP（如 BOARD_A_IP）所在块，记下索引 [N]：

------------[1]---------------
>>>addr[0] -ip= 71.255.5.138 -port=[38535]

执行 JoinLNN（第二个参数为索引 N，必须按 IP 匹配，勿硬编码）：

bash

hdc -t "$BOARD_B" shell "softbus_tool base.JoinLNN 0 1"
sleep 15

期望：retCode = 0，非空 networkId。

步骤 4：确认 LNN 在线（device-list）

bash

hdc -t "$BOARD_A" shell "softbus_tool device-list"
hdc -t "$BOARD_B" shell "softbus_tool device-list"

期望：双板均 online devices: 1。

步骤 5：确认联邦选举（peers）

等待 15～30 秒 后查询：

bash

hdc -t "$BOARD_A" shell "edgeclaw --format json federation peers" | grep localRole
hdc -t "$BOARD_B" shell "edgeclaw --format json federation peers" | grep localRole

期望：一块 localRole=coordinator，一块 localRole=member。

若未收敛（例如两块都是 coordinator），等待 20 秒后在成员板执行 federation sync，再查 peers：

bash

hdc -t "$MEMBER_DEV" shell "edgeclaw --format json federation sync"
sleep 10

记下 $COORD_DEV 与 $MEMBER_DEV 对应的 hdc deviceId。

步骤 6：成员板同步目录（federation sync）

作用：将成员板 Agent 目录推送到协调者 catalog（最短验收路径的关键一步）。

bash

hdc -t "$MEMBER_DEV" shell "edgeclaw --format json federation sync"

期望：命令成功返回；协调者稍后 federation list 应出现成员设备条目。

步骤 7：协调者查看联邦目录（federation list）

bash

hdc -t "$COORD_DEV" shell "edgeclaw --format json federation list"

期望：catalog.devices 非空，status: "online"，且 agents[] 含预置 Agent：

Agent `name`	说明
`devops_enginer`	运维诊断（推荐用于首次 invoke）
`edge_computer`	端云 / MCP

从 JSON 抄下：

字段	用途
`catalog.devices[0].deviceId`	`invoke` 的 `--device-id`
`agents[].name`	`invoke` 的 `--agent`

--device-id 必须用 catalog 中的 deviceId（常为 LNN networkId 格式），不要混用 hdc list targets 的串。

若 list 为空：确认步骤 4 device-list 为 1 → 成员板重做步骤 6 sync → 协调者重查 list。

步骤 8：协调者远程调用（federation invoke）

最短验收（使用镜像预置 devops_enginer，无需 EdgeHub）：

bash

hdc -t "$COORD_DEV" shell "edgeclaw --format json federation invoke \
  --device-id <步骤7中的deviceId> \
  --agent devops_enginer \
  --task '只回复OK' \
  --timeout-ms 180000"

成功时期望：

json

{
  "ok": true,
  "result": {
    "ok": true,
    "response": {
      "result": {
        "status": "completed",
        "text": "OK"
      }
    }
  }
}

参数	说明
`--device-id`	来自 `federation list`
`--agent`	成员 catalog 中的 `name`（下划线形式）
`--task`	自然语言任务
`--timeout-ms`	建议 ≥ 180000

若 invoke 超时：成员板再执行 federation sync，等待 5 秒后重试。

11.4.4 进阶：成员板安装独有 Agent 后再 invoke（可选）

用于演示「协调者调用成员上 EdgeHub 安装的 Agent」，非最短路径必需。

bash

hdc -t "$MEMBER_DEV" shell "edgeclaw agenthub install qa-automation-enginer -v v1.0 --force"
sleep 30
hdc -t "$MEMBER_DEV" shell "edgeclaw --format json federation sync"
hdc -t "$COORD_DEV" shell "edgeclaw --format json federation list"
# invoke 时 --agent qa_automation_enginer

若 agenthub install 返回 HTTP 400，改用预置 devops_enginer 完成验收即可。

11.4.5 验收检查表

#	步骤	通过标准
1	import-credential	双板 `ret=0`
2	discover-start	`StartDiscoverServer Finish`
3	JoinLNN	`retCode = 0`
4	device-list	双板 `online devices: 1`
5	federation peers	coordinator + member
6	成员 federation sync	成功
7	federation list	`devices` 非空，含 Agent
8	federation invoke	`status: completed`

11.4.6 常见问题与日志

现象	处理
选举未收敛	`sleep 20` → 成员 `federation sync` → 再查 `peers`
`federation list` 为空	确认 `device-list` 为 1 → 成员 `sync` → 协调者重查
`invoke` Timeout	成员 `sync` 后重试；增大 `--timeout-ms`
reboot 后失败	重做步骤 1～3（import + discover + JoinLNN）
禁止	`killall softbus_server`；删除 `/system/etc/edgeclaw/*`

查看联邦相关日志：

bash

hdc -t <deviceId> shell "hilog -x | grep C01650 | tail -30"

日志关键字	含义
`OnLocalNetworkIdChanged`	LNN networkId 已刷新
`federation.register`	成员注册成功
`invokeRemoteAgent`	远程调用已发起
`requestPeerFromWorker got=1`	收到 JSON-RPC 回复

11.5 invoke 返回字段说明

步骤 8 成功时，JSON 各层含义如下：

字段路径	含义
`ok`	CLI 命令是否执行成功
`result.ok`	联邦路由与 A2A 调用是否成功
`result.response.result.status`	远端 Agent 任务状态，`completed` 表示完成
`result.response.result.text`	远端 Agent 返回的文本
`result.error`	失败时的错误信息（如 `Timeout`）

常见失败：

现象	处理
`result.error: Timeout`	成员板 `federation sync` 后重试；增大 `--timeout-ms`
`device not found`	`--device-id` 与 `federation list` 不一致
`agent not found`	成员板未安装该 Agent，或 catalog 未刷新
peers 无 coordinator/member	回到 11.4 步骤 1～5 重做 LNN 与选举

11.6 联邦配置要点

/system/etc/edgeclaw/federation.json：

json

{
  "enabled": true,
  "role": "auto",
  "coordinator": {
    "autoElect": true,
    "electPriority": 0
  },
  "softbus": {
    "pkgName": "com.openharmony.edgeclaw.federation",
    "capability": "edgeclaw.federation",
    "publishId": "edgeclaw",
    "subscribeId": "edge_pipe",
    "autoJoinOnStart": true
  },
  "a2a": {
    "socketName": "edgeclaw.a2a",
    "defaultTimeoutMs": 120000
  }
}

十二、常见问题

12.1 问题速查表

现象	可能原因	解决方案
`aggregate_ready=false`	启动顺序错误或 edgemcp 未就绪	按 edgecomputer → edgemcp → edgeclaw 重启
`mcp status connected=false`	URL 不可达或 edgemcp 未就绪	先 `edgemcp health`；再 `mcp reload`
`mcp list --runtime` connected 但 chat 失败	连接池与 CLI 探测不一致	`edgeclaw mcp reload`
`edgemcp.bridge_connected=false`	edgecomputer_service 未运行	`service_control start edgecomputer_service`
`edgemcp init_error: Too many sessions`	MCP 会话泄漏	重启 edgemcp 与 edgeclaw_service
`tool_count=0`	edgemcp 未连接 edgecomputer	检查 edgecomputer IPC 与插件加载
`skillhub download HTTP 400`	slug 已下架或版本不存在	改用 `skillhub-hello` 等当前可用包
`edgeclaw run` 无响应/报错	model_factory.json 未配置 API Key	配置 LLM Provider
`federation invoke` 超时	SoftBus 未组网或目录未同步	按 11.4 节重做 LNN；成员板执行 `federation sync` 后重试
内置 Agent 重复	installed 目录同名冲突	检查 `data/installed/agents/`
`health ok` 但 chat 失败	网络不通或 API 配额	检查外网与 API Key

12.2 aggregate_ready 为 false 的诊断流程

bash

# 1. 检查三进程
ps -ef | grep -E 'edgecomputer|edgemcp|edgeclaw' | grep -v grep

# 2. 分层检查
edgecomputer service status --format json
edgemcp health --format json
edgeclaw --format json health --all

# 3. 按依赖顺序重启
service_control stop edgeclaw_service
service_control stop edgemcp
service_control stop edgecomputer_service
service_control start edgecomputer_service
sleep 2
service_control start edgemcp
sleep 2
service_control start edgeclaw_service
sleep 2
edgeclaw --format json health --all

12.3 MCP 连接失败

bash

# 确认运行时配置
cat /data/service/el1/public/edgeclaw/mcp_service.json

# 确认运行时连接池状态
edgeclaw --format table mcp list --runtime

# 手工改文件后重载（无需重启）
edgeclaw --format json mcp reload

# 确认 edgemcp 监听
edgemcp health --format json

# CLI 独立探测 URL 是否可达
edgeclaw --format json mcp status edge-device

确认 mcp_service.json 中 edge-device 条目与出厂配置一致。若 mcp list --runtime 显示 connected 但 chat 仍报 MCP client not connected，执行 mcp reload 同步连接池；仅当 harnessd 异常时才 service_control restart edgeclaw_service。

12.4 EdgeHub 下载失败

bash

param get persist.edge.cloud.base_url
curl -I https://zhihongos.cn/edgehub/api/web/skills/global/skillhub-hello/versions/1.0.0/download

确认网络可达、slug 与版本号正确。负向用例 #23 的 HTTP 400 属于预期行为。

12.5 日志位置

组件	日志路径
EdgeClaw	`/data/service/el1/public/edgeclaw/data/logs/edgeclaw.log`
EdgeComputer	`/data/service/el1/public/edgecomputer/edgecomputer.log`
EdgeMCP	`/data/service/el1/public/edgemcp/edgemcp.log`

bash

tail -f /data/service/el1/public/edgeclaw/data/logs/edgeclaw.log

12.6 服务重启

bash

service_control restart edgeclaw_service    # edgeclaw
service_control restart edgemcp    # edgemcp
service_control restart edgecomputer_service    # edgecomputer

十三、附录

附录 A：命令速查表

场景	命令
版本	`edgeclaw --version`
健康检查	`edgeclaw --format json health`
聚合就绪	`edgeclaw --format json health --all`
配置摘要	`edgeclaw --format json config show`
命令自省	`edgeclaw schema`
单轮对话	`edgeclaw run "问题"`
多轮对话	`edgeclaw chat -s main -m "问题"`
Skill 列表	`edgeclaw --format json skill list`
Agent 列表	`edgeclaw --format json agent list`
MCP 列表（运行时）	`edgeclaw --format table mcp list --runtime`
MCP 热重载	`edgeclaw --format json mcp reload`
MCP 添加	`edgeclaw mcp add --name <n> --url <url> --force`
MCP 删除	`edgeclaw mcp remove <name>`
MCP 工具	`edgeclaw --format json mcp tools edge-device`
安装 Skill	`edgeclaw skillhub install skillhub-hello -v 1.0.0`
安装 Agent	`edgeclaw agenthub install qa-automation-enginer -v v1.0 --force`
联邦状态	`edgeclaw --format json federation status`
联邦节点	`edgeclaw --format json federation peers`
远程调用	`edgeclaw federation invoke --device-id ... --agent ... --task "..."`
重启服务	`service_control restart edgeclaw_service`

附录 B：练手 checklist

步骤	做什么	怎么确认	对应章节
1	`hdc shell` 连板子	`edgeclaw --version` 有输出	第二章
2	确认三服务就绪	`health --all` → `aggregate_ready: true`	第二章、第三章
3	跑通第一条对话	`edgeclaw run "1+1"` 有回复	第三章
4	多轮会话	`chat -s demo` 能记住上文	第三章
5	对话查设备	`chat` 能列出子设备 / CPU	第四章
6	从 EdgeHub 装 Skill	`skillhub install skillhub-hello` 成功	第五章
7	从 EdgeHub 装 Agent	`agenthub install qa-automation-enginer` 成功	第五章
8	端云联调（可选）	JetLinks 在线 + MCP 读属性	第八章
9	双板联邦（可选）	`federation peers` 见对端	第十一章

附录 C：五服务教程体系导航

顺序	服务	本地教程	角色	依赖
1	EdgeComputer	edgecomputer.md	JetLinks 网关、子设备、插件	WiFi / JetLinks 账号
2	EdgeMCP	edgemcp.md	物模型 → MCP Tool	EdgeComputer
3	EdgeClaw	edgeclaw.md（本文）	AI 编排、自然语言控制 IoT	EdgeComputer + EdgeMCP
4	Edge Engine	edgeengine.md	端侧 CV/语音推理	NPU（RK3588）
5	EdgePipe	edgepipe.md	视觉流水线 YAML	Edge Engine

推荐路径：IoT + AI 开发者按 1→2→3 阅读；视觉 AI 开发者 4→5；全栈可并行。

附录 D：服务与端口对照

服务	进程	关键端口/套接字
EdgeClaw	edgeclaw_service	Unix Socket harnessd
EdgePipe	edge_pipe_service	—
Edge Engine	edge_engine_service	—
EdgeComputer	edgecomputer_service	gRPC Unix Socket
EdgeMCP	edgemcp	HTTP 9720 (/mcp)

附录 E：settings.json 完整示例

json

{
  "version": "1.0",
  "permission_mode": "full_auto",
  "max_turns": 16,
  "agent_mode": "reactive",
  "worker_agent_mode": "plan_and_executor",
  "compact": {
    "enabled": true,
    "threshold_tokens": 8000,
    "keep_recent_messages": 6
  },
  "tools": {
    "allow_shell": true,
    "shell_timeout_ms": 30000,
    "shell_max_output_bytes": 65536
  },
  "logging": {
    "level": "info",
    "trace_steps": true,
    "file": "data/logs/edgeclaw.log",
    "console": false
  },
  "extensions": {
    "edgehub": {
      "registry": "https://zhihongos.cn/edgehub",
      "default_scope": "global",
      "on_install_reload": true
    }
  }
}

附录 F：外部 MCP 接入（12306-mcp）

除本地 edge-device 外，EdgeClaw 可连接远程 Streamable HTTP MCP 服务。

bash

# 添加并热加载（无需重启 edgeclaw_service）
edgeclaw --format json mcp add \
  --spec '{"mcpServers":{"12306-mcp":{"type":"streamable_http","url":"https://mcp.api-inference.modelscope.net/b0b41ada79b042/mcp"}}}' \
  --force

# 验证
edgeclaw --format table mcp list --runtime
edgeclaw --format json mcp status 12306-mcp
edgeclaw --format table mcp tools 12306-mcp

# 对话中使用
edgeclaw chat -s travel -m \
  '请使用 12306-mcp 查询明天深圳到北京的高铁，列出 2 个车次'

删除示例服务：

bash

edgeclaw --format json mcp remove 12306-mcp

出厂镜像可能已预置 12306-mcp；也可用 mcp add --force 更新 URL 并立即生效。

附录 G：端到端实战案例

案例 1：新手 30 分钟上手

bash

hdc shell
edgeclaw --format json health --all
edgeclaw chat -s first -m "你好，你能做什么？"
edgeclaw chat -s first -m "请检查系统信息"

案例 2：EdgeHub 安装 + 对话验证

bash

edgeclaw skillhub search hello
edgeclaw skillhub install skillhub-hello -v 1.0.0
edgeclaw --format json skill list
edgeclaw chat -s hub-demo -m "你新增了哪些 skill？"

案例 3：IoT 端云全链路

bash

edgecomputer cloud set --host zhihongos.cn --port 1883 \
  --api-base https://zhihongos.cn/iot/api --api-user admin --api-password zhihongos
edgecomputer gateway set --product-id edge-gateway --device-id edge-gw-001 \
  --secure-id edge-secure-id --secure-key edge-secure-key-2026
edgecomputer child set --product-id edge-linux-child --device-id edge-linux-001
edgecomputer config apply
edgecomputer plugin load linux_device
edgeclaw chat -s iot -m "列出所有子设备并读取 edge-linux-001 的 cpu_usage"

案例 4：双板联邦远程诊断

协调者板执行：

bash

edgeclaw --format json federation peers
edgeclaw --format json federation invoke \
  --device-id <成员ID> --agent devops_enginer \
  --task "检查 edgeclaw_service 进程是否运行，只回复 OK 或 FAIL"

附录 H：health --all 完整 JSON 样例（实测）

json

{
  "aggregate_ready": true,
  "command": "health",
  "edgecomputer": {
    "connected": true,
    "device_count": 3,
    "fallback_used": true,
    "ipc_ok": true
  },
  "edgemcp": {
    "bridge_connected": true,
    "device_count": 0,
    "mcp_endpoint": "/mcp",
    "mcp_host": "127.0.0.1",
    "mcp_listening": true,
    "mcp_port": 9720,
    "reachable": true,
    "service": "edgemcp",
    "tool_count": 5
  },
  "health": {
    "cron_running": false,
    "harness_dir": "/data/service/el1/public/edgeclaw",
    "mcp_configured": true,
    "status": "ok",
    "version": "0.1.0"
  },
  "ok": true
}

附录 I：mcp tools 工具名清单（实测）

get_device_capabilities
get_device_properties
invoke_device_function
list_devices
set_device_properties

LLM 调用时使用带命名空间前缀的限定名，例如 mcp__edge-device__list_devices。

EdgeClaw 新手教程 ​

目录 ​

一、开始之前 ​

1.1 这份文档帮你做什么 ​

1.2 你需要准备 ​

1.3 CLI 名称与全局约定 ​

二、连接开发板 ​

2.1 宿主机连接开发板 ​

2.2 确认三服务已运行 ​

2.3 第一步验证 ​

2.4 版本确认 ​

2.5 网络与云平台 ​

2.6 模型 API Key 配置 ​

2.7 环境自检（可选） ​

三、快速开始 ​

3.1 第一步：健康检查 ​

3.2 第二步：聚合依赖检查 ​

3.3 第三步：单轮对话 ​

3.4 第四步：多轮对话 ​

3.5 第五步：查看能力目录 ​

3.6 期望结果 ​

四、对话控制设备 ​

4.1 MCP 是什么？ ​

4.2 mcp_service.json 配置与热更新 ​

推荐：用 CLI 管理 MCP（热更新，无需重启） ​

仍须重启的场景 ​

4.3 edge-device 五大工具 ​

4.4 通过对话调用 MCP ​

方式一：在消息里点名 MCP 工具（适合学习、复现） ​

方式二：用自然语言描述意图（适合日常使用） ​

方式三：委派 edge_computer 子 Agent（适合端云联调） ​

4.5 使用 edgemcp 直接调试 ​

edgemcp health — 服务自身是否就绪 ​

edgemcp tools list — 查看服务端工具定义 ​

edgemcp tools call — 直接调用单个工具 ​

4.6 EdgeClaw 侧：MCP CLI 命令 ​

mcp list / mcp list --runtime ​

mcp tools — 查看工具目录 ​

mcp status — 探测实时连接（CLI 独立探测） ​

4.7 分层健康检查与对照排障 ​

edgeclaw health --all 中的 edgemcp 段 ​

三条健康命令对照 ​

常见现象速查 ​

五、从 EdgeHub 扩展能力 ​

5.1 EdgeHub 是什么？ ​

5.2 查看 EdgeHub 地址（可选） ​

5.3 EdgeHub 网页界面操作图解 ​

5.3.1 进入市场与搜索 Skill ​

5.3.2 Skill 详情：复制安装命令 ​

5.3.3 搜索与安装 Agent ​

5.3.4 Agent 详情：复制安装命令 ​

5.3.5 网页与板端 CLI 对照 ​

5.4 skillhub — 技能市场操作详解 ​

5.4.1 命令一览 ​

5.4.2 search — 搜索技能 ​

5.4.3 install — 安装技能 ​

5.4.4 list — 列出已安装的 EdgeHub 技能 ​

5.4.5 delete — 卸载技能 ​

5.4.6 skillhub 典型工作流 ​

5.5 agenthub — 子智能体市场操作详解 ​

5.5.1 命令一览 ​

5.5.2 search — 搜索子智能体 ​

5.5.3 install — 安装子智能体 ​

5.5.4 list — 列出已安装的 EdgeHub 子智能体 ​

5.5.5 delete — 卸载子智能体 ​

5.5.6 slug 与运行时 name 对照 ​

5.5.7 agenthub 典型工作流 ​

5.5.8 skillhub 与 agenthub 对照速查 ​

5.6 负向用例（预期行为） ​

已下架 Skill（评测用例 #23） ​

空搜索结果（评测用例 #24） ​

5.7 安装后热更新验证 ​

5.8 当前可用市场包（2026-09 实测） ​

六、工作原理 ​

6.1 五大组件一览 ​

6.2 EdgeComputer 与 EdgeMCP ​

6.2.1 分工 ​

6.2.2 数据流（读一条属性） ​

6.3 EdgeClaw 与 EdgeMCP：自然语言如何控设备 ​

6.3.1 分工 ​

EdgeClaw 新手教程

目录

一、开始之前

1.1 这份文档帮你做什么

1.2 你需要准备

1.3 CLI 名称与全局约定

二、连接开发板

2.1 宿主机连接开发板

2.2 确认三服务已运行

2.3 第一步验证

2.4 版本确认

2.5 网络与云平台

2.6 模型 API Key 配置

2.7 环境自检（可选）

三、快速开始

3.1 第一步：健康检查

3.2 第二步：聚合依赖检查

3.3 第三步：单轮对话

3.4 第四步：多轮对话

3.5 第五步：查看能力目录

3.6 期望结果

四、对话控制设备

4.1 MCP 是什么？

4.2 mcp_service.json 配置与热更新

推荐：用 CLI 管理 MCP（热更新，无需重启）

仍须重启的场景

4.3 edge-device 五大工具

4.4 通过对话调用 MCP

方式一：在消息里点名 MCP 工具（适合学习、复现）

方式二：用自然语言描述意图（适合日常使用）

方式三：委派 edge_computer 子 Agent（适合端云联调）

4.5 使用 edgemcp 直接调试

edgemcp health — 服务自身是否就绪

edgemcp tools list — 查看服务端工具定义

edgemcp tools call — 直接调用单个工具

4.6 EdgeClaw 侧：MCP CLI 命令

mcp list / mcp list --runtime

mcp tools — 查看工具目录

mcp status — 探测实时连接（CLI 独立探测）

4.7 分层健康检查与对照排障

edgeclaw health --all 中的 edgemcp 段

三条健康命令对照

常见现象速查

五、从 EdgeHub 扩展能力

5.1 EdgeHub 是什么？

5.2 查看 EdgeHub 地址（可选）

5.3 EdgeHub 网页界面操作图解

5.3.1 进入市场与搜索 Skill

5.3.2 Skill 详情：复制安装命令

5.3.3 搜索与安装 Agent

5.3.4 Agent 详情：复制安装命令

5.3.5 网页与板端 CLI 对照

5.4 skillhub — 技能市场操作详解

5.4.1 命令一览

5.4.2 search — 搜索技能

5.4.3 install — 安装技能

5.4.4 list — 列出已安装的 EdgeHub 技能

5.4.5 delete — 卸载技能

5.4.6 skillhub 典型工作流

5.5 agenthub — 子智能体市场操作详解

5.5.1 命令一览

5.5.2 search — 搜索子智能体

5.5.3 install — 安装子智能体

5.5.4 list — 列出已安装的 EdgeHub 子智能体

5.5.5 delete — 卸载子智能体

5.5.6 slug 与运行时 name 对照

5.5.7 agenthub 典型工作流

5.5.8 skillhub 与 agenthub 对照速查

5.6 负向用例（预期行为）

已下架 Skill（评测用例 #23）

空搜索结果（评测用例 #24）

5.7 安装后热更新验证

5.8 当前可用市场包（2026-09 实测）

六、工作原理

6.1 五大组件一览

6.2 EdgeComputer 与 EdgeMCP

6.2.1 分工

6.2.2 数据流（读一条属性）

6.3 EdgeClaw 与 EdgeMCP：自然语言如何控设备

6.3.1 分工