Before you begin
- Clawboo running, installed any way:
npm install -g clawboo, a one-offnpx clawboo@latestrun, or a source checkout. - Node.js 22.12 or newer, with npm.
- An Anthropic API key from console.anthropic.com. A
claudeCLI signed in with a Claude subscription is not enough: Clawboo shows Claude Code as connected, and offers it for your agents, only when an Anthropic API key is available.
Set up Claude Code
Install the Claude Agent SDK
@anthropic-ai/claude-agent-sdk@0.3) into its own runtimes folder and shows npm’s output. This works however you run Clawboo, npx included, and needs no sudo and no restart.Clawboo does not ship the SDK, because its Claude Code binary adds about 210 MB to every install. A source checkout already has it in its node_modules, and an SDK you installed next to a global Clawboo keeps working, so there the row reads Needs key or Connected without this step.Check the Claude Code row
claude binary, which came with the SDK in the step above, so there is nothing more to install. A claude CLI on your PATH is not used and does not count: without the SDK the row reads Not installed.If the install ends with “The Agent SDK installed without its own <platform>-<arch> binary, so Claude Code could not run on it and nothing was changed”, npm left out the SDK’s platform package, which is an optional dependency. Clawboo keeps no such install, so whatever ran Claude Code before still does. Check that npm may install optional dependencies, then click Install again.Connect your Anthropic key
ANTHROPIC_API_KEY field, and click Connect. Clawboo checks the key with Anthropic before it saves it. If the check fails, the panel shows the reason; fix the key, or click Connect anyway when Anthropic is only unreachable from this computer.You should see the row read Connected. If you already saved an Anthropic key under Settings > Providers, Claude Code reads Connected without this step.Put a Claude Code agent on a team
What Clawboo controls on Claude Code
Your own Claude Code setup stays out
Clawboo starts Claude Code without your own Claude Code setup. A Claude Code agent does not load:- your user settings in
~/.claude/settings.json: plugins, hooks,env, permissions, model and effort level - the MCP servers you added to your own Claude Code
- your
~/.claude/CLAUDE.mdand~/.claude/rules, or aCLAUDE.mdin any folder above the one it works in (on a task with no worktree, the team’s folder is the exception; see below) - Claude Code’s auto memory, so it neither reads nor writes the notes Claude Code keeps for a repository
CLAUDE.md, .claude/settings.json (hooks included) and .mcp.json, as anyone who clones the repository gets them. On a task with no worktree it works in the task’s own folder, and it also reads the CLAUDE.md, .claude/CLAUDE.md and .claude/rules/ of the team’s folder and of the tasks/ folder between them, so a CLAUDE.md in the team’s folder reaches its task runs as well as the turns that start there. The team folder’s .claude/settings.json and .mcp.json do not apply on a task run: only the task folder’s own project settings do.
This does not change how Claude Code signs in. Clawboo passes your Anthropic key in Claude Code’s environment, and the claude command’s own sign-in is not kept in a settings file. If your Claude Code reaches Anthropic through ~/.claude/settings.json, for example an env block that sets ANTHROPIC_BASE_URL or an apiKeyHelper, that no longer applies to agents: set the same variables in the environment you start Clawboo with.
Leaving your setup out is not a sandbox. Claude Code can still read any file your user account can, ~/.claude included.
Permissions and safety
- A worktree is not a sandbox. Only a task-runner run of a task that changes files, with a repository named, works in its own git worktree, which keeps its edits off your main checkout. Everywhere else there is no worktree. A run on a task (one handed out in team chat, one you give from the Board, or a research or review run, which includes every agent Routine you create in the app) starts in the task’s own folder,
teams/<team id>/tasks/<task id>in the work folder (~/clawboo-workby default). Turns that hold no task, such as the lead’s turns and your messages in team chat, and the agent’s own chat start in its team’s folder,teams/<team id>, which every member of the team shares (a task or an agent with no team usesteams/_no-team). The work folder sits outside Clawboo’s data folder, so../..from there does not reach the database. Work an install keeps in the data folder (see The work folder for when that happens) does not get that distance. That folder only sets where it starts: Claude Code can still read and change any file your user account can, including Clawboo’s database and key vault in~/.clawboo, by their full path. - Clawboo’s approvals do not cover Claude Code’s own tools. Calls the agent makes through Clawboo’s Tools server (connectors, for example) go through Clawboo’s checks and can ask you first. Claude Code’s built-in shell, file and web tools never do.
- Clawboo hides some secrets from it, by name only. Before a run, Clawboo removes its own secrets (the OpenClaw Gateway token, the dashboard access token and the vault master key) from the environment Claude Code inherits. It also removes a fixed list of common credentials, such as GitHub, npm, cloud, Stripe, Slack and database variables, and the variables that tie a process to a Claude Code session (
CLAUDECODE,CLAUDE_CODE_ENTRYPOINT,CLAUDE_CODE_SESSION_ID,CLAUDE_CODE_SESSION_ATTENDED,CLAUDE_CODE_MESSAGING_SOCKETandCLAUDE_CODE_MESSAGING_TOKEN), so a Clawboo started from a terminal inside Claude Code does not hand that session to its agents. Claude Code settings such asCLAUDE_CODE_USE_BEDROCKpass through, like every other variable not on these lists, and credential files on disk stay readable. - With a user per agent, each agent has its own
~/.claude. WithCLAWBOO_AGENT_USERS(Linux only for now), each Claude Code agent runs as an OS user of its own and uses that user’s~/.claude, not yours or another agent’s. Give it an API key, or a token fromclaude setup-tokenasCLAUDE_CODE_OAUTH_TOKEN.
Costs
Claude Code reports the dollar cost of each run, and Clawboo records that figure as reported, not as an estimate. It counts toward your budgets, and Anthropic bills the same usage to your API key. If a run in team chat or in the agent’s own chat ends without reporting a cost (it failed early, say), Clawboo records an estimate from the length of the prompt and reply instead. The cost arrives when a run finishes, so a hard cap cannot stop a Claude Code run partway through. When that last report takes a hard cap past its limit, the finished result is kept and posted, and the next run is refused. A routine or API run that ends without reporting a cost is estimated the same way as in team chat. See Budgets and spend for how each runtime’s cost reaches your budgets.Disconnect Claude Code
In Settings > Runtimes, click Manage on the Claude Code row, then Disconnect. This deletes the Anthropic key from Clawboo’s vault. The vault keeps one copy of each key for every runtime, so Clawboo Native and Hermes lose that key too unless they find it elsewhere. Until you connect Claude Code again, it also ignores an Anthropic key in your shell or in~/.openclaw/.env. To remove one key on purpose, or keep it for other runtimes, see Disconnect a key or a runtime.
Limits
- Team setup has no model picker for Claude Code members.
- It needs an Anthropic API key to read Connected; a Claude subscription sign-in alone doesn’t count.
- The
clawboopackage does not include the Agent SDK. Install on the Claude Code row adds it. - A hard cap counts Claude Code’s cost only when each run ends, so it refuses the next run rather than stopping the current one.
Troubleshooting
The run failed: The Claude Code runtime needs @anthropic-ai/claude-agent-sdk
The run failed: The Claude Code runtime needs @anthropic-ai/claude-agent-sdk
Claude Code reads Needs key, but my claude CLI is signed in
Claude Code reads Needs key, but my claude CLI is signed in
ANTHROPIC_API_KEY set in the environment Clawboo runs with also counts.Claude Code is greyed out in Customize team (Connect in Runtimes)
Claude Code is greyed out in Customize team (Connect in Runtimes)
Invalid API key.
Invalid API key.
The run failed: Invalid API key (HTTP 401), or a billing or rate-limit message
The run failed: Invalid API key (HTTP 401), or a billing or rate-limit message
Could not reach anthropic (timed out).
Could not reach anthropic (timed out).
Installation failed with exit code 1.
Installation failed with exit code 1.
EACCES or ETARGET. Install never writes to npm’s global folder, so it needs no sudo. Clawboo removed the failed install, and an SDK you already had keeps working. Fix what npm reports, then click Install again.If the message says Clawboo’s runtimes folder must be apart from another folder, or belongs to another user, see When Clawboo will not use it.npm not found. Install Node.js (which bundles npm) and retry.
npm not found. Install Node.js (which bundles npm) and retry.
clawboo restart, then click Install again.Check that it works
- In Settings > Runtimes, the Claude Code row reads Connected.
- Open the team chat of a team with a Claude Code member. Type
@, pick that agent, and ask: “Say hello in one sentence.” - You should see a reply under the agent’s name. If the run fails, the chat shows “The run failed:” and the reason; look it up in Troubleshooting.
Under the hood
Under the hood
- Clawboo calls the SDK’s
query()withpermissionMode: 'bypassPermissions'andallowDangerouslySkipPermissions: true. It also passes the run’s working folder (the task’s worktree, the task’s own folder on a task run without one, or else the team’s folder), the model when a run names one, a session to resume, Clawboo’s four MCP servers over HTTP, and the scrubbed environment plus the connected key. It setssettingSources: ['project'], passessettingswithautoMemoryEnabled: falseand aclaudeMdExcludeslist that covers every folder above the working folder and your home folder, and setsCLAUDE_CODE_DISABLE_AUTO_MEMORY=1in the environment, over any value Clawboo itself runs with. - Claude Code files its saved sessions under the folder they ran in. When Clawboo moves a team folder into the work folder, it drops the session ids it saved for Claude Code agents (1:1 chat, team chat and task pointers), and when it moves a task checkout, the session id in that checkout’s handoff. The next turn starts a fresh session with the brief and the chat history. Task runs used to start in the team’s folder and now start in the task’s own folder, so once, at the first start with task folders, Clawboo also drops the Claude Code task sessions it saved before, and those tasks start a fresh session on their next run (see Task folders). Codex, Hermes and Clawboo Native agents keep their sessions.
- The SDK starts Claude Code from its own platform package. The Runtimes row checks for the SDK and that binary, never for a
claudeCLI. A run loads the SDK from Clawboo’s runtimes folder first, by its file path, else from next to Clawboo (a source checkout’snode_modules, or an SDK installed next to a global Clawboo). A source build of Clawboo uses SDK version 0.3.268. - Run a board task on Claude Code directly with
POST /api/runtimes/claude-code/run; see the Runtimes API. Such a run falls back to theclaudeCLI’s own sign-in when no Anthropic key is available. - A run that hits Claude Code’s turn limit ends cleanly, and the task runner continues the task in a fresh session with a handoff note. So does a run whose conversation outgrew the model’s context window: it ends out of room rather than failed, with a non-fatal error coded
context_overflowthat says why. Three values of aresult’sterminal_reasonmean that:prompt_too_long(the API refused the prompt and compaction could not make it fit),blocking_limit(Claude Code’s own count reached its limit with no compaction to fall back on, so it refused before calling the API) andrapid_refill_breaker(the context refilled to the limit within 3 turns of a compaction, 3 times in a row, so it gave up compacting). Clawboo does not resume such a session. In team chat, where nothing restarts by itself, the task is blocked and its saved session dropped, and Retry runs it in a fresh session. In a one-to-one chat, the next message starts fresh and the chat says so. Claude Code’s own text for these endings, such as advice to use its/clear, is never shown as the agent’s reply. It goes on the board as the failure’s detail, so a task that ran out of room this way says why. - An API error reaches the SDK as an assistant message with an
errorfield (authentication_failed,billing_error,rate_limit, …) and then aresultwithsubtype: 'success'andis_error: true. Clawboo reads that pair as a failed run carrying theerrorvalue as its code, and does not show the error notice as the agent’s reply. A refused key or login (authentication_failed,oauth_org_not_allowed,cloud_credential_error) is filed asAuthand a refused account (billing_error,account_on_hold,verification_required) asBilling, so the task waits in Needs you with Fix sign-in instead of being retried; see Error classes. Other failed results, such aserror_during_execution, keep the cause from theirerrorslist.
Related
- Choose a runtime: how Claude Code compares with the other runtimes.
- Connect AI providers and runtimes: keys, sign-ins and what Disconnect removes.
- What agents can do: permissions and safety for every runtime.
- Budgets and spend: how cost reaches your budgets.
- Worktrees and handoff: when a run gets its own git worktree.