OpenClawAgent

OpenClawAgent gives you a clean way to plug an OpenClaw worker into an Agency Swarm agency. Use it when Agency Swarm should stay in charge of delegation while OpenClaw handles one specialized branch.

Start With One Import

from agency_swarm.agents import OpenClawAgent

Use It In An Agency

from agency_swarm import Agency
from agency_swarm.agents import Agent, OpenClawAgent

coordinator = Agent(
    name="Coordinator",
    description="Routes work to the right specialist.",
    instructions="Delegate OpenClaw-specific tasks to OpenClawWorker.",
    model="gpt-5.6-luna",
)

openclaw_worker = OpenClawAgent(
    name="OpenClawWorker",
    description="Handles OpenClaw-native work.",
    instructions="Act as an OpenClaw specialist worker.",
)

agency = Agency(
    coordinator,
    communication_flows=[(coordinator, openclaw_worker)],
)

This example assumes OpenClawAgent can already reach a running OpenClaw endpoint. By default it calls the local /openclaw/v1 proxy, so either mount that proxy in the same FastAPI app or point the agent at a custom base_url.

Choose How To Reach OpenClaw

Same FastAPI app
Custom host and port
External OpenClaw server

from agency_swarm.agents import OpenClawAgent

openclaw_worker = OpenClawAgent(
    name="OpenClawWorker",
    description="OpenClaw specialist",
    instructions="Handle the delegated OpenClaw work and return the result.",
)

This uses the local /openclaw/v1 proxy in the same app. Before you use this path, mount that proxy in the same app with attach_openclaw_to_fastapi(app). Install the FastAPI extras for that path: pip install "agency-swarm[fastapi]". That mounted runtime also needs a working openclaw gateway command and a compatible Node installation. If OPENCLAW_PROXY_PORT is set, OpenClawAgent uses that port. Otherwise it falls back to PORT, then 8000.

from agency_swarm.agents import OpenClawAgent

openclaw_worker = OpenClawAgent(
    name="OpenClawWorker",
    description="OpenClaw specialist",
    instructions="Handle the delegated OpenClaw work and return the result.",
    host="127.0.0.1",
    port=18080,
    api_path="/openclaw/v1",
)

Use this when you run more than one OpenClaw-backed worker.

from agency_swarm.agents import OpenClawAgent

openclaw_worker = OpenClawAgent(
    name="OpenClawWorker",
    description="OpenClaw specialist",
    instructions="Handle the delegated OpenClaw work and return the result.",
    base_url="http://127.0.0.1:18789/v1",
    api_key="your-openclaw-token",
)

Use this when you are talking to a raw OpenClaw gateway that serves /v1 directly. If the remote server is another Agency Swarm app using this integration, use its /openclaw/v1 path instead of /v1. When that remote server is a delegated worker, start it with OPENCLAW_TOOL_MODE=worker. If it is plain OpenClaw outside Agency Swarm, disable its competing delegation paths in that runtime instead of copying this env var blindly. Raw /v1 gateways default to the upstream provider model, not openclaw:main. If that remote server expects a different model id, pass it with model="openclaw:custom" so this agent matches the target runtime. If you point to another Agency Swarm worker at /openclaw/v1, pass that worker’s api_key= explicitly unless you are using the same in-process proxy.

Collaboration Pattern

Use OpenClawAgent as a worker. Do not use it as the top-level delegator. Why:

Agency Swarm owns the recursive collaboration loop
OpenClaw has its own native messaging and session tools
keeping Agency Swarm on top preserves clean run hierarchy in the frontend

When a normal Agency Swarm agent delegates to OpenClawAgent, the streamed events already carry the same parent_run_id, agent_run_id, agent, and callerAgent fields the current frontend uses for nested runs.

Tools And Limits

OpenClawAgent is not the same thing as giving OpenClaw your normal Agency Swarm Python tools. Today, the clean extension paths for OpenClaw itself are:

OpenClaw plugin tools via api.registerTool(...)
MCP servers exposed to OpenClaw
OpenClaw tool policy config such as allowlists and deny lists

Use plain Agency Swarm tools on your normal orchestrator agent. Use OpenClaw plugins or MCP when you need to extend OpenClaw itself.

Host the OpenClaw proxy in the same FastAPI app

If your Agency Swarm app should also start the OpenClaw runtime, attach the proxy to the same FastAPI app:

from agency_swarm import Agency
from agency_swarm.agents import Agent, OpenClawAgent
from agency_swarm.integrations.fastapi import run_fastapi
from agency_swarm.integrations.openclaw import attach_openclaw_to_fastapi

def create_agency(load_threads_callback=None):
    coordinator = Agent(
        name="Coordinator",
        description="Routes work to the OpenClaw worker.",
        instructions="Delegate OpenClaw-specific work to OpenClawWorker.",
        model="gpt-5.6-luna",
    )
    openclaw_worker = OpenClawAgent(
        name="OpenClawWorker",
        description="OpenClaw specialist",
        instructions="Handle the delegated OpenClaw work and return the result.",
    )
    return Agency(
        coordinator,
        communication_flows=[(coordinator, openclaw_worker)],
        load_threads_callback=load_threads_callback,
    )

app = run_fastapi(
    agencies={"support": create_agency},
    app_token_env="APP_TOKEN",
    return_app=True,
)
if app is None:
    raise RuntimeError("FastAPI app failed to start")

attach_openclaw_to_fastapi(app)

When that runtime is meant to be a delegated worker, start the app with:

OPENCLAW_TOOL_MODE=worker python main.py

That worker mode disables the OpenClaw messaging paths that compete with Agency Swarm delegation.

Current limitation

OpenClawAgent can receive delegated work, but it should not be the sender in Agency Swarm communication flows.If you need deeper tool customization inside OpenClaw, use OpenClaw plugins or MCP instead of trying to pass ordinary Agency Swarm Python tools through the wrapper.

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Start With One Import

Use It In An Agency

Choose How To Reach OpenClaw

Collaboration Pattern

Tools And Limits

​Start With One Import

​Use It In An Agency

​Choose How To Reach OpenClaw

​Collaboration Pattern

​Tools And Limits

Start With One Import

Use It In An Agency

Choose How To Reach OpenClaw

Collaboration Pattern

Tools And Limits