agency-swarm-cn-git/docs/core-framework/third-party-agents/openclaw-agent.mdx

---
title: "OpenClawAgent"
description: "Use an OpenClaw worker inside an Agency Swarm agency."
icon: "lobster"
---

`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

```python
from agency_swarm.agents import OpenClawAgent
```

## Use It In An Agency

```python
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.4-mini",
)

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

<Tabs>
  <Tab title="Same FastAPI app">

```python
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`.
  </Tab>
  <Tab title="Custom host and port">

```python
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.
  </Tab>
  <Tab title="External OpenClaw server">

```python
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.
  </Tab>
</Tabs>

## 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

<Info>
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.
</Info>

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

<Accordion title="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:

  ```python
  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.4-mini",
      )
      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:

  ```bash
  OPENCLAW_TOOL_MODE=worker python main.py
  ```

  That worker mode disables the OpenClaw messaging paths that compete with Agency Swarm delegation.
</Accordion>

<Accordion title="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.
</Accordion>