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.

Related topics#