# openclaw-smart-agent

Adopt this skill: https://proskills.md/skills/other/xinlingzhifei-openclaw-smart-agent-skills-openclaw-smart-agent

Page: https://proskills.md/skills/other/xinlingzhifei-openclaw-smart-agent-skills-openclaw-smart-agent
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/openclaw-smart-agent/SKILL.md
size: 2819
upstream: https://github.com/xinlingzhifei/openclaw-smart-agent/blob/main/skills/openclaw-smart-agent/SKILL.md

```text
---
name: openclaw-smart-agent
description: Use when orchestrating multiple OpenClaw sub-agents on one machine, especially when the user wants to create agents from role descriptions, publish tasks by required skills, inspect agent health and load, or route work through the Smart Agent runtime.
---

# OpenClaw Smart Agent

## Overview

Use this skill to drive the Smart Agent runtime through OpenClaw tools instead of manually tracking which sub-agent should do what.

The workflow is:

1. Create or reuse an agent from a short identity description.
2. Publish a task with required skills.
3. Inspect registry status when routing, health, or load needs confirmation.

## Tool Map

| Tool | Use |
| --- | --- |
| `smart_agent_create` | Turn a short role description into a registered Smart Agent |
| `smart_agent_status` | Inspect current agents, health state, and load snapshot |
| `smart_agent_heartbeat` | Record heartbeat, load, and current task information for an agent |
| `smart_agent_publish_task` | Submit a task and let the router pick the best worker |

## Operating Pattern

### Create an agent

Use `smart_agent_create` when the user gives you a role such as:

- `Python开发`
- `数据分析`
- `测试工程师`

Pass the shortest accurate identity string. Let the runtime expand it from templates.
If the available roles are not enough, extend the repository templates as documented in `docs/template-guide.md`.
If no local template matches and the runtime is configured with `identity.fallback_strategy: openclaw_llm`, `smart_agent_create` can ask OpenClaw's own `llm-task` tool to synthesize a profile before registration.

### Publish work

Use `smart_agent_publish_task` when the user gives a task but does not name a worker explicitly. Include:

- a clear `task_desc`
- the `required_skills` list
- `priority` only when urgency matters

### Inspect state

Use `smart_agent_status` before retrying, when assignment looks wrong, or when the user asks why a task is blocked.

### Record heartbeat

Use `smart_agent_heartbeat` when an external worker or integration has fresh CPU, memory, error count, or current-task information and you want the skill's status view to reflect real runtime data.

## Good Requests

- `Create a Python开发 agent and assign it a parser task.`
- `Route this analysis job to the best available worker.`
- `Show me which Smart Agents are healthy right now.`

## Common Mistakes

- Do not invent agent ids before creating or querying them.
- Do not manually choose a worker when routing by skills is enough.
- Do not skip `smart_agent_status` when the user asks for health or load details.

## References

For endpoint details and payload shapes, read [references/api.md](references/api.md).
For template authoring, read `docs/template-guide.md` in the repository root.
```

## File: README.md
upstream: https://github.com/xinlingzhifei/openclaw-smart-agent/blob/main/README.md

````text
# OpenClaw Smart Agent

