Runtimes overview

When the early docs were written, OpenClaw was the only supported runtime and Claude/Codex were unbuilt stubs. That is no longer true. Chat is now multi-engine, and the other runtimes have shipped. This page is the overview of what runs your turns today and what is still genuinely on the roadmap.

For how the chat engines fit into the wider system, see the Architecture overview. For installing and wiring the gateway specifically, see OpenClaw.

Two seams, one set of runtimes

Carabase separates chat (an interactive, streaming conversation) from agent tasks (async, one-shot jobs queued via POST /api/v1/agent-tasks). Each has its own pluggable seam, but they share the same underlying model adapters and CLI bridges.

• Chat flows through the chat-engine seam. Every client — macOS, iOS, the CLI — sends turns to one route, POST /api/v1/agent/message, which resolves a chat runtime from workspace settings and dispatches to one of four engines.
• Agent tasks flow through the agent-runtime seam, which registers five runtimes.

Chat engines (all shipped)

workspace_settings.chat_runtime selects the engine. Valid values: auto, openclaw, host_native, codex_cli, claude_code (default auto).

Engine	What it is	Default?
OpenClaw	Wraps a locally-run OpenClaw gateway. History, memory, and skill state live gateway-side. The premium experience.	Selected by auto when a gateway password is configured.
Host-native	The OSS chat floor: an AI-SDK ReAct loop against the workspace’s selected model, with no gateway dependency. A self-host with only a model API key (or a local Ollama URL) chats out of the box.	Selected by auto when no gateway is configured.
Codex CLI	A bridge (read-write by default) to your locally-installed codex binary, authenticated by your own codex login.	Explicit-only.
Claude Code	A bridge (read-write by default) to your locally-installed claude binary, authenticated by your own claude login.	Explicit-only.

How auto resolves

auto picks by configuration presence, and the choice is sticky — it never fails a turn over to a different engine mid-conversation. If a gateway password is present (in the workspace row or the environment), auto resolves to OpenClaw; otherwise it resolves to host-native. The two vendor-CLI bridges are never auto-selected — you must choose them explicitly, and each requires its binary on your PATH plus an operator login.

The vendor-CLI bridges can read and write

As chat runtimes, codex_cli and claude_code run read-write by default: every harness and chat integration can read and write your workspace. Each turn shells out to your locally-installed CLI with:

• A short-lived, per-run MCP token scoped read-write, so the bridge can use your workspace’s retrieval tools and, when you ask it to, its write tools (record a decision, commit to a folio, propose an edit). The token expires with the run and is deleted when the run ends. Set CARABASE_CHAT_READ_ONLY=1 (the older CARABASE_CLI_CHAT_READ_ONLY=1 still works) to mint a read-only token instead; the host’s inbound gate then denies write tools, bound to the token rather than a spoofable header.
• A strict environment allowlist — the spawned CLI never sees your master key, database URL, or provider keys.
• Codex’s filesystem sandbox (-s read-only); for Claude, the entire built-in toolset is disabled (--tools "") while the Carabase MCP server is wired in separately.

Both bridges carry the same “ground or abstain” instruction the host-native engine uses, so they answer from your retrieved data rather than from the model’s parametric memory.

Grounding, model choice, and safety

The host-native engine (and, by extension, the two CLI bridges) is built to answer only from your data:

• Retrieval palette, plus writes on demand (host-native). The host-native chat loop can always call the workspace’s retrieval tools — semantic, graph, lexical, and metadata search; entity lookup; folio and memory traversal; time-series; visual and multimodal search; and full-document hydration. When you ask it to change something, it loads the matching group of the host’s own MCP write tools for that turn (tasks, folios, project memory, Documents, Tables, the review queue, backfills) and calls them in-process, with the same checks a full MCP token gets. It writes only when you ask or agree, never because retrieved content tells it to, and it asks before deleting, archiving or starting a backfill. CARABASE_CHAT_READ_ONLY=1 keeps it to retrieval only. See the MCP tools reference for the full surface.
• Ground-or-abstain. The model must cite retrieved evidence or abstain, rather than guess.
• Truthful intelligence controls. GET /api/v1/chat/options identifies the active runtime and exposes only the model/reasoning controls it honors. Host-native uses its operator-defined menu, the CLI bridges accept request-local overrides, and OpenClaw stays fixed because its gateway owns provider selection.
• Multi-turn coherence. Because host-native has no gateway session, it replays prior turns from the workspace’s own message store and rolls older history into a compact summary so long conversations stay in budget. If summarization ever fails, it degrades to a bounded recent window — it never fails your turn.
• Visible failure without short answers. A 120-second time-to-first-activity guard turns a startup hang into a typed error; after the first model text or tool call, the answer has no host-native wall-clock deadline. Empty-response guards still fail visibly.

Two grounding upgrades ship default-off behind operator flags: a grounding-verify gate that buffers a turn and checks its load-bearing figures and dates against this turn’s evidence (one corrective retry, then honest abstention), and cross-turn evidence carry-over so a follow-up about the same document re-surfaces it instead of retrieving cold.

Agent-task runtimes

The async agent-task seam registers five runtimes, selectable via the runtime field on a task:

Runtime	Kind
openclaw, claude, codex	AI-SDK model adapters over the shared agent loop.
codex_cli, claude_code	The same vendor-CLI bridges used by chat. As task runtimes they get a read-only token unless the task opts into writes.

Unlike chat, agent tasks run with the full tool palette (including write-capable tools, when granted).

Still on the roadmap

A few things named in the runtime plans are not yet built:

• A Gemini CLI bridge. Only the Codex and Claude bridges have shipped; Gemini is framed as a future manifest in the plan.
• A CLI version-compatibility registry (pinning min/max CLI versions to guard against silent upstream upgrades).
• An “installed-only” runtime picker in the Admin SPA that hides a CLI runtime when its binary is absent.
• Open-web tools (web_search / search_image) for the chat loop are deliberately inert — there is no live provider wired in, so a web_search call returns a tool error and the loop proceeds without it.