openclaw-smart-agent

OpenClaw Smart Agent

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 for the local setup path, verification flow, and plugin installation options. See template guide for adding or modifying identity templates. See 中文手册：未命中模板且不使用 OpenClaw LLM 的解决方案 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

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:

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:

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. 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 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:

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

Development

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.