[![CI](https://github.com/xinlingzhifei/openclaw-smart-agent/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/xinlingzhifei/openclaw-smart-agent/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/xinlingzhifei/openclaw-smart-agent?display_name=tag)](https://github.com/xinlingzhifei/openclaw-smart-agent/releases)
[![License](https://img.shields.io/github/license/xinlingzhifei/openclaw-smart-agent)](https://github.com/xinlingzhifei/openclaw-smart-agent/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)

OpenClaw Smart Agent is a GitHub-publishable, skill-first bundle for single-machine multi-agent orchestration in OpenClaw. It combines:

- a Python runtime support layer for identity enhancement, registration, routing, heartbeat-backed health snapshots, and task recovery
- an OpenClaw plugin that exposes the runtime as agent tools
- a workspace skill that teaches the host agent when and how to use those tools
- an optional OpenClaw `llm-task` fallback that can synthesize a profile when no local identity template matches

See [OpenClaw integration guide](docs/openclaw-integration.md) for the local setup path, verification flow, and plugin installation options.
See [template guide](docs/template-guide.md) for adding or modifying identity templates.
See [中文手册：未命中模板且不使用 OpenClaw LLM 的解决方案](docs/template-only-identity-solution.zh-CN.md) for a template-only path when you want deterministic identity matching without model-based fallback.

## What v1 includes

- Zero-configuration identity enhancement from YAML templates
- Optional `openclaw_llm` fallback for unmatched identities through OpenClaw Gateway `llm-task`
- SQLite-backed agent registry and task persistence
- Smart scoring router using skills, load, and priority weighting
- Heartbeat-backed health snapshots for timeout, CPU or memory pressure, and repeated errors
- Recovery flow that requeues work when an agent becomes unhealthy
- REST API plus CLI for local operation

## What v1 does not include

- Cross-machine distributed scheduling
- Built-in LLM inference
- Full process supervisor or container orchestration

## Architecture

```mermaid
flowchart LR
    OA["OpenClaw Host"] --> PL["Plugin Tools"]
    PL --> API["FastAPI Runtime"]
    API --> ID["Identity Enhancer"]
    API --> RG["Agent Registry"]
    API --> RT["Task Router"]
    API --> HM["Health Monitor"]
    HM --> RC["Recovery Manager"]
    RG --> DB["SQLite State Store"]
    RT --> DB
    RC --> DB
```

## Repository layout

- `src/openclaw_smart_agent/`: Python runtime package
- `plugin/`: OpenClaw plugin package and TypeScript entrypoint
- `skills/openclaw-smart-agent/`: workspace skill bundle
- `config/config.example.yaml`: sample runtime config
- `scripts/install.sh`: bootstrap script for source installs

## Install from GitHub

### Runtime only

Use this when you want the Python runtime and CLI:

```bash
python -m pip install "git+https://github.com/xinlingzhifei/openclaw-smart-agent.git"
openclaw-smart-agent init-config --output config/config.yaml
openclaw-smart-agent serve --config config/config.yaml
```

### Full bundle from a cloned repository

Use this when you also want the workspace skill and plugin package that live in the repository:

```bash
git clone https://github.com/xinlingzhifei/openclaw-smart-agent.git
cd openclaw-smart-agent
./scripts/install.sh
```

The install script copies the workspace skill into `${OPENCLAW_WORKSPACE:-~/.openclaw/workspace}/skills/openclaw-smart-agent`.
After you install the plugin and restart OpenClaw Gateway, the plugin will auto-start the runtime by default. Manual `openclaw-smart-agent serve --config config/config.yaml` is still useful for local debugging.

For the full skill-to-plugin-to-runtime verification path, including `smart_agent_heartbeat`, see [docs/openclaw-integration.md](docs/openclaw-integration.md).
You can also run `python scripts/verify_runtime.py` after starting the runtime to exercise the minimal API flow.

## OpenClaw integration

1. Publish the plugin package from `plugin/` to npm or ClawHub, or install it from the local `plugin/` directory during development.

2. Install that plugin in OpenClaw.

3. Restart OpenClaw so it picks up the workspace skill from `skills/openclaw-smart-agent/`.

4. The plugin will probe `http://127.0.0.1:8787` and auto-start `openclaw-smart-agent serve` when the runtime is not already running.

The plugin talks to the runtime through `http://127.0.0.1:8787` by default. Override it with `OPENCLAW_SMART_AGENT_BASE_URL`.

Note: if you run the Smart Agent runtime on a different host or port, set `OPENCLAW_SMART_AGENT_BASE_URL` in the environment that starts OpenClaw so the plugin can reach the runtime.

Optional plugin config:

- `autoStartRuntime`: disable this if you want to manage the runtime yourself
- `runtimeConfigPath`: point the auto-started runtime at a specific config file

## OpenClaw LLM identity fallback

Template matching stays first. If no YAML template matches, you can optionally ask OpenClaw itself to generate the profile through the official `llm-task` tool.

1. Enable and allowlist `llm-task` in OpenClaw.
2. Turn on `identity.fallback_strategy: openclaw_llm` in `config/config.yaml`.
3. Point the runtime at your OpenClaw Gateway URL and bearer token.

Note: `defaultAuthProfileId: "main"` is only a template value. If your real OpenClaw auth profile id is different, replace it in both the OpenClaw `llm-task` config and the Smart Agent runtime config.

See [docs/openclaw-integration.md](docs/openclaw-integration.md) for the required OpenClaw config and an example runtime config block.

## API quick start

- `POST /api/v1/agents/create`
- `POST /api/v1/agents/heartbeat`
- `GET /api/v1/agents/status`
- `POST /api/v1/tasks/publish`

`POST /api/v1/agents/create` uses local templates first and can fall back to `openclaw_llm` when configured.

Example:

```bash
curl -X POST http://127.0.0.1:8787/api/v1/agents/create \
  -H "content-type: application/json" \
  -d '{"identity":"Python开发"}'
```

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest tests -q
npm --prefix plugin install --no-audit --no-fund
npm --prefix plugin run check
```

## Compatibility notes

- Verified in this repository against Python 3.14 and Node 24.
- The current OpenClaw plugin entry follows the official `openclaw.plugin.json` plus `openclaw.extensions` package metadata model.
- The PRD mentioned `skill.json`, but current OpenClaw documentation uses `SKILL.md` for workspace skills and `openclaw.plugin.json` for plugins, so this repository follows the current upstream format.
````
