openclaw-to-caret-migration/research/RESEARCH-02-gateway-internals.md

# Research 02 — openclaw gateway internals

**Subagent:** `ae5ca38f70b1e9626` (Explore)
**Completed:** 2026-04-06 12:50 UTC

## Gateway API surface

WebSocket-first RPC at `ws://localhost:18789/`, with HTTP fallback routes.

### HTTP endpoints

| Method | Path                                | Purpose                                                                 |
|--------|-------------------------------------|-------------------------------------------------------------------------|
| POST   | `/hooks/{hookPath}/wake`            | Trigger heartbeat or immediate agent wake. Body: `{text, mode}`.        |
| POST   | `/hooks/{hookPath}/agent`           | Spawn isolated agent session. Body: `{agentId, sessionKey, message, channel, to, deliver, model, thinking, timeoutSeconds}`. Returns `{ok, runId}`. Idempotency: 60s dedup by `Authorization + X-Idempotency-Key`. |
| POST   | `/tools/invoke`                     | Call a tool directly. Body: `{tool, action, args, sessionKey, dryRun}`. |
| GET    | `/health` / `/healthz` / `/ready`   | Liveness / readiness probes.                                            |
| GET    | `/` and `/app/*`                    | Built-in web control UI (the SPA we saw when probing earlier).         |
| Plugin-registered routes            | Custom plugin HTTP endpoints; auth enforced per plugin's `requiresAuth`.|

### Authentication

- `Authorization: Bearer <token>` OR `X-OpenClaw-Token: <token>` header
- Token sources: `gateway.auth.token` in config, `OPENCLAW_GATEWAY_TOKEN` env var, device token at `~/.openclaw/credentials/device-token`
- WebSocket auth: passed in URL query `?token=...` or connect frame

### RPC method RBAC scopes

- READ: `health`, `channels.status`, `sessions.list`, `cron.list`, `node.list`, ...
- WRITE: `send`, `agent`, `agent.wait`, `wake`, `node.invoke`, ...
- ADMIN: `config.set`, `agents.create`, `cron.add`, `sessions.reset`, ...
- APPROVALS, PAIRING: narrower scoped methods.

## Session spawn recipe

### The primary spawn path

```
Client RPC request → gateway dispatch → agentHandlers.agent() → agentCommandFromIngress() → in-process task
```

Not a child process. Sessions run as in-process tasks under the gateway. Each session's message history lives in `~/.openclaw/sessions/*.jsonl`.

### Agent identity & tool allowlist resolution at spawn

1. Resolve agent ID from `params.agentId` or `agents.defaults.id`.
2. Resolve tool allowlist: first match wins among `agents[id].tools.allow/deny` → `agents[id].toolProfile` → `agents.defaults.tools.*` → subagent role restrictions.
3. Hard-deny list always wins (`exec.approval.*`, `node_invoke_system_run`, etc.).
4. Runtime context: `runtime="subagent"` (sandboxed) or `"acp"` (host access).
5. Workspace and session store selected from agent's config.

### Subagent / ACP spawn (for nesting)

```typescript
const result = await spawn({
  task: "Analyze the attached image",
  mode: "run" | "session",
  thread: true,
  agentId: "analyzer"
});
// Returns { status, childSessionKey: "subagent:uuid", runId }
```

Sessions prefixed `subagent:*` run in a sandbox (gVisor or Docker container). `acp:*` runs on host under parent's cwd. Parent sees subagent output but can't reach into its filesystem.

## Cron / heartbeat mechanism

**It's not a crontab. It's an in-process scheduler built into the gateway.**

### Heartbeat loop

1. At gateway boot, `startHeartbeatRunner()` in `src/infra/heartbeat-runner.ts` starts.
2. For each agent where `agents[id].heartbeat.enabled == true`:
   - Parse `heartbeat.every` interval
   - Calculate next-due time
   - Set a timer (internally a `setInterval` that checks wall clock every ~10s)
3. When timer fires:
   - Read `memory/heartbeat-state.json` (for dedup / avoid double-fires)
   - Read pending `memory/system-events/` (queued by cron jobs, exec completions, etc.)
   - Build a prompt from heartbeat config + pending events
   - Spawn agent with `extraSystemPrompt` = heartbeat prompt
   - Agent responds (may be empty)
   - Update heartbeat state file

### Cron service (parallel to heartbeat)

