Clawboo Native runtime

​

What it is

• No install, no subprocess. The adapter (@clawboo/adapter-native) and the server-side harness ship inside the Clawboo server. The descriptor marks it builtIn: true with healthBin: null and installCommand: null. There is nothing to install; connecting is purely pasting a provider key (or none, for Ollama).
• No Gateway. With a single pasted key, the native runtime runs Clawboo end-to-end: a leader delegates over the Tasks MCP, a specialist claims and works in a worktree, and the result lands on the board, all without an OpenClaw Gateway. The provider SDKs (@anthropic-ai/sdk, openai) are imported lazily inside the first turn, so booting the server costs nothing.

​

Capabilities

​

The agent config

interface AgentConfig {
  id: string
  name: string
  systemPrompt: string // the STABLE prompt tier (KV-cache safe)
  primaryProvider: string // one of the 11 KNOWN_PROVIDERS ids (see the routing table)
  primaryModel: string
  fallbacks?: { provider: string; model: string }[]
  envVar: string // vault env-var NAME for the primary key (never the secret)
  tools: {
    memory: boolean // Memory MCP (shared facts)
    tools: boolean // Tools MCP / managed capability broker
    tasks: boolean | 'read' // Tasks MCP / the durable board; 'read' attaches only list_tasks + get_task
    teamchat: boolean // TeamChat MCP — post + listen as a named peer
    custom?: string[] // reserved
  }
  participantKind: string // 'agent' today; open set
  maxTurns?: number // default 16
  budgetUsd?: number | null // null = system default; a set value mints an agent-scope hard-cap budget
  createdAt: number
  updatedAt: number
  tenantId: string | null // dormant multi-tenant seam — always null today
}

​

Providers and routing

​

Fallback

1. The active candidate streams a turn. If it fails with a fallback-worthy error (auth, rate_limit, overloaded, network) before yielding any output, the next candidate is tried.
2. Once a candidate yields, it is surfaced as-is; a mid-stream retry would duplicate the streamed text, so a mid-stream error propagates.
3. A working candidate becomes sticky for the rest of the conversation, and cost is attributed to the provider that actually served the turn.

​

The turn loop

• KV-cache discipline. The system prompt is the stable tier (the agent’s systemPrompt plus a date-only stamp, never minute precision, which would bust the cache prefix). The tool universe is built once before turn 1 and sorted by name (deterministic order is a cache key). The caller-assembled run context (which already carries the volatile memory block in its tail) arrives as the first user message; nothing volatile ever enters the system prompt.
• Per-turn cost. Each completed provider response emits a cost event whose usage and USD are that turn’s deltas, not a running total. The host’s budget kill-switch therefore sees live spend mid-run, not one bill at the end. This is something the wrapped one-shot runtimes can’t offer.
• Terminals. No tool calls → a clean success done. Hitting maxTurns is a clean max_turns terminal (the host rotates to a fresh successor session carrying a handoff note), distinct from a failure. An abort or a provider error ends the run too; and every terminal persists the transcript.

​

Built-in file tools

​

In-process MCP

• Tasks (tasks): the durable board.
• Memory (memory): shared facts. The run’s authoritative memory scope (team id plus agent id) is bound onto the in-process Memory server, so native saves are team-shared and reads are team-limited, matching the HTTP-attached runtimes. The native server carries vectors too (hybrid search parity with every other runtime).
• Tools (tools): the managed capability broker.
• TeamChat (teamchat): posting and listening in the shared team room as a named peer. It binds the author identity from the run (anti-spoof) and requires both an agent id and a team.

​

The per-identity home

​

How to connect

​

1. Verify a key before committing

curl -X POST http://localhost:18790/api/runtimes/clawboo-native/healthcheck \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-..."}'

​

2. Connect the key

# Anthropic (the default slot)
curl -X POST http://localhost:18790/api/runtimes/clawboo-native/connect \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-ant-..."}'

# OpenRouter
curl -X POST http://localhost:18790/api/runtimes/clawboo-native/connect \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-or-...","provider":"openrouter"}'

​

3. Seed a default starter team (seed-native-team)

curl -X POST http://localhost:18790/api/onboarding/seed-native-team \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic"}'

​

Verify it worked

• GET /api/runtimes should show the clawboo-native entry with installed: true, binPath: null, and connectionState: "ready". Its health.ok is true when any routable provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY) resolves, or OLLAMA_BASE_URL is set, no binary probe, no network call.
• Run a board task on it via POST /api/runtimes/clawboo-native/run. Every resolvable provider key is injected from the vault into the run, so a key connected from the UI authenticates automatically.

​

Troubleshooting

​

Related

• Connecting runtimes, the install/connect/disconnect lifecycle and the encrypted vault
• Runtimes overview, the capability matrix across all five runtimes
• /api/runtimes reference, full request/response shapes for connect, healthcheck, run, and seed-native-team
• Quickstart: native-first, paste a key and land in a team with no Gateway
• The board, the durable task substrate a native run drives
• Memory, the shared facts tier a native run reads and writes over MCP
• Teams and planes, the shared-plane / private-plane split
• Environment variables, CLAWBOO_HOME, OLLAMA_BASE_URL, provider keys