@enderfga/claw-orchestrator 7.14.0 → 7.16.0

package/skills/references/dashboard.md

@@ -5,9 +5,9 @@ HTTP server. It lets you **launch and observe** Council sessions, Autoloop
 runs and Forge (Ultraapp) builds, and browse durable workflow runs, from a
 browser — no CLI, no webchat, no plugin tool calls needed.
 
-URL: `http://127.0.0.1:18796/dash` (local) or whatever public hostname you
-front the embedded server with (the recommended setup uses a path-based
-reverse proxy, e.g. `https://<your-host>/dash`).
+URL: `http://127.0.0.1:18796/dash` (or `/dashboard`) locally, or whatever public
+hostname you front the embedded server with (the recommended setup uses a
+path-based reverse proxy, e.g. `https://<your-host>/dash`).
 
 ## Tabs
 
@@ -23,6 +23,17 @@ view-only (start runs with `workflow_start`). Council and Autoloop open a
 modal form (because they need workspace/task input); Forge POSTs an empty
 body and drops you into an interview (the spec is built conversationally).
 
+- The **Council** form takes a task, a project directory and an optional round
+  limit (default 15). It starts a fixed team of three Claude agents — a planner,
+  an implementer and a reviewer — with `bypassPermissions`. Use `council_start`
+  for your own personas, engines or models.
+- The **Autoloop** form takes a workspace and an optional Planner model; the run
+  id is generated. Other role choices are available through `POST /autoloop/new`
+  or `autoloop_start`.
+
+The header shows the spend recorded in the run ledger over the last 24 hours,
+across every engine, refreshed every 30 seconds.
+
 ## Standalone deployment
 
 The recommended way to run the dashboard 24/7 is a separate `clawo serve`
@@ -117,32 +128,36 @@ that both read the file always agree.
 
 ## Resuming a terminated autoloop run
 
