claw-bot

English · Homepage · Jetson acceptance

claw-bot logo

claw-bot 是面向机器人感知、行动和反馈的 Agent Harness plugin。它打包 skill、MCP server、CLI、dashboard 和验收工具，让决策 Agent 可以使用 realworld 或 simulator 环境暴露的机器人能力。

claw-bot plugin + decision agent = Robot Brain

claw-bot dashboard preview

安装

如果已经通过 npm 分发，在 Linux 或 Jetson 机器人主机上执行一行即可安装和配置：

npm exec --yes --package @bozhi-ai/claw-bot@latest -- claw-bot install --yes --json

如果从 GitHub 分发，用这个仓库同时作为临时 installer package 和全局 package 来源：

CLAW_BOT_INSTALL_PACKAGE_SPEC=github:bozhi-ai/claw-bot \
npm exec --yes --package github:bozhi-ai/claw-bot -- claw-bot install --yes --json

安装器会全局安装或刷新 claw-bot，写入 dashboard token、claw-bot config、 Codex profile 和 systemd user service，并启动 dashboard service。它假设主机是 Linux，已安装 node、npm、git 和 systemctl --user，dashboard 的 8787 端口可用，并推荐安装 arecord 用于麦克风诊断。

如果 systemctl --user 因 lingering 未启用而无法运行，在仓库外执行：

loginctl enable-linger "$USER"

Dashboard

Dashboard 是现场验收和操作员界面。它展示语音状态、麦克风就绪状态、环境配置、 agent plan、action payload、controller feedback 和维护状态。

读取 dashboard URL：

claw-bot dashboard open --json

或通过安装器写入的 token 手动拼接：

source ~/.config/claw-bot/dashboard.env
echo "http://$(hostname):8787/?token=${CLAW_BOT_DASHBOARD_TOKEN}"

从另一台机器访问时，把 $(hostname) 换成机器人主机名或 IP：

http://jetson.local:8787/?token=<CLAW_BOT_DASHBOARD_TOKEN>

Dashboard 是长驻 HTTP/WebSocket service。它不是营销主页；静态主页位于 index.html。

MCP 配置

claw-bot install --yes 会创建：

手动配置 MCP 的 Agent 可以使用：

[mcp_servers.claw_bot]
command = "claw-bot-mcp"
args = []
enabled = true
required = true
enabled_tools = [
  "robot_status",
  "robot_configure_environment",
  "robot_perceive",
  "robot_act",
  "robot_subscribe",
  "robot_feedback"
]

如果 MCP registry 客户端直接启动 npm package：

npx -y @bozhi-ai/claw-bot@latest mcp

MCP Registry 元数据在 server.json。打包的 skill 位于 skills/claw_bot。

MCP 正式标准与隔离验收见 docs/mcp-preview-standard.md。

验证

验证已安装系统：

systemctl --user status claw-bot-dashboard.service --no-pager --lines=20
claw-bot status --json
claw-bot doctor --json
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' | claw-bot-mcp
claw-bot voice start --environment realworld --json
claw-bot voice status --json
claw-bot voice stop --json
npm run benchmark:robot -- --runner mcp --case all --iterations 3 --json

预期高层结果：

现场验收

本地测试和 HTTP health check 只能证明 harness 已配置。真机或模拟器 demo 需要记录 以下证据链：

Jetson 部署和 live voice 验收见 docs/claw-bot-deploy-acceptance.md。

设计哲学

claw-bot 拥有 plugin 边界。决策 Agent 拥有规划循环；机器人或模拟器环境拥有硬件、 controller 和 runtime capability。

在这个边界内：

边界

claw-bot 拥有：

claw-bot 不拥有：

CLI

常用命令：

claw-bot status --json
claw-bot doctor --json
claw-bot dashboard open --json
claw-bot voice start --environment realworld --json
claw-bot voice status --json
claw-bot voice stop --json
claw-bot-mcp

Realtime voice 和 dashboard 相关二进制也会发布：

claw-bot-chatgpt-auth
claw-bot-chatgpt-transcribe-bridge
claw-bot-dashboard
claw-bot-jetson-tui
claw-bot-openai-realtime-bridge

开发

安装依赖并运行完整门禁：

npm install
npm test
npm run pack:check

RGB-D 集成测试需要通过 CLAW_BOT_TENSOR_PYTHON 指定一个已安装 PyTorch >=2.6、Pillow 和 numpy 的 Python 环境。未配置时测试会明确跳过； 已配置但运行时无效时测试会失败。Pull request CI 会安装 CPU 依赖并运行这些测试。 需要认证的 live vision 模型测试只有在设置 CLAW_BOT_LIVE_VISION_TEST=1 时才会启用； fixture 覆盖不需要该测试。参见 RGB-D 测试命令。

Focused checks：

npm run test:robot
npm run test:mcp
npm run test:skill
npm run test:voice
npm run benchmark:robot -- --runner mcp --case all --iterations 3 --json

现场 demo 前，把本地 source checkout 刷新到全局安装的 plugin：

claw-bot install --yes --package . --json

Package contents 应保持在 plugin 拥有的文件范围内：skill、MCP server、CLI、 dashboard、docs、验收脚本、templates 和 assets。

链接