- Class: `CronService` in `src/cron/service.ts`
- Config: `cron.jobs[].schedule` (cron expression)
- State: `~/.openclaw/memory/cron/store.json` with `{id, schedule, agentId, prompt, lastRunMs, nextDueMs}`
- Run logs: `~/.openclaw/memory/cron/runs/`
- Can enqueue `system-events/*.json` that heartbeat picks up next cycle.

### Ad hoc triggers

- `openclaw wake --now` fires heartbeat immediately
- `openclaw cron run <id> --force` fires a cron job immediately
- `openclaw system-event "text"` queues an event for next heartbeat

## Plugin discovery and wiring

### Loader

`src/plugins/loader.ts` → `loadOpenClawPlugins()`:

1. Scan `~/.openclaw/plugins/` directory
2. Read each plugin's manifest (plugin.yaml or package.json exports)
3. Dynamic-import plugin module via jiti
4. Initialize `PluginRuntime` with sandbox context, gateway request handler, scoped filesystem access
5. Register plugin's hooks (lifecycle events) and gateway methods (HTTP/RPC)

### Example: Telegram plugin

- Starts a polling loop calling Telegram Bot API `getUpdates()`
- For each incoming message, calls `dispatchGatewayMethod("agent", {...})` to spawn a Claude session
- Claude's response routed back via plugin's send handler

## Replacement difficulty matrix

| Component                                  | Difficulty | Notes                                                         |
|--------------------------------------------|-----------|----------------------------------------------------------------|
| Session storage (JSONL messages)           | Easy      | Simple file format, adopt as-is                               |
| Heartbeat scheduler                        | Medium    | Timer logic easy; state/dedup is the work                     |
| Cron service                               | Medium    | Schedule parsing + state persistence                          |
| Hook API (POST /hooks)                     | Easy      | Stateless request/response                                    |
| RPC / WebSocket protocol                   | Hard      | Custom protocol with dedup, framing, RBAC                     |
| Tool policy and allowlist resolution       | Medium    | Glob pattern + inheritance hierarchy                          |
| Plugin system                              | Hard      | Dynamic loading, sandboxed runtime contexts                   |
| Subagent / ACP spawn                       | Hard      | Nesting, thread binding, runtime isolation                    |
| Delivery system (Telegram, Slack, etc.)    | Hard      | Multi-channel abstraction; tightly coupled                    |
| Control UI                                 | Medium    | React SPA; can be replaced if protocol stays compatible       |
| Authentication and RBAC                    | Medium    | Token validation + scope checks                               |

## Don't reinvent this

1. **Session transcript storage** (`src/config/sessions/`) — JSONL with dedup, compression, archival. Adopt.
2. **Plugin SDK** (`src/plugin-sdk/`) — type-safe hook runners, tool registration. Many plugins depend on it.
3. **Tool policy resolution** (`src/agents/tool-policy*.ts`) — battle-tested glob + inheritance. 2-3 weeks to replace.
4. **Delivery system** (`src/infra/outbound/`) — routes to Telegram/Slack/Discord/WhatsApp with retries and dedup. Very tightly coupled.
5. **Exec approvals** (`src/infra/exec-approvals-*`) — human-in-the-loop for sensitive ops. Keep if you plan approvals.
6. **Hot-reload config** (`src/gateway/config-reload.ts`) — atomic updates with broadcasts.

## Migration path summary

To replace openclaw's orchestration while keeping agents and tools:

1. Adopt existing session storage (or thin DB adapter)
2. Keep plugin system — at minimum the hook-runner pattern for startup/shutdown
3. Reimplement heartbeat scheduler as a background job
4. Reimplement cron service with same semantics
5. Build your own HTTP/RPC gateway, keeping `/tools/invoke` signature for compatibility
6. Map hook API to your agent spawn endpoint
7. Reimplement tool policy resolution using your config schema
8. Adopt delivery system or build equivalent (biggest lift)

**Estimated effort:** 4-8 weeks competent team, assuming Claude SDK agent harness is mostly intact and session/tool abstractions reused.

## Caret's conclusion

Full orchestration replacement is a 4-8 week project. That's NOT what I want.

**What I DO want is much smaller**: the specific slice that handles Gitea webhook events → policy enforcement → optional agent wake-up. That's a ~600-800 line bun listener, not a whole orchestrator. Everything else (session storage, plugin SDK, delivery system, tool policy) I keep depending on openclaw for, or reuse Claude Code's native primitives (Channels plugins, CronCreate, hooks).

The research confirms the right shape: build a **minimal webhook listener + event router + script fan-out** that can run standalone, and wire it into Claude Code's native Channels mechanism for the judgment wake-ups. Don't try to replicate the whole orchestrator.