# claw-bot

[中文](README.zh-CN.md) · [Homepage](index.html) · [Jetson acceptance](docs/claw-bot-deploy-acceptance.md)

![claw-bot logo](assets/brand/logo-horizontal.svg)

`claw-bot` is an Agent Harness plugin for robot perception, action, and
feedback. It packages a skill, MCP server, CLI, dashboard, and acceptance tools
so a decision agent can use capabilities exposed by a `realworld` or
`simulator` environment.

```text
claw-bot plugin + decision agent = Robot Brain
```

![claw-bot dashboard preview](assets/product/dashboard-preview.svg)

## Install

For a published npm package, install and configure a Linux or Jetson robot host
in one command:

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

For GitHub distribution, use the repository as both the temporary installer
package and the global package source:

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

The installer globally installs or refreshes `claw-bot`, writes the dashboard
token, claw-bot config, Codex profile, and systemd user service, then starts
the dashboard service. It assumes Linux with `node`, `npm`, `git`,
`systemctl --user`, an available dashboard port `8787`, and optionally `arecord`
for microphone diagnostics.

If `systemctl --user` cannot run because lingering is disabled, enable it
outside this repository:

```bash
loginctl enable-linger "$USER"
```

## Dashboard

The dashboard is the field acceptance and operator surface. It shows voice
state, microphone readiness, environment configuration, agent plan, action
payloads, controller feedback, and maintenance status.

Read the dashboard URL:

```bash
claw-bot dashboard open --json
```

Or construct it from the installer-written token:

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

For LAN access from another machine, replace `$(hostname)` with the robot host
name or IP:

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

The dashboard is a long-running HTTP/WebSocket service. It is not the marketing
homepage; the static homepage lives in [`index.html`](index.html).

## MCP Setup

`claw-bot install --yes` creates:

- `~/.codex/profiles/claw-bot/config.toml`
- `~/.config/claw-bot/environments.json`
- `~/.config/claw-bot/claw-bot.env`
- `~/.config/claw-bot/dashboard.env`
- `~/.config/systemd/user/claw-bot-dashboard.service`

For agents that configure MCP manually:

```toml
[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"
]
```

For registry-driven MCP clients that launch the npm package directly:

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

The MCP Registry metadata is in [`server.json`](server.json). The packaged skill
is [`skills/claw_bot`](skills/claw_bot).

The formal MCP contract and isolated acceptance standard are documented in [`docs/mcp-preview-standard.md`](docs/mcp-preview-standard.md).

## Validate

Verify the installed system:

```bash
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
```

Expected high-level result:

- dashboard service is active
- dashboard token is configured
- default active environment is `realworld`
- default `dryRun` is `true`
- MCP exposes only the `robot_*` tool surface
- benchmark runner reports all cases `ok`

## Field Acceptance

Local tests and HTTP health checks only prove the harness is configured. For a
real robot or simulator demo, record this evidence chain:

- spoken command
- transcript
- agent plan
- action payload
- controller feedback
- visible result

For Jetson deployment and live voice acceptance, follow
[`docs/claw-bot-deploy-acceptance.md`](docs/claw-bot-deploy-acceptance.md).

## Design Philosophy

claw-bot owns the plugin boundary. The decision agent owns the planning loop;
the robot or simulator environment owns the hardware, controller, and runtime
capabilities.

Within that boundary:

- Perception is exposed through MCP as snapshots, metadata, or stream handles.
- Decision remains agent-owned; Codex, Hermes, Pi, or another agent can use the
  plugin.
- Action is routed through environment adapters and returns structured
  feedback.
- `realworld` and `simulator` are environment types, not separate tool
  namespaces.
- Agents should call `robot_status` first, inspect capabilities, then choose
  perception or action calls.

## Scope

claw-bot owns:

- the packaged `claw_bot` skill
- the `claw-bot` CLI
- the `claw-bot-mcp` stdio server
- unified MCP tools for status, environment configuration, perception, action,
  subscriptions, and feedback
- realtime voice start, stop, and status as an operator input surface
- dashboard and Jetson validation helpers for field acceptance
- benchmark runners for comparing decision-agent integrations
- visual and product assets under `assets/`

claw-bot does not own:

- sensor setup
- actuator firmware
- low-level safety loops
- trained skill or policy loading
- simulator hosting
- robot model internals
- vendor deployment lifecycle

## CLI

Common commands:

```bash
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 and dashboard binaries are also published:

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

## Development

Install dependencies and run the full gate:

```bash
npm install
npm test
npm run pack:check
```

Focused checks:

```bash
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
```

Refresh a local source checkout into the globally installed plugin before a
field demo:

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

Package contents should stay focused on plugin-owned files: skill, MCP server,
CLI, dashboard, docs, acceptance scripts, templates, and assets.

## Links

- [Static homepage](index.html)
- [Chinese README](README.zh-CN.md)
- [Jetson deployment acceptance](docs/claw-bot-deploy-acceptance.md)
- [Packaged skill](skills/claw_bot/SKILL.md)
- [Dashboard source](web/dashboard/index.html)
- [MCP Registry metadata](server.json)