OpenClaw runtime

OpenClaw is Carabase’s premium default chat engine. When a workspace has an OpenClaw gateway configured, every chat-window message flows through it — tool calls, MCP server use, and upstream model selection all happen gateway-side.

OpenClaw is no longer the only runtime, though. Chat is multi-engine: the host resolves a chat_runtime per workspace and dispatches to one of several engines:

• openclaw — the gateway (this page). The default when a gateway password is configured.
• host_native — the built-in, no-gateway OSS chat floor. The host runs an AI-SDK retrieval loop directly against your configured utilityHigh model. This is what a self-host gets out of the box with zero OpenClaw.
• codex_cli / claude_code — read-only bridges to your locally installed codex / claude CLIs (authenticated by your own codex login / claude login). Explicit-only; never auto-selected.

When the runtime is set to auto (the default), the host picks OpenClaw if a gateway password is present, otherwise host_native — a sticky choice based on configuration, not a per-turn health failover. For the engine roster and how host-native grounding/compaction work, see Other runtimes.

This page covers installing OpenClaw and wiring it up. If you’ve already run pnpm bootstrap, the host generated half the configuration for you — you just need to install OpenClaw and share the gateway password.

What you need

• OpenClaw CLI (the agent framework itself)
• A bearer token that both Carabase and OpenClaw agree on (the “gateway password”)
• Network reachability between the two: by default, OpenClaw listens on localhost:18789 and Carabase reaches it at the same address

1. Install OpenClaw

pnpm add -g openclaw@latest

Verify it’s on your PATH:

openclaw --version

OpenClaw stores its config and runtime data under ~/.openclaw/.

2. Configure the gateway password

Carabase’s pnpm bootstrap already generated a fresh 256-bit OPENCLAW_GATEWAY_PASSWORD and put it in your .env.dev file. Both processes need to share that exact value, or the gateway responds 401 on every request.

If you ran pnpm bootstrap

Find the value with:

grep '^OPENCLAW_GATEWAY_PASSWORD=' .env.dev

Open OpenClaw’s config (check OpenClaw’s own docs for the canonical path) and paste it as the gateway password. Roughly:

[gateway]
password = "<the 64-char hex string from .env.dev>"

If you skipped pnpm bootstrap

Generate a fresh value and put it in both places:

./scripts/gen-secret.sh 32

Paste the output into:

1. .env.dev → OPENCLAW_GATEWAY_PASSWORD=...
2. OpenClaw’s gateway config → the gateway password field

The password is resolved per-workspace from the workspace row, falling back to the OPENCLAW_GATEWAY_PASSWORD env var for the headless case.

3. Start OpenClaw

How you do this depends on how you installed it. The simplest is foreground:

openclaw gateway

For a daemonized install, follow OpenClaw’s own install docs — typically launchctl on macOS, systemd on Linux. Carabase also health-monitors the gateway and will best-effort spawn openclaw gateway itself if it goes down.

4. Verify the connection

With both processes running, test the gateway directly:

# Without auth — should get 401:
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:18789/health

# With auth — should get 200:
PASSWORD=$(grep '^OPENCLAW_GATEWAY_PASSWORD=' .env.dev | cut -d= -f2)
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $PASSWORD" \
  http://localhost:18789/health

Then ask the host directly:

WORKSPACE_ID=$(psql $DATABASE_URL -tAc 'SELECT id FROM workspaces LIMIT 1')
curl -s -H "x-workspace-id: $WORKSPACE_ID" \
  http://localhost:3000/api/v1/agent-runtime/status | jq

You’re looking for:

{
  "reachable": true,
  "authConfigured": true,
  "authWorks": true,
  "gatewayUrl": "http://localhost:18789"
}

When the gateway is unreachable, authConfigured and authWorks come back as null (unknown) rather than misleading booleans.

If reachable is false: OpenClaw isn’t running, or it’s listening on a different port (override with OPENCLAW_GATEWAY_URL in .env.dev).

If authWorks is false: the password in .env.dev doesn’t match OpenClaw’s config. Re-paste from a fresh ./scripts/gen-secret.sh 32 into both places and restart both processes.

5. Override paths (optional)

The host accepts a few env vars for non-default OpenClaw layouts:

Var	Default	When to set
OPENCLAW_GATEWAY_URL	http://localhost:18789	Gateway on a non-default port or host
OPENCLAW_CONFIG_PATH	openclaw.config.json	Carabase’s MCP-server config that OpenClaw consumes
OPENCLAW_WORKSPACE_DIR	~/.openclaw/	Where the dream-cycle reads DREAMS.md from

What the gateway gives you

Once it’s connected, the OpenClaw gateway is the entry point for every chat-window message routed to it. Architecturally:

• The host proxies chat to the gateway’s POST /v1/chat/completions (OpenAI-compatible streaming endpoint).
• The model field is always normalized to the gateway contract: "openclaw" or "openclaw/<agentId>". Raw provider strings (e.g. openrouter/auto) are rejected by OpenClaw, so the host coerces anything that isn’t already an OpenClaw agent string. The client value is honored only when it addresses a specific OpenClaw agent (to pick a persona / sub-agent).
• Upstream model selection lives inside OpenClaw (its own config), not in Carabase’s model-routing. Carabase’s model-routing page controls background work — compaction, entity extraction, embeddings — not the chat model the gateway uses.
• Tool calls fan out to Carabase’s MCP server, which the host self-registers with the gateway at boot (ensureCarabaseMcpRegistered) over GET /mcp/sse. That surface exposes Carabase’s 14 retrieval tools — semantic / lexical / graph / metadata / entity-candidate search, multi-strategy routing, hypothesis verification, time-series and memory-network traversal, visual and multimodal search, mesh scanning, and reading narrative folios — so the chat agent can reach your knowledge mesh.

If the MCP server isn’t registered, the chat agent has no path to the mesh. The host registers it automatically at boot; to check or repair by hand:

openclaw mcp list
openclaw mcp add carabase --transport sse \
  --url http://localhost:3000/mcp/sse \
  --header "x-workspace-id=<workspace>"

Security boundary

The gateway port (18789) is never exposed — not even on the Tailnet. Only the Fastify API on port 3000 accepts connections, and it sits in front of the gateway to enforce workspace scoping and keep credentials (API keys, webhook secrets — stored encrypted in Postgres) out of OpenClaw’s config files entirely.