Codebase Tour: CLI → Gateway → Agent

This is a top-down tour. The goal isn’t to read every file—it’s to build a reliable mental map so you can follow the call chain.

The 6 questions to keep in your head

1. Where does the CLI start (entry + command dispatch)?
2. What is the Gateway “control plane” (connect/auth/method calls/subscriptions)?
3. How do channels deliver inbound messages (shared envelope)?
4. How does routing pick an agentId and sessionKey (and keep groups isolated)?
5. How does a reply get produced (agent loop: run → attempt → streaming)?
6. How are tools executed safely (sandbox + tool policy + approvals)?

One-line end-to-end flow

Channel inbound → Gateway normalizes + routes → enqueue by sessionKey (lane) → trigger the agent runtime → stream a reply → (optionally) run tools → deliver back to the same channel.

Start with these docs (in order):

• TypeBox protocol + method catalog
• Session tool (routing + session keys)
• Agent loop
• Queue + lanes

Two planes in the Gateway

Control plane

• Client connects
• Calls methods (e.g. chat.send)
• Subscribes to event streams (chat/agent/presence/tick)

See:

• Gateway protocol
• Control UI (how it uses WS)

Data plane

• chat.send starts a run (non-blocking ACK); results arrive via streamed events
• logs.tail powers Control UI log tailing

Routing + isolation (why conversations don’t leak)

Routing aims for:

• Deterministic delivery (reply goes back to the same channel)
• Isolation (groups/channels get separate session keys)

Key concept: inbound message → resolve agentId/sessionKey → enqueue on lane: session:<key> to preserve ordering.

See:

• Multi-agent routing
• Sessions
• Queue + lanes

Tool execution: why there are three layers

OpenClaw separates risk into:

1. Sandbox (where it runs)
2. Tool policy (what it’s allowed to do)
3. Approvals (when a human is required)

See:

• Sandbox
• Sandbox vs tool policy vs elevated

The fastest practical way to learn

1. Run a chat once (openclaw dashboard / Control UI).
2. Tail logs: openclaw logs --follow, note the runId from a chat.send.
3. Read: TypeBox → session tool → agent loop → queue.
4. When stuck, use: logging / troubleshooting / security docs.