OpenClaw runtime

Carabase v0.1 ships with OpenClaw as the only supported agent runtime. The host process talks to a gateway that OpenClaw runs locally; everything chat-related — tool calls, MCP server use, model routing — flows through that gateway.

This page covers what you need to install and how to wire it up. If you’ve already run pnpm bootstrap, the host has generated half of the configuration for you — you just need to install OpenClaw and paste the gateway password into its config.

Note

Claude (@ai-sdk/anthropic) and Codex (@ai-sdk/openai) provider stubs are present in the codebase but not advertised in v0.1. They’re scheduled for v0.2 — see Other runtimes.

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/. You can override that with OPENCLAW_WORKSPACE_DIR if you need a different layout.

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

The script printed the value at the end. Find it again with:

grep '^OPENCLAW_GATEWAY_PASSWORD=' .env.dev

Open OpenClaw’s config (typically ~/.openclaw/config.toml, but 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/config.toml → gateway.password = "..."

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.

4. Verify the connection

With both processes running, the gateway should be reachable from Carabase. Test it 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,
  "providers": [{ "name": "openclaw", "ok": true }]
}

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/config.toml. Re-paste from a fresh ./scripts/gen-secret.sh 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 remote machine
OPENCLAW_WORKSPACE_DIR	~/.openclaw/workspace	Where the dream-cycle reads DREAMS.md from
OPENCLAW_CONFIG_PATH	<repo>/openclaw.config.json	Carabase’s own MCP-server config for OpenClaw to consume

All three can also be set per-workspace via PUT /api/v1/workspace-settings — env vars are the boot-time fallback for the headless case.

What the gateway gives you

Once it’s connected, the OpenClaw gateway is the entry point for every chat-window message. From an architectural standpoint:

• POST /v1/chat/completions — OpenAI-compatible streaming endpoint the desktop client uses
• The gateway routes to the upstream model configured in ~/.openclaw/config.toml (NOT in Carabase’s model-routing — that’s deliberate, the chat role in ModelRouting is deprecated)
• Tool calls fan out to MCP servers Carabase exposes at /mcp/sse
• Memory + skill state lives on the OpenClaw side; Carabase is the data substrate

If you’re trying to change which model the gateway uses, edit OpenClaw’s config — not Carabase’s model-routing settings page (that page only controls background work like compaction and entity extraction).