@enderfga/claw-orchestrator 3.0.0

package/skills/references/multi-engine.md

@@ -0,0 +1,382 @@
+# Multi-Engine
+
+Claw Orchestrator supports multiple coding CLI engines behind a unified `ISession` interface. Each engine manages its own subprocess, event stream, and cost tracking independently.
+
+## Architecture
+
+```
+SessionManager
+├── engine: 'claude'    → PersistentClaudeSession
+│   └── Wraps: claude CLI (stream-json protocol, persistent subprocess)
+├── engine: 'codex'     → PersistentCodexSession
+│   └── Wraps: codex exec --sandbox workspace-write --json (per-message spawning)
+├── engine: 'codex-app' → PersistentCodexAppServerSession
+│   └── Wraps: codex app-server --listen stdio:// (long-running JSON-RPC; required for /goal)
+├── engine: 'gemini'    → PersistentGeminiSession
+│   └── Wraps: gemini -p --output-format stream-json (per-message spawning)
+├── engine: 'cursor'    → PersistentCursorSession
+│   └── Wraps: agent -p --force --output-format stream-json (per-message spawning)
+└── engine: 'custom'    → PersistentCustomSession
+    └── Wraps: any CLI via user-provided CustomEngineConfig
+```
+
+## Supported Engines
+
+### Claude Code (`engine: 'claude'`)
+
+Default engine. Long-running subprocess with streaming JSON I/O. Tested with Claude Code CLI **2.1.126**.
+
+- Persistent multi-turn conversations
+- Real-time streaming (text, tool_use, tool_result, system events)
+- Session resume via `--resume`
+- Full cost tracking from API usage data
+- Hook lifecycle events (`includeHookEvents`), permission delegation (`permissionPromptTool`), prompt cache optimization (`bare` + `excludeDynamicSystemPromptSections` + `enablePromptCaching1H`), debug control, `--from-pr` resume, and MCP channel subscriptions
+- Fork subagent (`forkSubagent`), tool search (`enableToolSearch`), OpenTelemetry logging toggles (`otelLogUserPrompts`, `otelLogRawApiBodies`), `xhigh` effort tier (Opus 4.7), and `stats.pluginErrors` capture — see [CLI 2.1.121 options in SKILL.md](../SKILL.md) and [tools.md](./tools.md)
+
+> **Behavior changes from upstream Claude CLI 2.1.121** (worth knowing if you set permission rules):
+> - `--agent` / `--print` now enforce agent frontmatter `permissionMode`, `tools`, `disallowedTools` (was advisory). Affects `council` agent personas.
+> - `Bash(find:*)` permission rule no longer auto-approves `find -exec` or `find -delete`. Add explicit rules if you depend on these.
+> - `--dangerously-skip-permissions` also skips prompts for `.claude/skills/` directory. Treat with care.
+> - Distributed tracing context (`TRACEPARENT` / `TRACESTATE`) is automatically forwarded to the child process — set them in the parent before starting the session.
+
+```typescript
+await manager.startSession({
+  name: 'claude-task',
+  engine: 'claude',       // default, can omit
+  model: 'opus',
+  cwd: '/project',
+});
+```
+
+### OpenAI Codex (`engine: 'codex'`)
+
+Wraps the `codex exec` subcommand. Each `send()` spawns a new process. Tested with `codex` CLI **0.128.0**.
+
+- Non-interactive execution via `codex exec --sandbox workspace-write --json` (replaces the deprecated `--full-auto` flag from earlier Codex versions)
+- Real per-turn `usage` from the `turn.completed` JSON event (input, output, cached, reasoning tokens)
+- Per-session continuity: the `thread_id` from the first turn's `thread.started` event is captured and reused via `codex exec resume <id>` for subsequent sends, so the model sees prior turns
+- One-shot execution per message (no persistent subprocess between sends)
+- Working directory passed via `-C` flag
+- Default model: `gpt-5.5`
+- Requires `codex` CLI >= 0.119 (for `exec resume`): `npm install -g @openai/codex`
+- **Does not support `/goal`** — for that, use `engine: 'codex-app'` below
+
+```typescript
+await manager.startSession({
+  name: 'codex-task',
+  engine: 'codex',
+  model: 'gpt-5.5',
+  cwd: '/project',
+  sandboxMode: 'workspace-write', // optional, this is the default
+});
+```
+
+### OpenAI Codex App-Server (`engine: 'codex-app'`)
+
+Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON-RPC subprocess. **Required for `/goal` long-horizon objective support** — Codex's exec subcommand has no slash-command surface.
+
+- Long-running subprocess; one `codex app-server` per session
+- JSON-RPC 2.0 over stdio with v2 protocol method names (`initialize`, `thread/start`, `turn/start`, ...)
+- Real-time streaming via `item/agentMessage/delta` notifications
+- Cumulative token tracking from `thread/tokenUsage/updated` notifications
+- Goal lifecycle observation via `thread/goal/updated` and `thread/goal/cleared` notifications
+- Goal control via the `codex_goal_*` tools (which internally send the `/goal` slash command as user text — see [tools.md](./tools.md#codex-7))
+
+> **Feature-flag risk.** The `goals` feature is marked "under development" in Codex 0.128.0 and has known bugs (e.g. issue #20591). The session class always passes `--enable goals` so it works the moment upstream stabilizes the feature, but during the transition period some goal commands may fail or be silently dropped on the server side. The wrapper layer is unaffected.
+
+```typescript
+await manager.startSession({
+  name: 'codex-goal-task',
+  engine: 'codex-app',
+  model: 'gpt-5.5',
+  cwd: '/project',
+});
+// Then either:
+//   await manager.codexGoalCommand('codex-goal-task', 'build a tic-tac-toe app');
+// or via the codex_goal_set tool:
+//   await tool('codex_goal_set', { name: 'codex-goal-task', objective: 'build a tic-tac-toe app' });
+```
+
+### Google Gemini (`engine: 'gemini'`)
+
+Wraps the `gemini` CLI with `--output-format stream-json`. Each `send()` spawns a new process.
+
+- One-shot execution per message (no persistent subprocess)
+- Working directory carries accumulated changes across sends
+- Real token counts from stream-json `result` events (not estimated)
+- Permission modes: `bypassPermissions` → `--yolo`, `default` → `--sandbox`
+- Requires `gemini` CLI installed: `npm install -g @google/gemini-cli`
+
+```typescript
+await manager.startSession({
+  name: 'gemini-task',
+  engine: 'gemini',
+  model: 'gemini-3.1-pro-preview',
+  cwd: '/project',
+});
+```
+
+### Cursor Agent (`engine: 'cursor'`)
+
+Wraps the Cursor Agent CLI (`agent`) with `--print --force --output-format stream-json`. Each `send()` spawns a new process.
+
+- One-shot execution per message (no persistent subprocess)
+- Working directory via `--workspace` flag
+- Real token counts from stream-json `result` events (camelCase: `inputTokens`, `outputTokens`, `cacheReadTokens`)
+- `--force` enables auto-approval of all file changes
+- `--trust` auto-trusts the workspace without prompting
+- Cursor uses its own model routing (e.g., `sonnet-4`, `gpt-5`, `auto`)
+- Requires Cursor Agent CLI: `curl https://cursor.com/install -fsSL | bash`
+- Binary: `agent` (set `CURSOR_BIN` env var to override)
+
+```typescript
+await manager.startSession({
+  name: 'cursor-task',
+  engine: 'cursor',
+  model: 'sonnet-4',
+  cwd: '/project',
+});
+```
+
+## ISession Interface
+
+All engines implement `ISession`, making them interchangeable at the `SessionManager` level:
+
+```typescript
+interface ISession {
+  // State
+  sessionId?: string;
+  readonly isReady: boolean;
+  readonly isPaused: boolean;
+  readonly isBusy: boolean;
+
+  // Lifecycle
+  start(): Promise<this>;
+  stop(): void;
+  pause(): void;
+  resume(): void;
+
+  // Communication
+  send(message, options?): Promise<TurnResult | { requestId; sent }>;
+
+  // Observability
+  getStats(): SessionStats & { sessionId?; uptime };
+  getHistory(limit?): Array<{ time; type; event }>;
+  getCost(): CostBreakdown;
+
+  // Context
+  compact(summary?): Promise<TurnResult | { requestId; sent }>;
+  getEffort(): EffortLevel;
+  setEffort(level): void;
+
+  // Model
+  resolveModel(alias): string;
+
+  // Events (EventEmitter)
+  on(event, listener): this;
+  emit(event, ...args): boolean;
+}
+```
+
+## Team Tools Across Engines
+
+Team tools (`team_list`, `team_send`) operate on the same virtual-team layer for **every** engine: the "team" is the set of all active sessions managed by SessionManager.
+
+| Engine | `team_list` | `team_send` |
+|--------|------------|-------------|
+| Claude | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Codex | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Gemini | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Cursor | Lists other active SessionManager sessions | Routes via cross-session inbox |
+
+Messages are delivered via the inbox system — idle sessions receive immediately, busy sessions queue for later delivery.
+
+> **Note:** Claude Code does have a native experimental "Agent Teams" feature (v2.1.32+, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), but it is an in-process TUI mechanism with no slash command or stdin-driven messaging — a subprocess wrapper cannot access its mailbox. Plugin team tools therefore use the engine-agnostic virtual team across the board.
+
+## Proxy: Any Model via OpenClaw Gateway
+
+Claude Code CLI only speaks Anthropic protocol. The built-in proxy translates Anthropic ↔ OpenAI format, letting you drive Claude Code with **any model** routed through the OpenClaw gateway.
+
+### Zero Config
+
+If OpenClaw gateway is running, everything is automatic:
+
+```typescript
+// No baseUrl, no env vars, no extra config
+await manager.startSession({
+  name: 'task',
+  engine: 'claude',
+  model: 'openclaw',        // gateway routes to your configured model
+  cwd: '/project',
+});
+```
+
+What happens behind the scenes:
+1. Plugin reads `~/.openclaw/openclaw.json` for gateway port + auth
+2. Starts a local proxy server (random port, auto-managed)
+3. Claude Code CLI sends Anthropic-format requests → proxy converts to OpenAI → gateway → any model
+
+### Manual Config (optional)
+
+Override with environment variables if needed:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GATEWAY_URL` | Auto-detected from openclaw.json | Gateway endpoint (e.g. `http://127.0.0.1:18789/v1`) |
+| `GATEWAY_KEY` | Auto-detected from openclaw.json | Gateway auth password/token |
+| `GEMINI_API_KEY` | - | Direct Gemini API access (bypasses gateway) |
+| `OPENAI_API_KEY` | - | Direct OpenAI API access (bypasses gateway) |
+
+### Architecture
+
+```
+Claude Code CLI (Anthropic format)
+  → Auto-proxy (Anthropic → OpenAI conversion)
+    → OpenClaw Gateway (/v1/chat/completions, model="openclaw")
+      → Any model (Gemini, GPT, local, etc.)
+```
+
+## Custom Engine (`engine: 'custom'`)
+
+Integrate **any** coding agent CLI without writing engine-specific code. You provide a `CustomEngineConfig` that maps your CLI's flags to OpenClaw session concepts.
+
+Two protocol modes:
+- **Persistent** (`persistent: true`) — long-running subprocess with stream-json I/O over stdin/stdout (like Claude Code)
+- **One-shot** (`persistent: false`, default) — new process spawned per `send()` (like Gemini/Codex)
+
+### CustomEngineConfig
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Display name (used in logs, session IDs) |
+| `bin` | string | yes | Binary path or command name |
+| `binEnv` | string | | Env var name that overrides `bin` at runtime |
+| `persistent` | boolean | | `true` = persistent subprocess, `false` = one-shot (default) |
+| `args` | object | yes | CLI flag mappings (see below) |
+| `permissionModes` | object | | Maps OpenClaw mode names to CLI-specific values |
+| `pricing` | object | | `{ input, output, cached? }` per 1M tokens |
+| `contextWindow` | number | | Context window size (default: 200,000) |
+| `env` | object | | Extra environment variables for the CLI process |
+| `sanitizePatterns` | string[] | | Regex patterns to redact from stderr |
+
+### args field
+
+| Key | Example | Description |
+|-----|---------|-------------|
+| `print` | `"-p"` | Non-interactive/print mode flag |
+| `outputFormat` | `"--output-format"` | Output format flag |
+| `outputFormatValue` | `"stream-json"` | Value for stream-json output |
+| `inputFormat` | `"--input-format"` | Input format flag (persistent only) |
+| `inputFormatValue` | `"stream-json"` | Value for stream-json input |
+| `skipPermissions` | `"-y"` | Skip all permissions flag |
+| `permissionMode` | `"--permission-mode"` | Permission mode flag |
+| `model` | `"--model"` | Model selection flag |
+| `systemPrompt` | `"--system-prompt"` | System prompt override flag |
+| `appendSystemPrompt` | `"--append-system-prompt"` | Append system prompt flag |
+| `maxTurns` | `"--max-turns"` | Max agent turns flag |
+| `resume` | `"--resume"` | Session resume flag (persistent only) |
+| `verbose` | `"--verbose"` | Verbose output flag |
+| `replayUserMessages` | `"--replay-user-messages"` | Replay user messages (persistent only) |
+| `includePartialMessages` | `"--include-partial-messages"` | Include partial messages (persistent only) |
+| `effort` | `"--effort"` | Effort level flag |
+| `workspace` | `"--workspace"` | Workspace/cwd flag (one-shot only) |
+| `extra` | `["--trust"]` | Additional static arguments |
+
+### Example: Persistent mode (Claude Code-compatible CLI)
+
+```typescript
+await manager.startSession({
+  name: 'my-agent-task',
+  engine: 'custom',
+  cwd: '/project',
+  customEngine: {
+    name: 'my-agent',
+    bin: 'my-agent',
+    binEnv: 'MY_AGENT_BIN',
+    persistent: true,
+    args: {
+      print: '-p',
+      outputFormat: '--output-format',
+      outputFormatValue: 'stream-json',
+      inputFormat: '--input-format',
+      inputFormatValue: 'stream-json',
+      skipPermissions: '-y',
+      permissionMode: '--permission-mode',
+      model: '--model',
+      systemPrompt: '--system-prompt',
+      appendSystemPrompt: '--append-system-prompt',
+      maxTurns: '--max-turns',
+      resume: '--resume',
+      verbose: '--verbose',
+      replayUserMessages: '--replay-user-messages',
+      includePartialMessages: '--include-partial-messages',
+    },
+    pricing: { input: 3, output: 15, cached: 0.3 },
+    contextWindow: 200_000,
+    sanitizePatterns: ['MY_API_KEY=[^\\s]+'],
+  },
+});
+```
+
+### Example: One-shot mode (simple CLI)
+
+```typescript
+await manager.startSession({
+  name: 'simple-agent-task',
+  engine: 'custom',
+  cwd: '/project',
+  customEngine: {
+    name: 'simple-agent',
+    bin: '/usr/local/bin/simple-agent',
+    persistent: false,  // default
+    args: {
+      print: '-p',
+      outputFormat: '--output-format',
+      outputFormatValue: 'stream-json',
+      skipPermissions: '--yolo',
+      model: '--model',
+      workspace: '--workspace',
+      extra: ['--no-color'],
+    },
+    permissionModes: {
+      bypassPermissions: 'yolo',
+      default: 'sandbox',
+    },
+    pricing: { input: 1, output: 5 },
+  },
+});
+```
+
+### Custom Engine in Council
+
+Custom engines work in council by setting `engine: 'custom'` and `customEngine` on the agent persona:
+
+```typescript
+manager.councilStart('Build feature X', {
+  agents: [
+    {
+      name: 'Planner',
+      emoji: '🟠',
+      persona: 'Architecture expert',
+      engine: 'custom',
+      customEngine: { name: 'my-agent', bin: 'my-agent', persistent: true, args: { ... } },
+    },
+    { name: 'Reviewer', emoji: '🔵', persona: 'Code reviewer', engine: 'claude', model: 'opus' },
+  ],
+  maxRounds: 10,
+  projectDir: '/project',
+});
+```
+
+## Adding a New Built-in Engine
+
+To add a built-in engine (for CLIs that need custom protocol handling beyond what `CustomEngineConfig` supports):
+
+1. Create `src/persistent-<engine>-session.ts` implementing `ISession`
+2. Add the engine name to `EngineType` in `src/types.ts`
+3. Add a case to `SessionManager._createSession()`
+4. Add model pricing to `MODELS[]` in `src/models.ts`
+
+The `ISession` interface is deliberately minimal — each engine handles its own subprocess bootstrapping, I/O protocol, and cleanup internally.
+
+For most third-party CLIs, the `custom` engine with `CustomEngineConfig` is sufficient and requires zero code changes.

package/skills/references/openai-compat.md

@@ -0,0 +1,203 @@
+# OpenAI-Compatible Bridge
+
+> **Cost warning**: This bridge routes requests through the Claude Code CLI, which uses your Claude Max subscription's **extra usage** quota. When OpenClaw's agent loop sends its system prompt (with distinctive tool definitions and agent instructions), Anthropic's backend recognizes this as programmatic/agent traffic and bills it against extra usage — **not** the included allowance. This is by design: the bridge does NOT bypass Anthropic's billing or subscription enforcement. Using it as OpenClaw's primary model backend means every agent turn consumes extra usage credits at standard API rates ($15/M input, $75/M output for Opus). Monitor your usage at [claude.ai/settings/usage](https://claude.ai/settings/usage).
+
+The embedded server exposes a drop-in OpenAI-compatible endpoint so any client that speaks `/v1/chat/completions` can talk to a persistent Claude Code (or Codex / Gemini / Cursor) session. The bridge is designed to serve **two kinds of clients as first-class citizens**:
+
+1. **Upstream agents** that maintain their own conversation state and forward only the latest user turn — OpenClaw's main agent loop, cron jobs, subagents, programmatic clients.
+2. **OpenAI-compatible webchat / labeling tools** that re-send the full transcript on every turn — ChatGPT-Next-Web, Open WebUI, LobeChat, data-labeling pipelines.
+
+Both modes share the same wire protocol; the difference is how a "new conversation" is detected. See [Operator Modes](#operator-modes) below.
+
+## Endpoint
+
+| | |
+|---|---|
+| **URL** | `http://127.0.0.1:18796/v1/chat/completions` |
+| **Models endpoint** | `GET /v1/models` |
+| **Inspection endpoint** | `GET /v1/sessions` (lists active openai-compat sessions with caching stats) |
+| **Auth** | Bearer token via `Authorization: Bearer $OPENCLAW_SERVER_TOKEN` (set the env var to enable; otherwise no auth and the server is loopback-only) |
+| **Wire format** | OpenAI Chat Completions, both streaming (SSE) and non-streaming |
+
+## Session keying
+
+Each request is mapped to a long-running session. Once a session exists, subsequent requests with the same key reuse the same persistent CLI subprocess — so Anthropic prompt caching warms across turns. The key is derived in priority order:
+
+1. **`X-Session-Id` header** — explicit, highest precedence
+2. **`user` field in the request body** — OpenAI standard field, treated as a stable caller identifier
+3. **`sys-<sha1(model + systemPrompt)[0..12]>`** — automatic fallback so unkeyed callers don't all collapse onto a single shared session
+4. **`'default'`** — only when there is no system prompt AND no model (degenerate empty body)
+
+The hash fallback exists because the previous behavior collapsed every unkeyed caller onto one `openai-default` session. In multi-caller setups (OpenClaw routing the main agent + cron jobs + subagents through one gateway) that meant requests serialized against each other and frequently picked up the wrong session's `appendSystemPrompt` — also a privacy leak across distinct callers.
+
+The model is mixed into the hash so that two callers with the same system prompt but different requested models (e.g. one wants `claude-opus-4-6`, another wants `claude-sonnet-4-6`) don't collide and silently get responses from the wrong model.
+
+The full plugin-side session name is `openai-<key>`.
+
+## Operator modes
+
+### Default mode — agent / programmatic clients
+
+When the env var is **not set**, the bridge assumes upstream callers maintain their own conversation transcript and only forward the latest user turn. Sessions are reused indefinitely. The only signal that starts a new conversation is the explicit reset header:
+
+```
+X-Session-Reset: 1
+```
+
+(also accepted: `true`, case-insensitive, with whitespace)
+
+When the header is present, the existing session for this key is stopped and a fresh one is created. Use this from a client that wants "new chat" semantics under your own control — e.g. when your UI's "Clear History" button is pressed.
+
+### Webchat mode — `OPENAI_COMPAT_NEW_CONVO_HEURISTIC=1`
+
+When the env var is set to `1`, the bridge additionally restores a legacy heuristic: a request whose `messages` array contains exactly one non-system message (i.e. the conversation has no assistant turns yet) is treated as a fresh conversation. This is the only signal that webchat frontends (ChatGPT-Next-Web, Open WebUI, LobeChat) emit when the user clicks "New Chat" — they clear their UI transcript and post `[system, user]`.
+
+Without this flag, those frontends would silently continue the previous CLI session and surface stale context the user thought they had cleared.
+
+The env var is read on every request, so ops can flip it via `launchctl setenv` (or equivalent) without restarting the server.
+
+| Mode | Best for | New-conversation signals |
+|---|---|---|
+| **Default** | OpenClaw main agent, cron jobs, subagents, scripted clients | `X-Session-Reset: 1` only |
+| **`HEURISTIC=1`** | ChatGPT-Next-Web, Open WebUI, LobeChat, data labeling tools | `X-Session-Reset: 1` **and** `[system, user]` shape |
+
+## Status webhook
+
+When `OPENAI_COMPAT_STATUS_URL` is set (full HTTP URL), each chat completion sends best-effort `POST` requests with `Content-Type: application/json` and body:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `state` | string | `thinking` (turn started), `working` (a tool is running), or `idle` (turn finished or stream closed). |
+| `activity` | string | Short human-readable line, e.g. `Processing request...`, `Reading: foo.ts`, `Running: npm test...`. |
+| `tool` | string \| null | Tool name when `state === working`, otherwise `null`. |
+
+Failures are ignored (no retries). Use this from a small local HTTP handler that forwards status into your webchat UI.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENCLAW_SERVER_TOKEN` | (unset) | Bearer token for HTTP auth. Set to enable; written to `~/.openclaw/server-token` for the CLI. |
+| `OPENCLAW_RATE_LIMIT` | `300` | Max requests per IP per 60-second sliding window. |
+| `OPENCLAW_CORS_ORIGINS` | (loopback only) | Set to `*` to allow all origins (the `/v1/*` paths already do this). |
+| `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` | (unset) | Set to `1` to enable webchat mode (see above). |
+| `OPENAI_COMPAT_STATUS_URL` | (unset) | If set, the bridge POSTs JSON status updates to this URL (fire-and-forget, 2s timeout). See [Status webhook](#status-webhook). |
+| `OPENCLAW_SERVE_MAX_SESSIONS` | `32` | Max concurrent OpenAI-compat sessions in serve mode. Bumped from the in-plugin default of 5 because each distinct caller now gets its own `sys-<hash>` session. |
+| `OPENCLAW_SERVE_TTL_MINUTES` | `60` | Idle TTL for OpenAI-compat sessions in serve mode. Idle sessions are reaped by a 60s background loop; persisted disk registry is kept for 7 days so a returning caller is auto-resumed. |
+
+## Inspection: `GET /v1/sessions`
+
+Returns a JSON list of every active OpenAI-compat session and its caching statistics:
+
+```bash
+TOKEN=$(cat ~/.openclaw/server-token)
+curl -s http://127.0.0.1:18796/v1/sessions -H "Authorization: Bearer $TOKEN" | jq
+```
+
+Sample response:
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "key": "sys-a3f81c9d0b27",
+      "session_name": "openai-sys-a3f81c9d0b27",
+      "model": "claude-opus-4-6",
+      "cwd": "/home/user/projects",
+      "created": "2026-04-09T03:12:18.441Z",
+      "turns": 14,
+      "tokens_in": 248312,
+      "tokens_out": 38201,
+      "cached_tokens": 198104,
+      "context_percent": 28,
+      "cost_usd": 0.4123
+    }
+  ]
+}
+```
+
+The single most important field is **`cached_tokens`**. If it grows turn-over-turn, the persistent CLI is being reused and Anthropic prompt caching is warming. If it stays at 0, something is killing the session every turn — check that no client is sending `X-Session-Reset` unintentionally and that `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` is not set when it shouldn't be.
+
+## Smoke tests
+
+Run after standing up the server. Set `TOKEN=$(cat ~/.openclaw/server-token)` first.
+
+**1. Two distinct system prompts produce two distinct sessions.**
+
+```bash
+for SYS in 'You are Alice.' 'You are Bob.'; do
+  curl -s http://127.0.0.1:18796/v1/chat/completions \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    -d "{\"model\":\"claude-opus-4-6\",\"messages\":[{\"role\":\"system\",\"content\":\"$SYS\"},{\"role\":\"user\",\"content\":\"hi\"}]}" \
+    | jq -r '.id'
+done
+curl -s http://127.0.0.1:18796/v1/sessions -H "Authorization: Bearer $TOKEN" \
+  | jq '.data[] | {key, model, turns}'
+# Expected: two rows, distinct sys-<hash> keys.
+```
+
+**2. Same system prompt + different model produces two sessions.**
+
+```bash
+for M in claude-opus-4-6 claude-sonnet-4-6; do
+  curl -s http://127.0.0.1:18796/v1/chat/completions \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    -d "{\"model\":\"$M\",\"messages\":[{\"role\":\"system\",\"content\":\"SAME\"},{\"role\":\"user\",\"content\":\"hi\"}]}" > /dev/null
+done
+curl -s http://127.0.0.1:18796/v1/sessions -H "Authorization: Bearer $TOKEN" | jq '.data | length'
+# Expected: 2
+```
+
+**3. `X-Session-Reset: 1` resets cleanly.**
+
+```bash
+SID=smoke-reset
+curl -s http://127.0.0.1:18796/v1/chat/completions \
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID" -H "Content-Type: application/json" \
+  -d '{"model":"claude-opus-4-6","messages":[{"role":"user","content":"remember the word banana"}]}' > /dev/null
+curl -s http://127.0.0.1:18796/v1/chat/completions \
+  -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID" -H "X-Session-Reset: 1" -H "Content-Type: application/json" \
+  -d '{"model":"claude-opus-4-6","messages":[{"role":"user","content":"what word did I just tell you"}]}' \
+  | jq -r '.choices[0].message.content'
+# Expected: model says it has no prior context.
+```
+
+**4. `cached_tokens` grows turn-over-turn (the success metric).**
+
+```bash
+SID=smoke-cache
+PREAMBLE=$(printf 'x%.0s' {1..3000})
+for i in 1 2 3 4; do
+  curl -s http://127.0.0.1:18796/v1/chat/completions \
+    -H "Authorization: Bearer $TOKEN" -H "X-Session-Id: $SID" -H "Content-Type: application/json" \
+    -d "{\"model\":\"claude-opus-4-6\",\"messages\":[{\"role\":\"system\",\"content\":\"long preamble: $PREAMBLE\"},{\"role\":\"user\",\"content\":\"turn $i\"}]}" > /dev/null
+  curl -s http://127.0.0.1:18796/v1/sessions -H "Authorization: Bearer $TOKEN" \
+    | jq ".data[] | select(.session_name == \"openai-$SID\") | {turn: $i, cached_tokens, tokens_in}"
+done
+# Expected: cached_tokens climbs substantially by turn 3-4. If it stays at 0,
+# the persistent CLI is still being killed every turn — regression.
+```
+
+## Error responses
+
+Errors use the OpenAI error envelope:
+
+```json
+{ "error": { "message": "...", "type": "invalid_request_error" } }
+```
+
+| Status | When |
+|---|---|
+| 400 | `messages` empty/missing, no user message, invalid `max_tokens` |
+| 401 | Missing or wrong bearer token (when auth enabled) |
+| 415 | POST without `Content-Type: application/json` |
+| 429 | Rate limited (`OPENCLAW_RATE_LIMIT` exceeded) |
+| 503 | Failed to start a new session (model unavailable, CLI crashed at boot) |
+| 500 | Mid-turn failure |
+
+## Related
+
+- [getting-started.md](./getting-started.md) — install + auth setup
+- [sessions.md](./sessions.md) — what a session is and how the lifecycle works under the hood
+- [tools.md](./tools.md) — the full plugin tool surface (council, ultraplan, etc.)