openclaw/docs/agents.md

---
summary: "Current agent integration: Pi as the sole coding agent with config examples"
read_when:
  - Changing agent invocation or defaults
---
<!-- {% raw %} -->
# Agent Integration 🤖

CLAWDIS ships with a single coding-agent path: **Pi** (RPC mode). Legacy Claude/Codex/Gemini/Opencode integrations have been removed.

## Default behavior

If you don’t configure `inbound.reply`, CLAWDIS uses the bundled Pi binary in RPC mode:
- command: `pi --mode rpc {{BodyStripped}}`
- per-sender sessions (stored under `~/.clawdis/sessions/*.jsonl`)
- `/new` starts a fresh session

This is usually enough for a personal assistant setup; add `inbound.allowFrom` to restrict who can trigger it.

If you keep an `AGENTS.md` (and optional “memory” files) for the agent, set `inbound.reply.cwd` to that workspace so Pi runs with the right context.

## Custom agent command (still Pi)

To override the agent command, configure `inbound.reply.mode: "command"`:

```json5
{
  inbound: {
    reply: {
      mode: "command",
      command: ["pi", "--mode", "rpc", "{{BodyStripped}}"],
      timeoutSeconds: 1800,
      agent: { kind: "pi", format: "json" }
    }
  }
}
```

Notes:
- CLAWDIS forces `--mode rpc` for Pi invocations (even if you pass `--mode json/text`).
- If your `command` array omits `{{Body}}`/`{{BodyStripped}}`, CLAWDIS still synthesizes the prompt body for RPC mode.

## Sessions

Session behavior lives under `inbound.reply.session`:

```json5
{
  inbound: {
    reply: {
      session: {
        scope: "per-sender",
        resetTriggers: ["/new", "/reset"],
        idleMinutes: 10080,
        sendSystemOnce: true,
        sessionIntro: "You are Clawd. Be a good lobster."
      }
    }
  }
}
```

Defaults when `session` is enabled:
- Session files are written to `~/.clawdis/sessions/{{SessionId}}.jsonl`.
- Resume adds `--continue` automatically (Pi needs it to load prior messages).

## Heartbeats

If you enable `inbound.reply.heartbeatMinutes`, CLAWDIS periodically runs a heartbeat prompt (default: `HEARTBEAT /think:high`).

- If the agent replies with `HEARTBEAT_OK` (exact token), CLAWDIS suppresses outbound delivery for that heartbeat.
- If you want a different command for heartbeats, set `inbound.reply.heartbeatCommand`.

```json5
{
  inbound: {
    reply: {
      heartbeatMinutes: 30,
      heartbeatCommand: ["pi", "--mode", "rpc", "HEARTBEAT /think:high"]
    }
  }
}
```

## Tool streaming (RPC)

RPC mode emits structured tool lifecycle events (start/result) and assistant output. These are:
- logged to `/tmp/clawdis/…`
- streamed over the Gateway WS to clients like WebChat and the macOS app

## Browser helpers

If you enable the clawd-managed browser (default on), the agent can use:
- `clawdis browser status` / `tabs` / `open <url>` / `screenshot [targetId]`
- `clawdis browser snapshot --format ai` (returns an AI snapshot with `[ref=…]` ids)
- `clawdis browser click <ref>` (click by ref from an AI snapshot)

This uses a dedicated Chrome/Chromium profile (lobster-orange by default) so it doesn’t interfere with your daily browser.

## Debugging `clawdis-mac` errors

When the agent runs `clawdis-mac` (often over SSH), the CLI prints compact, human-readable errors by default.

- To get the full `NSError` dump (domain/code/userInfo), rerun with `CLAWDIS_MAC_VERBOSE_ERRORS=1` in the environment.

---

*Next: [Group Chats](./group-messages.md)* 🦞
<!-- {% endraw %} -->