Agents

OpenClaw agents are the AI assistants that receive messages from channels, maintain context through sessions, call tools, and produce responses. The system ships with a built-in agent runtime (id openclaw) that handles the full turn lifecycle inside the Gateway process.

Interacting with an agent

Use the CLI to send a direct message to the default agent:

openclaw agent --message "Summarize the last session"
openclaw agent --message "Fix the bug in index.ts" --thinking low

The --thinking flag controls the reasoning level passed to the model. The command delivers the message through connected channels and returns the agent's reply.

Configuration

Agent behavior is driven by the agents section in ~/.openclaw/openclaw.json (JSON5). The agents.defaults object supplies baseline settings for every agent:

{
  "agents": {
    "defaults": {
      "model": "gpt-4o",
      "workspace": "~/my-workspace",
      "sandbox": { "mode": "strict" },
      "heartbeat": { "every": "30m", "target": "last" },
      "skills": ["core", "web"],
      "compaction": { "enabled": true },
      "contextPruning": { "enabled": true }
    }
  }
}

Override any field per agent under agents.list[]. Channel and peer routing is controlled by the top-level bindings[] array, which maps (channel, account, peer) patterns to a specific agentId.

See the full schema with openclaw config schema.

Built-in runtime behaviors

The default runtime executes agent turns with these core capabilities:

  • Tool execution: Registered tools (coding, channel actions, web, etc.) are invoked inside the turn. Results stream back to the model and to connected clients. Non-main sessions run under the configured sandbox policy.
  • Compaction: Automatic or manual (/compact) reduction of transcript size while preserving state. Checkpoints are stored so a session can resume from a compacted state.
  • Heartbeats: Periodic background turns scheduled by agents.defaults.heartbeat.every. The target and directPolicy fields control delivery and visibility.
  • Sub-agent dispatch: Long-running or specialized work can spawn isolated sub-agents via session tools. Sub-agents carry lineage metadata (spawnedBy, spawnDepth) and appear separately in sessions.list.
  • Model fallback: When the primary model or provider fails, the runtime automatically tries configured fallbacks from agents.defaults.model.

All of these surfaces are active for the built-in runtime and participate in the same session and delivery machinery.

Runtime selection

The default runtime id is openclaw. When additional runtimes are registered by plugins, you can select them explicitly or use the special value auto (which prefers a plugin harness when one matches the request).

Resource packages (skills, prompts, themes) are declared in package metadata or discovered from conventional directories and loaded into the active agent.

Updated June 17, 2026