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
    shell?: boolean // the run_command tool; optional, and absent from the defaults, so absent means off
    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

​

Running commands

​

Every precondition for the tool to exist

1. The shell is switched on for that Boo, AgentConfig.tools.shell === true. The field is optional and deliberately absent from the default config, so absent reads as off and a shell never arrives switched on.
2. The run has a working directory. In practice that means a board task with a provisioned worktree. A 1:1 chat, a team-room turn and a dispatch turn carry no working directory, so the tool is absent there. (The post-task verification critic does get one, but it runs under the default config with the switch off.)
3. The host is not Windows. See Windows has no shell at all.
4. The run is a clawboo-native run. run_command is a local tool, dispatched by the native conversation loop rather than registered with the capability broker, precisely so it cannot appear inside a claude-code, codex, hermes or openclaw agent. It is not an MCP tool and is not listed in MCP tools.

​

The switch

• The switch reads “Let this Boo ask to run commands”, with the helper line “You are asked before every command. Nothing is remembered, so a command you allowed once will ask again the next time.”
• Turning it on raises a confirm dialog titled “Let this Boo ask to run commands?”, with the body “It will be able to propose running programs on this computer. You are asked to approve every command before it runs, and nothing is remembered, so you will see each one.” The confirm button reads “Allow it to ask”.
• Once it is on, the card adds: “Commands run in this Boo’s working folder, as you, with access to the network. One program at a time: it cannot use pipes, redirects, or a shell.”

​

The tool contract

• Input is argv (an array of strings, required) and why (a string, optional: “One short sentence on why this command is needed”).
• argv only. The program and each argument are separate array items, never one string, and the child is spawned with shell: false, always. There are no pipes, no redirects and no shell operators.
• A person is asked every single time, and nothing is remembered. There is no allowlist at this tier, so the card never offers Always: an “Always” that behaved as an allow-once would be a control that lies.
• One run may ask about 10 commands. The next call is refused without reaching anyone.
• The card stays answerable for 10 minutes.
• Output is capped at 64 KiB, stdout and stderr in arrival order, and the result says when the tail was dropped. A command is never killed merely for being chatty.
• A non-zero exit is returned as an error result with the output still attached. A command stopped by a signal has no exit code, and the result then opens with The command finished with exit code unknown.
• A command that runs past five minutes is stopped: SIGTERM to the process group, escalating to SIGKILL after a 3 second grace window. Stopping the run kills it the same way.

​

Refused before anyone is asked

• An argv that is not a non-empty array of strings, holds more than 64 items, or carries an item over 2048 bytes.
• Any control character in an argument. A NUL would truncate the string at the syscall boundary, so what a person read on the card and what the kernel receives would differ.
• An argv[0] carrying a path separator without being an absolute path: a bare program name or an absolute path, nothing in between.
• A program that resolves to a denylisted name, or a script whose shebang names one.

​

Program resolution

​

The child process

• The child gets an allowlist environment, not the server’s ambient one. On a Unix host the names that pass through are PATH, HOME, SHELL, LANG, LC_ALL, LC_CTYPE, TZ, TMPDIR, LOGNAME, TERM, USER, and the proxy variables.
• Provider credentials are not forwarded, so an approved printenv does not return your API keys.
• It runs in the Boo’s working folder, as the user running clawboo, with network access.

​

Windows has no shell at all

​

Honest limits

• The card does not show the Boo’s stated reason. why is stored on the approval row, but the shell card carries no agent note: what you see is the command and the folder, and nothing about why the Boo wants it.
• Declining can end the task, not just the command. A refusal latches the tool for the rest of the run, and the next attempt is a second policy denial in a row, which trips the run’s repeat-denial breaker and aborts the board task. An unanswered card sets the same latch, but the expiry itself is not recorded as a denial, so it takes two later attempts rather than one to trip the breaker.
• A card nobody answers blocks the run for the full 10 minutes, and the run makes no other progress while it waits.
• The ceiling and the latch are per driver run, not per task. A task that is re-driven starts again at zero asks, with the latch cleared.
• No audit row is written for a run_command execution, so it never appears in GET /api/tools/audit. The approval itself is an ordinary row in the approvals queue.

​

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. Deploy a team

​

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 of the routable provider keys in the provider table resolves (all eleven count, not just the first three), or OLLAMA_BASE_URL is set, no binary probe, no network call. Runtime health is deliberately runtime-wide; each agent’s own routing is reported per agent as providerReady on GET /api/agents, which mirrors the router’s candidate rule: true when a key resolves in that agent’s envVar, or in one of its fallbacks, or its provider is keyless Ollama. The agent detail and chat headers badge an agent whose providerReady is false even while the runtime card is green.
• 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, and run
• 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