-Opening a run whose `status` is `terminated` (because its process has
-exited, or because you're viewing it cross-process) fetches
-`/autoloop/<id>/chat_history`, replays the conversation into the Planner pane,
-and shows a green **Resume run** button in the topbar. The same button is shown
-for any live paused run, and it follows later SSE state: a pause adds it, and
-returning to an active status removes it. Timeout fields are included only when
-`pending_dispatch` exists; an ordinary or activity-lease pause resumes with
-an empty timeout body. Clicking it POSTs `/autoloop/<id>/resume`;
-the orchestrator re-attaches the Planner (reusing the persisted Claude
-session ID when available, so Claude's context picks up where it left
-off) and the dashboard reconnects to `/events` for live updates.
+Opening any autoloop run fetches `/autoloop/<id>/chat_history` and replays it
+into the three panes, so the conversation survives a page refresh. A green
+**Resume run** button appears in the topbar when the run is not live in this
+server's process (it has exited, or another process owns it), or when its status
+is `paused` or `terminated`. It follows later SSE state: a pause adds it, and
+returning to an active status removes it.
+
+Clicking it POSTs `/autoloop/<id>/resume`. Timeout fields are included only when
+`pending_dispatch` exists — the button then sends that dispatch's id with a
+send timeout one minute longer than the one that expired; an ordinary or
+activity-lease pause resumes with an empty timeout body. The orchestrator
+re-attaches the Planner (reusing its persisted conversation where the engine
+supports resume, so its context picks up where it left off) and the dashboard
+reconnects to `/events` for live updates.
 
 If the run used a **custom engine** for any role, the button first asks
 `/autoloop/<id>/resume-requirements` and prompts for one reference name per
 role — the name of a `CLAWO_CUSTOM_ENGINE_<NAME>` variable on the orchestrator
-host. The config itself is never stored and never sent; only the name is.
+host, whose value is the JSON custom-engine config. The config itself is never
+stored and never sent; only the name is.
 
 A run without a `chat.jsonl` or a persisted session still resumes, with a blank
-Planner pane and a fresh Claude context.
+Planner pane and a fresh Planner context.
 
 ## Cross-process visibility
 
 Every council, autoloop and workflow run is a durable kernel run stored under
-`~/.claw-orchestrator/wf/`, so the dashboard lists runs started by any process —
-the OpenClaw plugin, `clawo serve`, or the CLI — sorted newest-first, until the
-run records are deleted. Forge runs are read from
+`~/.claw-orchestrator/wf/` (or `$CLAWO_WF_DIR`), so the dashboard lists runs
+started by any process — the OpenClaw plugin, `clawo serve`, or the CLI — sorted
+newest-first, until the run records are deleted. Forge runs are read from
 `~/.claw-orchestrator/ultraapps/`.
 
 ## Reverse-proxy integration
@@ -172,11 +187,12 @@ launchctl kickstart -k "gui/$(id -u)/com.clawo.serve"
 
 ## Runs tab
 
-Lists durable workflow runs. Because runs are checkpointed to
+Lists the 50 most recent durable workflow runs. Because runs are checkpointed to
 disk, this sees runs started by other processes and by earlier sessions, not just
 what the current server started.
 
-Each row shows the run state and its verdict as one of three things:
+Each row shows the run state, its recorded cost when there is one, and its verdict
+as one of three things:
 
 - **verified** — an acceptance contract ran and passed.
 - **refuted** — a contract ran and a required check failed.

package/skills/references/getting-started.md

@@ -13,9 +13,26 @@ clawo serve
 # Drive sessions from the command line
 clawo session-start myproject -d ~/project
 clawo session-send myproject "fix the auth bug"
+clawo session-status myproject
 clawo session-stop myproject
 ```
 
+`clawo serve` listens on `127.0.0.1:18796` (`-p/--port`, `-H/--host`; `OPENCLAW_SERVER_HOST`
+also sets the bind address) and prints the dashboard URL, `http://127.0.0.1:18796/dashboard`.
+Apart from `clawo engines` and `clawo acp`, which run locally, the other `clawo` commands are
+HTTP clients of that server: they read its address from `CLAWO_API_URL` (default
+`http://127.0.0.1:18796`) and its token as described under
+[Embedded Server Authentication](#embedded-server-authentication), and a request that fails or
+cannot reach the server exits with status 1. `session-start -e <engine>` picks the engine
+(default `claude`; `codex`, `codex-app`, `agy`, `grok`, `opencode`, `acp` with
+`--acp-agent <id>`, `custom` with `--custom-engine <id>`);
+`session-send --message-file <file>` sends a long message, and `--json` on `session-send` and
+`session-status` prints the full result. See [cli.md](./cli.md) for every command.
+
+`clawo serve` does not read the OpenClaw plugin configuration below; it allows 32 concurrent
+sessions and reaps idle ones after 60 minutes (`OPENCLAW_SERVE_MAX_SESSIONS`,
+`OPENCLAW_SERVE_TTL_MINUTES`).
+
 ### As OpenClaw Plugin
 
 ```bash
@@ -23,9 +40,11 @@ openclaw plugins install @enderfga/claw-orchestrator --dangerously-force-unsafe-
 openclaw gateway restart
 ```
 
-> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Antigravity / Grok Build / OpenCode CLI subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
+> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Antigravity / Grok Build / OpenCode / ACP agent subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
 
-Agents automatically get access to all session, council, and management tools.
+Agents automatically get access to all session, council, and management tools. The plugin starts
+the same embedded HTTP server on the first tool call (set `CLAWO_NO_EMBEDDED_SERVER=1` to skip
+it), so the `clawo` CLI and the dashboard work against a running plugin too.
 
 ### TypeScript Library
 
@@ -49,12 +68,15 @@ await manager.stopSession('backend-fix');
 ## Requirements
 
 - **Node.js >= 22**
-- **Claude Code CLI >= 2.1** — `npm install -g @anthropic-ai/claude-code`
+- **Claude Code CLI >= 2.1.259** — `npm install -g @anthropic-ai/claude-code`. A session with no permission-prompt tool passes `--permission-prompts none`, which 2.1.259 added
 - **OpenClaw >= 2026.3.0** — for plugin mode (optional)
-- **OpenAI Codex CLI >= 0.112** — `npm install -g @openai/codex` (optional, for codex engine)
+- **OpenAI Codex CLI** — `npm install -g @openai/codex` (optional). The `codex` engine needs >= 0.119 for `codex exec resume`, which every send after the first uses. The `codex-app` engine and its goal RPCs are tested with 0.164.0
 - **Antigravity CLI** — `curl -fsSL https://antigravity.google/cli/install.sh | bash` (optional, for the `agy` engine — Google's successor to the sunset Gemini CLI)
-- **Grok Build CLI** — optional, for the `grok` engine
-- **OpenCode CLI** — `npm install -g opencode-ai` (optional, for the `opencode` engine)
+- **Grok Build CLI** — see `x.ai/cli` (optional, for the `grok` engine)
+- **OpenCode CLI 1.x** — `npm install -g opencode-ai` (optional, for the `opencode` engine). OpenCode 2 (the `@opencode/cli` package) is refused at session start
+- **An ACP agent** — optional, for the `acp` engine: any agent that serves the Agent Client Protocol on stdio, such as Kimi Code (`kimi acp`), dsh (`dsh --profile acp`) or `opencode acp`
+
+Tested versions of each engine are in the [README](../../README.md#engine-compatibility).
 
 ### Engine Authentication
 
@@ -65,6 +87,7 @@ Each engine requires its own authentication before use:
 - **Antigravity** — run `agy` once and complete the Google OAuth login
 - **Grok** — run `grok` once and sign in (grok.com account or `XAI_API_KEY`)
 - **OpenCode** — run `opencode auth login`, or set a provider key such as `ANTHROPIC_API_KEY`
+- **ACP agents** — the agent's own login or environment (for example `KIMI_MODEL_*` for Kimi Code, `DEEPSEEK_API_KEY` for dsh); see [Multi-Engine](./multi-engine.md#acp-agents-engine-acp)
 
 The plugin does not manage authentication — it expects each CLI to be ready to run.
 
@@ -76,7 +99,9 @@ Authentication on the embedded HTTP server (used by the CLI and standalone mode)
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `OPENCLAW_SERVER_TOKEN` | Unset: a random token is generated. Set to a value: use that token. Set to `disabled`: turn auth off (single-user hosts only) |
 
-On start the server writes the token to `~/.openclaw/server-token` (mode 0600) and reuses it across restarts; the CLI reads it automatically. Every request except `/health` must carry it as `Authorization: Bearer <token>` or the `clawo_auth` cookie. Browsers sign in once via `/login?token=<token>&redirect=/dashboard`, which sets the cookie.
+On start the server writes the token to `~/.openclaw/server-token` (mode 0600) and reuses it across restarts; delete the file and restart the server to rotate it. Every request except `/health` must carry it as `Authorization: Bearer <token>`, the `clawo_auth` cookie, or a `?token=` query parameter. Browsers sign in once via `/login?token=<token>&redirect=/dashboard`, which sets the cookie and redirects, so the token does not stay in the address bar.
+
+The CLI finds the token on its own: `CLAWO_AUTH_TOKEN`, then `OPENCLAW_SERVER_TOKEN`, then the token file.
 
 ### OpenAI-Compatible Endpoint
 
@@ -97,7 +122,7 @@ See [openai-compat.md](./openai-compat.md) for the full session-keying rules, `X
 
 ## Configuration
 
-In `~/.openclaw/openclaw.json`:
+In plugin mode, in `~/.openclaw/openclaw.json`:
 
 ```jsonc
 {
@@ -107,16 +132,10 @@ In `~/.openclaw/openclaw.json`:
         "enabled": true,
         "config": {
           "claudeBin": "claude",
-          "defaultModel": "claude-opus-5-5",
           "defaultPermissionMode": "acceptEdits",
           "defaultEffort": "auto",
           "maxConcurrentSessions": 5,
           "sessionTtlMinutes": 120,
-          "proxy": {
-            "enabled": false,
-            "bigModel": "gemini-3.1-pro-preview",
-            "smallModel": "gemini-3-flash-preview",
-          },
         },
       },
     },
@@ -124,13 +143,28 @@ In `~/.openclaw/openclaw.json`:
 }
 ```
 
+| Key                     | Default       | Meaning                                                                                                                                                                                      |
+| ----------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claudeBin`             | `claude`      | Claude Code binary                                                                                                                                                                           |
+| `defaultModel`          | unset         | Model for a session that names none, on an engine that runs that model; the claude engine takes any model. Other engines, and every engine when it is unset, run their own default           |
+| `defaultPermissionMode` | `acceptEdits` | Permission mode for a session that names none                                                                                                                                                |
+| `defaultEffort`         | `auto`        | Effort for a session that names none                                                                                                                                                         |
+| `maxConcurrentSessions` | `5`           | Most sessions open at once; a start beyond it is refused                                                                                                                                     |
+| `sessionTtlMinutes`     | `120`         | Idle sessions are stopped after this long                                                                                                                                                    |
+| `pricingOverrides`      | none          | Per-model rates, USD per 1M tokens: `{"gpt-5.5": {"input": 0, "output": 0, "cached": 0}}` for a flat-rate plan. See [Zeroing a model's pricing](./observability.md#zeroing-a-models-pricing) |
+| `proxy.enabled`         | on            | `false` stops the plugin from registering the multi-model proxy routes on the OpenClaw gateway                                                                                               |
+
 ## Next Steps
 
 - [Sessions](./sessions.md) — persistent session lifecycle and management
 - [Session Inbox](./inbox.md) — cross-session messaging
-- [Multi-Engine](./multi-engine.md) — one interface over Claude Code, Codex, Antigravity, Grok Build, OpenCode and custom CLIs
+- [Multi-Engine](./multi-engine.md) — one interface over Claude Code, Codex, Antigravity, Grok Build, OpenCode, ACP agents and custom CLIs
 - [Council](./council.md) — multi-agent collaboration with consensus voting
 - [Ultraplan & Ultrareview](./ultra.md) — deep planning and fleet code review
+- [Workflows](./workflow.md) — durable runs and the `solve`, `council`, `fanout` and `goal` templates
+- [Verification](./verification.md) — acceptance contracts the runtime checks itself
+- [Observability](./observability.md) — the run ledger and spend caps
+- [Dashboard](./dashboard.md) — the browser UI served at `/dashboard`
 - [Tools Reference](./tools.md) — complete tool API reference (78 tools)
 - [CLI Reference](./cli.md) — command-line interface
 - [MCP Server](./mcp.md) — expose the tools to any MCP host

package/skills/references/inbox.md

@@ -15,15 +15,17 @@ Session A (planner)          SessionManager           Session B (coder)
      │                            │    queue in inbox      │
      │                            │         │              │
      │                            │    ... B becomes idle  │
-     │                            ├── deliverInbox(B) ────►│ deliver queued msgs
+     │     caller ── deliverInbox(B) ─────────────────────►│ deliver queued msgs
 ```
 
-- **Idle sessions** receive messages immediately as a new user turn
-- **Busy sessions** have messages queued in an inbox (max 200 messages)
+- **Idle sessions** (ready and not busy) receive messages immediately as a new user turn. The call does not wait for the recipient's reply
+- **A delivered message is an ordinary turn**: it goes through the same send path as `session_send`, so the recipient's spend cap applies and the turn gets its own run-ledger row and a place in the conversation a handoff carries
+- **Busy sessions** have messages queued in an inbox (max 200 messages); so does an idle session whose turn could not start — for example one that has reached its spend cap
+- **Queued messages wait for a caller**: nothing delivers them on its own. Call `sessionDeliverInbox()` once the session is idle
 - Messages are wrapped in `<cross-session-message>` XML tags
 - Supports broadcast to all sessions via `to: "*"`; a broadcast skips the sender
-- Sender and target must be existing sessions, otherwise the call fails
-- Returns `{ delivered, queued }`
+- Sender and target must be live sessions on this SessionManager, otherwise the call fails
+- Returns `{ delivered, queued }`. On a broadcast, `delivered` is true when any recipient got the message at once and `queued` when any recipient's copy was queued; a broadcast that fails for one recipient is logged and does not stop the others
 
 ## Usage
 
@@ -49,7 +51,7 @@ const all = manager.sessionInbox('coder', false);
 
 ### Deliver Queued Messages
 
-When a session finishes a task and becomes idle, deliver its queued messages:
+When a session finishes a task and becomes idle, deliver its queued messages. All unread messages go in one turn, each in its own envelope, and are marked read. The call does not wait for the reply; if the turn cannot start (spend cap reached) it throws and the messages stay unread:
 
 ```typescript
 const count = await manager.sessionDeliverInbox('coder');
@@ -64,6 +66,8 @@ console.log(`Delivered ${count} queued messages`);
 | `session_inbox`         | Read inbox messages                     |
 | `session_deliver_inbox` | Deliver queued messages to idle session |
 
+`team_send` (CLI: `clawo session-team-send`) sends through the same inbox, with the summary `team message from <sender>`. The three tools above have no CLI command.
+
 ## Message Format
 
 Messages delivered to sessions are wrapped in XML:
@@ -74,10 +78,11 @@ The auth module needs rate limiting. Please add a token bucket...
 </cross-session-message>
 ```
 
-Attribute values are XML-escaped, and any `cross-session-message` tag inside the body is escaped, so a sender cannot forge a second envelope.
+The `summary` attribute is present only when a summary was given. Attribute values are XML-escaped, and any `cross-session-message` tag inside the body is escaped, so a sender cannot forge a second envelope.
 
 ## Inbox Limits
 
 - **Max size**: 200 messages per session
 - **Eviction**: oldest read messages dropped first, then oldest unread
-- **No TTL**: messages, read or unread, stay in memory until evicted or the process exits. They are not persisted to disk.
+- **No TTL**: messages, read or unread, stay in memory until evicted, the session is stopped, or the process exits. They are not persisted to disk.
+- **Stopping clears the inbox**: `stopSession()` drops the session's messages, so a new session started under the same name does not receive mail meant for the old one. A stop that keeps the session resumable (`keepPersisted: true`, used when a session is restarted to continue the same conversation) leaves them in place.

package/skills/references/mcp.md

@@ -58,10 +58,12 @@ npm install -g @enderfga/claw-orchestrator
 
 When invoked, `clawo-mcp`:
 
-1. Sets `CLAWO_NO_EMBEDDED_SERVER=1` so the orchestrator does not bind its HTTP control plane (port 18796) — MCP-only deployments do not need it.
+1. Sets `CLAWO_NO_EMBEDDED_SERVER=1` (unless the variable is already set) so the orchestrator does not bind its HTTP control plane (port 18796) — MCP-only deployments do not need it.
 2. Captures the plugin's registered tools via an in-memory shim.
 3. Speaks MCP over stdio. All log lines go to stderr; stdout is reserved for the protocol.
 
+A `tools/call` returns the tool's result as text content blocks. A tool that throws, or a name that is not advertised, comes back as a result with `isError: true` and the message as text.
+
 ---
 
 ## Host configuration
@@ -115,7 +117,8 @@ Hermes prefixes tool names with `mcp_<server>_`. The model sees the prefixed nam
 }
 ```
 
-For Claude Code (`~/.claude.json` or per-project `.mcp.json`), use the same shape under `mcpServers`.
+For Claude Code, run `claude mcp add clawo -- clawo-mcp` (add `-e KEY=value` for each variable), or
+write the same shape under `mcpServers` in `~/.claude.json` or a per-project `.mcp.json`.
 
 ### Codex CLI
 
@@ -245,9 +248,9 @@ Hosts deliberately do not forward your full shell environment to MCP subprocesse
 | `GEMINI_API_KEY`             | Multi-model proxy (Gemini models)                                          |
 | `GATEWAY_URL`, `GATEWAY_KEY` | Routing through an OpenClaw / Anthropic-style gateway                      |
 | `CLAWO_MCP_TOOLS`            | Comma-separated allowlist of tool names; unlisted tools are not advertised |
-| `CLAWO_NO_EMBEDDED_SERVER`   | Suppresses port 18796 binding. `clawo-mcp` sets this automatically         |
+| `CLAWO_NO_EMBEDDED_SERVER`   | `1` suppresses port 18796 binding. `clawo-mcp` sets it when it is unset    |
 
-The engines themselves (`claude`, `codex`, `agy`, `grok`, `opencode`) must also be installed and authenticated on the host machine — `clawo-mcp` spawns them as subprocesses, it does not bundle them.
+The engines themselves (`claude`, `codex`, `agy`, `grok`, `opencode`, and any ACP agent you start with `engine: 'acp'`, such as `kimi` or `dsh`) must also be installed and authenticated on the host machine — `clawo-mcp` spawns them as subprocesses, it does not bundle them.
 
 ---
 
@@ -279,11 +282,14 @@ For "let the model commission an ultrareview before merging":
 
 `clawo-mcp` advertises [tool annotations](https://modelcontextprotocol.io/specification/server/tools#annotations) so hosts can prefer safer tools when reasoning:
 
-| Annotation                        | Tools                                                                                                                                                                                                                                                                |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `readOnlyHint` + `idempotentHint` | `session_list`, `sessions_overview`, `coding_session_status`, `session_grep`, `session_inbox`, `coding_agents_list`, `team_list`, `council_status`, `council_review`, `ultraplan_status`, `ultrareview_status`, `autoloop_status`, `autoloop_list`, `codex_goal_get` |
-| `destructiveHint`                 | `session_stop`, `council_abort`, `council_accept`, `council_reject`, `autoloop_stop`, `project_purge`                                                                                                                                                                |
-| `openWorldHint`                   | All tools that make outbound model API calls (most session / council / ultraplan / autoloop tools)                                                                                                                                                                   |
+| Annotation                        | Tools                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `readOnlyHint` + `idempotentHint` | `session_list`, `sessions_overview`, `coding_session_status`, `session_grep`, `session_inbox`, `coding_agents_list`, `team_list`, `council_status`, `council_review`, `ultraplan_status`, `ultrareview_status`, `autoloop_status`, `autoloop_list`, `codex_goal_get`, `claude_goal_status`, `claude_agents_list`, `plugin_details`, `codex_models`, `codex_thread_list`, `fanout_status`, `workflow_status`, `workflow_list`, `ultraapp_list`, `ultraapp_get`, `ultraapp_status`                                                                                        |
+| `destructiveHint`                 | `session_stop`, `council_abort`, `council_accept`, `council_reject`, `autoloop_stop`, `project_purge`, `codex_interrupt`, `codex_rollback`, `fanout_abort`, `workflow_cancel`, `ultraapp_build_cancel`, `ultraapp_promote_version`, `ultraapp_stop_container`, `ultraapp_delete`                                                                                                                                                                                                                                                                                        |
+| `openWorldHint`                   | `session_start`, `session_send`, `session_handoff`, `team_send`, `session_send_to`, `session_deliver_inbox`, `council_start`, `council_inject`, `ultraplan_start`, `ultrareview_start`, `autoloop_start`, `autoloop_chat`, `codex_resume`, `codex_review`, `codex_goal_set`, `codex_goal_resume`, `session_compact`, `claude_goal_set`, `codex_steer`, `fanout_start`, `workflow_start`, `workflow_resume`, `workflow_approve`, `verify_run`, `ultraapp_new`, `ultraapp_answer`, `ultraapp_add_file`, `ultraapp_spec_edit`, `ultraapp_build_start`, `ultraapp_feedback` |
+| none                              | `autoloop_reset_agent`, `codex_goal_pause`, `codex_goal_clear`, `session_update_tools`, `session_switch_model`, `claude_goal_clear`, `codex_fork`, `workflow_steer`, `ultraapp_start_container`                                                                                                                                                                                                                                                                                                                                                                         |
+
+Every registered tool has an entry. A hint that is not set takes the MCP default — not read-only, destructive, open-world — so the tools in the last row are advertised at the defaults, and so is each unset hint in the other rows.
 
 ---
 
@@ -292,7 +298,7 @@ For "let the model commission an ultrareview before merging":
 **The host shows no tools after restart**
 
 - Confirm `clawo-mcp` resolves on PATH: `which clawo-mcp`. If you used a non-global install, use the absolute path in `command`.
-- Confirm the host logs (Hermes: `~/.hermes/logs/`, Claude Desktop: View → Open Logs Folder). Look for the `[clawo-mcp]` lines.
+- Confirm the host logs (Hermes: `~/.hermes/logs/`, Claude Desktop: View → Open Logs Folder). Look for the `[clawo-mcp]` lines; a server that started prints `mcp server ready — exposing N of M tools over stdio`.
 
 **Engine starts but fails with `command not found`**
 
@@ -304,7 +310,7 @@ For "let the model commission an ultrareview before merging":
 
 **Tool list comes back empty**
 
-- `CLAWO_MCP_TOOLS` filter is set to names that don't exist. Drop it and check `tools/list` again, then add back the correct names. Stderr will print a warning.
+- `CLAWO_MCP_TOOLS` filter is set to names that don't exist. Stderr prints a warning that lists every available tool name; correct the filter from that list, or drop it to expose everything.
 
 **Port 18796 in use error**
 
@@ -314,10 +320,12 @@ For "let the model commission an ultrareview before merging":
 
 ## MCP vs OpenClaw plugin: when to use which
 
-| Use case                                                                                                                              | Recommended form                  |
-| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| You already run OpenClaw and want the tools available to every OpenClaw agent                                                         | OpenClaw plugin                   |
-| You want to drive coding agents from Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose, or another MCP host | MCP server                        |
-| You want to call the orchestrator from a non-MCP custom runtime (Python, Go, …)                                                       | Standalone `clawo serve` HTTP API |
+| Use case                                                                                                                              | Recommended form                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| You already run OpenClaw and want the tools available to every OpenClaw agent                                                         | OpenClaw plugin                                                                        |
+| You want to drive coding agents from Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose, or another MCP host | MCP server                                                                             |
+| You want to call the orchestrator from a non-MCP custom runtime (Python, Go, …)                                                       | Standalone `clawo serve` HTTP API                                                      |
+| You want an OpenAI-compatible client (a webchat, a gateway) to talk to a coding session                                               | `/v1/chat/completions` on `clawo serve` — see [`openai-compat.md`](./openai-compat.md) |
+| You want an editor (Zed, JetBrains, Neovim, Emacs, VS Code) to use the orchestrator as its coding agent                               | ACP agent (`clawo acp`) — see [`acp.md`](./acp.md)                                     |
 
-The same package supports all three — they share the SessionManager and tool definitions. Pick whichever entry point matches your host.
+The same package supports all of these — they share the SessionManager, and the MCP server and the OpenClaw plugin share the tool definitions. Pick whichever entry point matches your host.