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 read-only bridge to your locally-installed codex binary, authenticated by your own codex login.	Explicit-only.
Claude Code	A read-only bridge 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 are read-only

codex_cli and claude_code run read-only by default. Each turn shells out to your locally-installed CLI with:

• A short-lived, per-run MCP token scoped read-only, so the bridge can reach your workspace’s retrieval tools but cannot take side effects (write tools are denied at the host’s inbound gate, bound to the token — not 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:

• Read-only retrieval palette. The chat loop can 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 — but no write tools. See the MCP tools reference for the full surface.
• Ground-or-abstain. The model must cite retrieved evidence or abstain, rather than guess.
• Use-time model selection. Host-native picks its model per turn from an operator-defined allowlist (a Fast/Smart menu derived from your routing config), so you can favour speed or quality without reconfiguring. The picker reads GET /api/v1/chat/models.
• 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. A wall-clock deadline plus empty-response guards turn a hung or empty turn into a typed error frame, so a stuck turn fails visibly instead of hanging.

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 read-only vendor-CLI bridges used by chat.

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.