From 852e8f7a2a5ab3552d603a6d53b3eaf3aab2d33a Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 5 Apr 2026 10:54:11 +0100 Subject: [PATCH] docs: update Claude CLI backend docs for MCP bridge, streaming, and auth changes --- docs/gateway/cli-backends.md | 38 +++++++++++++++++++++--------------- docs/providers/anthropic.md | 18 +++++++++++++---- 2 files changed, 36 insertions(+), 20 deletions(-) diff --git a/docs/gateway/cli-backends.md b/docs/gateway/cli-backends.md index f6b29f2fd29..e350b39a97f 100644 --- a/docs/gateway/cli-backends.md +++ b/docs/gateway/cli-backends.md @@ -1,9 +1,9 @@ --- -summary: "CLI backends: text-only fallback via local AI CLIs" +summary: "CLI backends: local AI CLI fallback with optional MCP tool bridge" read_when: - You want a reliable fallback when API providers fail - You are running Claude CLI or other local AI CLIs and want to reuse them - - You need a text-only, tool-free path that still supports sessions and images + - You want to understand the MCP loopback bridge for CLI backend tool access title: "CLI Backends" --- @@ -12,8 +12,10 @@ title: "CLI Backends" OpenClaw can run **local AI CLIs** as a **text-only fallback** when API providers are down, rate-limited, or temporarily misbehaving. This is intentionally conservative: -- **Tools are disabled** (no tool calls). -- **Text in → text out** (reliable, with Claude CLI partial text streaming when enabled). +- **OpenClaw tools are not injected directly**, but backends with `bundleMcp: true` + (the Claude CLI default) can receive gateway tools via a loopback MCP bridge. +- **JSONL streaming** (Claude CLI uses `--output-format stream-json` with + `--include-partial-messages`; prompts are sent via stdin). - **Sessions are supported** (so follow-up turns stay coherent). - **Images can be passed through** if the CLI accepts image paths. @@ -263,33 +265,37 @@ CLI backend defaults are now part of the plugin surface: ## Bundle MCP overlays -CLI backends still do **not** receive OpenClaw tool calls, but a backend can opt -into a generated MCP config overlay with `bundleMcp: true`. +CLI backends do **not** receive OpenClaw tool calls directly, but a backend can +opt into a generated MCP config overlay with `bundleMcp: true`. Current bundled behavior: -- `claude-cli`: `bundleMcp: true` +- `claude-cli`: `bundleMcp: true` (default) - `codex-cli`: no bundle MCP overlay - `google-gemini-cli`: no bundle MCP overlay When bundle MCP is enabled, OpenClaw: +- spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process +- authenticates the bridge with a per-session token (`OPENCLAW_MCP_TOKEN`) +- scopes tool access to the current session, account, and channel context - loads enabled bundle-MCP servers for the current workspace - merges them with any existing backend `--mcp-config` - rewrites the CLI args to pass `--strict-mcp-config --mcp-config ` -If no MCP servers are enabled, OpenClaw still injects a strict empty config. -That prevents background Claude CLI runs from inheriting ambient user/global MCP -servers unexpectedly. +The `--strict-mcp-config` flag prevents Claude CLI from inheriting ambient +user-level or global MCP servers. If no MCP servers are enabled, OpenClaw still +injects a strict empty config so background runs stay isolated. ## Limitations -- **No OpenClaw tools** (the CLI backend never receives tool calls). Some CLIs - may still run their own agent tooling. Backends with `bundleMcp: true` - can still receive a generated MCP config overlay for their own CLI-native MCP - support. -- **Streaming is backend-specific**. Claude CLI forwards partial text from - `stream-json`; other CLI backends may still be buffered until exit. +- **No direct OpenClaw tool calls.** OpenClaw does not inject tool calls into + the CLI backend protocol. However, backends with `bundleMcp: true` (the + Claude CLI default) receive gateway tools through a loopback MCP bridge, + so Claude CLI can invoke OpenClaw tools via its native MCP support. +- **Streaming is backend-specific.** Claude CLI uses JSONL streaming + (`stream-json` with `--include-partial-messages`); other CLI backends may + still be buffered until exit. - **Structured outputs** depend on the CLI’s JSON format. - **Codex CLI sessions** resume via text output (no JSONL), which is less structured than the initial `--json` run. OpenClaw sessions still work diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index d8f0fff7a6e..533c05b4191 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -289,9 +289,11 @@ If the `claude` binary is not on the gateway host PATH: ### What you get -- Claude subscription auth reused from the local CLI +- Claude subscription auth reused from the local CLI (read at runtime, not persisted) - Normal OpenClaw message/session routing -- Claude CLI session continuity across turns +- Claude CLI session continuity across turns (invalidated on auth changes) +- Gateway tools exposed to Claude CLI via loopback MCP bridge +- JSONL streaming with live partial-message progress ### Migrate from Anthropic auth to Claude CLI @@ -347,8 +349,16 @@ you need to. ### Important limits - This is **not** the Anthropic API provider. It is the local CLI runtime. -- Tools are disabled on the OpenClaw side for CLI backend runs. -- Text in, text out. No OpenClaw streaming handoff. +- OpenClaw does not inject tool calls directly. Claude CLI receives gateway + tools through a loopback MCP bridge (`bundleMcp: true`, the default). +- Claude CLI streams replies via JSONL (`stream-json` with + `--include-partial-messages`). Prompts are sent over stdin, not argv. +- Auth is read at runtime from live Claude CLI credentials and is not persisted + to OpenClaw profiles. Keychain prompts are suppressed in non-interactive + contexts. +- Session reuse is tracked via `cliSessionBinding` metadata. When Claude CLI + login state changes (relogin, token rotation), stored sessions are + invalidated and a fresh session starts. - Best fit for a personal gateway host, not shared multi-user billing setups. More details: [/gateway/cli-backends](/gateway/cli-backends)