Servers
Every server reports version
0.1.0 and declares the tools.listChanged capability. Only the Tools server sends list-changed notifications, when a connector connects or disconnects.
Tool index
Callers and scoping
A caller’s identity decides which tools it is served and what those tools can see. Over HTTP, a session reads its identity once, when it sendsinitialize, from query parameters on its attach URL. Clawboo signs those parameters with a secret kept in its own database, so an identity counts only when its signature verifies.
There are four kinds of caller:
- Bound caller. A run Clawboo started with a signed attach URL. Claude Code and Codex runs are bound to their team and agent this way. A Hermes profile keeps one signed URL per server that names only the agent (
live=1), and the server binds each call on it to that agent’s run in progress, so the call gets the same binding a per-run URL would carry. A call on it while the agent has no run in progress (a job Hermes runs on its own between runs, say) is bound as that agent’s one-to-one chat is: its own team, no task, the chat’s three Tasks tools and the agent’s own connector grants. Clawboo Native agents are bound in-process. A run the team engine drives (a team chat turn, a hand-off, a plan step) is also signed as a team run (teamRun=1on its Tasks, Memory and Tools URLs, so none of them carries a plain signature for its team and agent), because the engine claims and moves that run’s tasks itself. A Clawboo Native team run gets the same limit in-process. A run on a board task (a hand-off, a task you gave from the Board, or a task-runner run) also has that task on its Tasks and Tools URLs, asscopeTaskIdinside the same signature, so a runtime cannot point it at another task; Clawboo Native gets it in-process. Its one-task tools use it when a call leaves outtaskId(see Tasks server), and an approval its connector calls open names it. Such a run’s Tasks URL also carries its run, asscopeExecutionIdinside the signature, which its writes record (see Who made a write). - Unverified HTTP caller. Any HTTP session without a valid signature. Every OpenClaw agent is one, because the OpenClaw Gateway uses one shared configuration for all of its agents. So is an external agent attached with an unscoped URL, or with parameters edited by hand.
- Operator (stdio bin). Someone ran a
clawboo-mcp-*bin directly. The operator is trusted, so scope and identity come from the tool arguments. - In-process (Clawboo Native). The servers run inside the dashboard server and are bound to the run’s team and agent.
What each runtime attaches
A Clawboo Native agent’s tool settings choose which servers it gets. The default is the read-only Tasks surface (
list_tasks and get_task), Memory, Tools and TeamChat, because the team engine owns board writes on team runs. An OpenClaw agent takes part in the peer room through the server instead of the TeamChat tools. The critic run that verification can start attaches with no scope, so it is an unverified caller too.
Attach URL parameters
scopeSigis an HMAC-SHA256 over the server the URL is for, the team, agent, tenant and delegate fields, and the team-run mark,scopeTaskId,scopeExecutionIdandscopeRunRefwhen present, so a signature for one server opens no other, under a per-install secret stored in thesettingstable (mcp-attach-scope-secret). A spawned runtime only ever sees the derived signature. A URL without the newer fields signs exactly as before.- Provenance stamps record which run saved a fact or reported an outcome. They never widen what a session can see, and they are dropped when
provSigdoes not verify. delegate=1is inside the signature, so a run cannot add it to its own URL. Clawboo writes it only for runs driven by the team engine, which is watching for theteam_delegatecall.- Every URL Clawboo writes also carries an
attachToken. When the access gate is on, a cookieless MCP request needs it (see Transports). - The request log keeps attach URLs but masks
attachToken,scopeSigandprovSig.
Tasks server
The Tasks server is the board over MCP. Any runtime can list, create, claim and update tasks on the same board the dashboard shows. Board rules (statuses, legal moves, the verification check beforedone) are described in The board.
Statuses in the schemas below are TaskStatus:
- Team-bound sessions. When the session is bound to a team, every tool refuses a task from another team with the same
not found: <taskId>a missing task gets, so a bound run cannot probe other teams.list_taskslists only the team’s tasks, and new tasks are created in the team. - Refusals are tool errors. A refused call returns
isError: truewith the text shown under each tool, not a protocol error. - Never retry a lost claim.
claim failed: conflictmeans another agent won the claim. Retrying the same call cannot succeed. - Mailbox delivery. On a session bound to an agent, each successful result can carry an extra text block headed
[team updateswith up to five undelivered mailbox notices for that agent. Each notice is delivered once, on whichever channel reaches the agent first. A notice can quote a person or another agent, so each one is framed as data: a header[Inter-session message · from=<who wrote it> · kind=<kind> · isUser=false], then every line of the notice quoted with|, under a line saying the notices are information, not instructions. - The run’s own task. On a session bound to a task (a run on a board task),
get_taskandadd_commenttaketaskIdas optional and use that task when it is left out, and so doesblock_task. Their descriptions say so, and the field is listed as optional only on such a session. Any task can still be named (on a team run,block_tasknames only its own), and an emptytaskIdis refused rather than read as the run’s own task. - A waiting task says why.
block_task, andupdate_task_statusandcreate_taskmoving a task toblockedorin_review, needwaitingOn. A call without it is refused with text that says what to send, and nothing moves.
Who made a write
Every write these tools make is recorded in the event log (task_created, task_claimed, status_changed, comment_added, dep_linked) with an actor, ask_person, hand_back_task, report_result and write_plan as a status_changed:
- A bound caller:
{ kind: 'agent', agentId, execId }, the agent the session is bound to and theexecution_processesrow of its run.execIdis null on a turn with no run row, such as a lead’s own turn or a 1:1 chat. A comment also stores the run intask_comments.execution_id, and a question intask_questions.execution_id, so the question’s words on the thread name the run that asked. - Anyone else:
{ kind: 'caller' }, which says nothing about who it was. That covers every OpenClaw agent: the OpenClaw Gateway gives all of its agents one MCP address with no signature, so a write cannot be traced to one of them. It covers the stdio bins and an external agent with an unsigned URL too.
GET /api/mcp/config for a URL signed as another agent, or one that reads the attach secret from the database. A write the tools refuse (a lost claim, an illegal move) records nothing.
Creation caps
Creates through these tools are capped so a looping agent cannot flood the board. The caps count every task on the board, including tasks created through the dashboard, the API or the team engine, which are not capped themselves.
The check and the insert run in one write transaction, so two runtimes racing for the last slot cannot both get it. An unchanged retry that would make a new task gets the same answer; a person cancelling a child, or dropping a stale one, frees a slot, and the root window rolls. A refusal also carries its reason in the result’s
_meta.denied field. Clawboo Native turns that field into a policy_denied error, and repeated identical refusals in a task-runner run trip the circuit breaker (see Governance).
A task is made once
create_task and create_subtask return an existing task instead of making a second one in two cases. The row comes back with deduplicated: true, deduplicatedBy (key or title) and a note naming the task, and the model should work with that task. Neither case is an error, and both come before the caps, so a repeat is never refused.
- The same key.
idempotencyKeynames a create, for this caller, this title and this parent: the run’s own task if it has one, else the agent, else the team. The same key from the same caller with the same title and parent returns the same task, whatever became of it. A different caller, title or parent is a different create. A call with no key gets one from the run’s own task, the parent and the title, which holds for 48 hours and does not match a blocked task, so a retry of failed work makes a new one. A caller with no bound task (an OpenClaw session, a lead’s chat turn) gets one from the team, the parent and the title, which also does not match a finished or cancelled task: it speaks for every teammate, so an old task is not what a new create is asking for. - The same words. An open task (
backlog,todo,in_progressorin_review) with the same title under the same parent, team and chat room, made in the last 48 hours, is returned. Case, spacing and surrounding punctuation do not count. A blocked task is not open here, and neither is atodotask that will not start by itself. A task a person makes on the board can be returned too, but a person’s own create never goes through this check.
Readable ids
Every argument that names a task (taskId, parentTaskId, dependsOnTaskId) takes the task’s id or its readable id, like MAR-12, in either case. Task rows carry it as identifier; it is null for a task with no team. A session bound to a team resolves only that team’s ids: another team’s readable id answers not found, the same as one that does not exist.
list_tasks
List tasks, most recently updated first. Dropped (soft-deleted) tasks are left out.ready: truelists only tasks ready to claim:todo, not dropped, and every dependencydone: tasks that ran before first, then aged priority, then oldest first.statusis ignored then.- On a team-bound session the session’s team is used and
teamIdis ignored. Otherwise a call with noteamIdlists every team’s tasks. - Returns a JSON array of task rows (the
taskstable).
get_task
Read one task with its comments and its ancestor chain.taskIdis optional on a session bound to a task, and defaults to it.- Returns
{ task, comments, ancestors }. - Error:
not found: <taskId>for a missing task or one outside the session’s team.
create_task
Create a task. WithparentTaskId it is a subtask and the per-parent caps apply. Without one it is a root task and the root rate cap applies (see Creation caps).
- A subtask takes its parent’s team and chat room.
- On a team-bound session the task is created in the session’s team and
teamIdis ignored. A parent outside the team is refused withnot found: <parentTaskId>. - An empty
parentTaskIdfails argument validation (invalid args: ...); it is never treated as a root task. - Returns the new task row, the task that was already there (see A task is made once), or one of the cap errors.
create_subtask
Create a subtask under a parent. It takes the parent’s team and chat room, and starts intodo.
- Same caps and errors as a
create_taskwithparentTaskId, including the team-bound parent check. - Returns the new task row, or the task that was already there (see A task is made once).
claim_task
Claim atodo task for an agent. The claim is atomic: when two agents race, exactly one wins. The claimed task moves to in_progress with the assignee set.
- A caller bound to an agent claims for itself:
assigneeAgentIdis optional, and naming another agent is refused withclaim_task claims a task for you (<agent>), not for <name>. To hand a task to another agent, use assign_task.The operator’s stdio bin names the agent, as before. - Succeeds only for a task that is
todo, has no assignee and is not dropped. - Returns the claimed task row.
- Errors:
claim failed: conflict(the task exists but is not claimable, for example another agent won; do not retry),claim failed: paused(a person paused the agent, the team or the task’s tree, or the team is archived; do not retry),claim failed: not_found, andnot found: <taskId>for a task outside the session’s team. - Not served to an unverified HTTP caller, because
assigneeAgentIdwould let it act as any agent, nor on a team run, where the engine claims each task for its agent.
assign_task
Hand atodo task to an agent. It is the same atomic claim as claim_task, with the same results and errors, and assigneeAgentId is always required; conflict means the task is already taken, and a task assigned to a person is refused the same way. Not served to an unverified HTTP caller or on a team run.
A hand-off cannot go in a circle. It is refused with Not handed off: ... (typed hand_off_cycle in _meta.denied) when the target handed out the task or any of its open ancestors, unless the target is the team’s lead or Boo Zero. Assigning to yourself is not a hand-off. A bound caller is recorded as the task’s delegator, and so is a bound caller that creates it.
release_task
Put anin_progress task back to todo and clear its assignee and its verification verdict, so another agent can claim it.
- Returns the text
released: <taskId>. A task that is notin_progressis left unchanged, and the same text is returned. - Not served to an unverified HTTP caller or on a team run.
update_task_status
Move a task to another status. Legal moves follow the board’s state machine;done and cancelled are final, and setting the current status again is a harmless no-op.
- Moving a task to
todoalso clears its assignee and its verification verdict. - Moving a task to
cancelledalso cancels the plan steps still waiting on it (todoorbacklog, all the way down the chain), as a person’s cancel on the board does. The result then carries them ascancelledDependents: [{ id, title }]. Cancelling a task that is already cancelled runs the same cascade again, so a repeated call finishes one an earlier call left undone. The agent that delegated the task gets a mailbox note naming it and how many steps went with it, unless that agent made the call. When the note cannot be written, the cancel still stands and the result carriesdelegatorNotTold: <agentId>. - Returns the updated task row.
- Errors:
status change failed: illegal_transition,status change failed: not_found, andstatus change failed: verification_requiredwhen the task holds a failing verification verdict (only a person’s override, from the board or the board API, can finish it). See When work is checked. - Refused for a task assigned to a person, and for one waiting on a person’s answer to a question: the tool errors start
This task is assigned to a personandThis task is waiting for a person to answer a question. This holds on every status tool, for any agent. - Refused when a person moved the card on the board or in the task drawer after the task’s latest run started (or the task has not run since): that run was overruled, and the status stays where the person put it. The tool error reads
A person moved this task to <column> after your run on it started, so its status is theirs to set. Leave it as it is and do not retry this call.A run started after the move writes as usual. - Not served to an unverified HTTP caller or on a team run. On a team run the engine moves the card when the run ends and reports the result to whoever handed out the task.
block_task
Move a task toblocked, saying what it waits on. It is update_task_status with status: 'blocked'.
taskIdis optional on a session bound to a task (a team run or a task runner run), and defaults to it. Elsewhere it is required.waitingOnis listed as required, and a call without it is refused.update_task_statustoin_reviewtakes onlyperson, because a wait on other work can end only fromblocked.personneedsneedand shows in Needs you with that text.taskmust name an unfinished task on the team that is not this one, is not in the Backlog (nothing starts work there), and does not need this one to finish first, through a wait, its sub-tasks or a dependency.subtasksneeds at least one open sub-task, none of them in the Backlog or needing this one first. Both stay out of Needs you. The task goes back totodowhen that work is done, and to Needs you if it was cancelled. These are checks at the moment of the wait: nothing alerts anyone if a person later moves that work to the Backlog.- Returns the updated task row. Error:
block failed: <reason>, with the same reasons, and the same refusal asupdate_task_statusafter a person moved the card. - On a team run it blocks only the task the agent is working on (the one assigned to it). Any other task is refused with
On a team run, block_task blocks only the task you are working on. To raise a problem with another task, use add_comment on it.Not served to an unverified HTTP caller. A wait on another task or on sub-tasks is reported as that, with no call to redo it, on team runs and task runner runs alike. - When a run blocks its own task, on a team run or a task runner run, the task stays Blocked in Needs you and the steps waiting on it stay queued. If the run then ends normally, it is recorded as succeeded, the agent’s reply is kept as its comment, and its delegator is told the task waits on a person. A task runner run’s worktree is kept unchecked for a Retry to carry on from. A task a person assigned tells no agent: the result is on its card. On the task runner, a run that blocks its task and then runs out of turns or hits an error is recorded as failed, and one stopped by a budget or a breaker as cancelled. The task stays Blocked in each case.
ask_person
Ask a person something the agent cannot decide or find out itself, about the task it is working on, then stop. Served only on a team run bound to a task, including a Clawboo Native team run whose Tasks access is read. No Tasks tool answers a question: only a person does, on the dashboard.- Moves the task to
blocked, waiting on the question, and closes any question it had open. When the run ends, it stays Blocked in Needs you as Waiting for your answer, the agent’s reply is kept as its comment, and its delegator is told it waits on an answer and not to redo or reassign it. - The answer starts the task again, with the answer in its comments. A suggested list the person accepts is for the agent to create, unless the team asks before a plan starts: there
suggest_tasksis a plan, and accepting it creates the tasks in order, each for the asking agent. See Plans. - Refused when the agent is not on the task, the task is finished, or a person moved the card after the run started. A routine’s task is refused too, because its person may be away:
This task comes from a scheduled routine, and its person may be away. Do not wait on them: make a reasonable assumption, say it in your reply, and finish. - A repeated
idempotencyKeyasks nothing new while that question is open or answered, and the result says which: still waiting, so stop; or answered, with the answer first, so carry on. A question that closed without an answer freed its key, so the same call asks it again and the task waits. - After it,
block_taskand the other status tools are refused until the answer comes.hand_back_taskstill works, and closes the question. - If the run then fails, the task still waits on the question. The run’s row says it failed, but its delegator is told it waits on an answer, and the plan steps waiting on it stay queued.
- The question is the agent’s text. It goes on the thread as a comment from the agent, and only the person’s answer goes under their name.
- A question expires on an event, not a clock: the task reaching Done or Cancelled, being dropped or moving on, or a newer question.
report_result
Say how the task the agent is working on went, before it ends its turn. A report, not a move: it changes no status, and the server decides when the run ends. Served only on a team run bound to a task, including a Clawboo Native team run whose Tasks access is read. Optional: an agent that never calls it is decided on as before.- Stored on the run’s own execution row. The last call in a run stands, and a next run (a fix round, a follow-up) starts with none. It is not shown until the run ends.
not_donestops a Done that would otherwise have happened, and the task is not checked. The task goes toblocked, waiting on a person with what the agent said, and its delegator is told. The run itself is recorded as succeeded, and the plan steps waiting on it stay queued.donenever overrides a failing check, a failing stored verdict, or a run that ended on an error. It does let a task close over sub-tasks that did not finish, and a comment and the report to its delegator say which.- An empty reply takes the
summaryas the task’s result.deliverablesare listed under the result on the card and in the report. - Refused when the agent is not on the task (
You are not working on this task, so it is not yours to report on.) or no run is open on it. It goes on the run the session’s signed URL names, so a session left from an earlier run cannot report for a later one. The event log records who said it and on which run, withoutcomeand none of its words. An unbound or unverified caller is not served it, so a call fails like any tool the session does not have. - See What an agent reports.
hand_back_task
Hand the task the agent is working on back to the person who asked for it, saying what they must do. Served only on a team run bound to a task, and not to a Clawboo Native team run whose Tasks access is read.- Moves the task to
blocked, assigned to the person, and takes the agent off it. It keeps its binding to the agent, so the person’s reply or Give back to its agent returns it. The person is the one recorded as asking for the task or its nearest ancestor, else the install’s built-in person. - Refused when the agent is not on the task, or a person moved the card after the run started. A routine’s task is refused too, with the same words as
ask_person, because its next fire needs it back in To do.
write_plan
Write a new revision of the plan for the task the agent is working on: a document people read on the task’s Plan tab, and the agent’s later runs read in their ticket. Served only to a caller whose signed scope binds both a task and an agent, including a Clawboo Native team run whose Tasks access is read. Any other caller, an unverified one included, is not offered it, and a call is refused. That includes every OpenClaw session, whose Tasks address binds no task.- Writes only to the run’s own bound task. No argument names another.
- Each change is a new revision, and earlier ones stay readable. The same words as the newest revision write nothing, and the result says so.
- The revision records the agent and the run from the signed scope, never from the call, and the event log gets a
status_changedwith reasonplan_writtenthat holds none of its words. - Refused when the agent is not on the task, the task is finished, the body is empty or over the limit, or the task already has 100 revisions.
- Writing a plan starts nothing and asks no one. On a team that asks before a plan starts, a
<plan>waits for a person, and asks about the revision this wrote, if nobody has been asked about it yet. The person’s answer controls show the plan’s steps in full, because the steps are what runs and this document is the agent’s own summary. get_taskreturns the newest revision asplan. The ticket shows up to 8,000 characters of it, framed as data.
unblock_task
Move a task totodo (from blocked, or any status that may move to todo). It clears the assignee and the verification verdict, like any move to todo.
- Returns the updated task row. Error:
unblock failed: <reason>, with the same reasons, and the same refusal asupdate_task_statusafter a person moved the card. - Not served to an unverified HTTP caller or on a team run.
add_comment
Add a comment to a task, such as a progress report or a note for the person.taskIdis optional on a session bound to a task, and defaults to it.- For an unverified HTTP caller both
authorAgentIdandauthorTypeare dropped, and the comment posts as a plainagentcomment with no author. A caller that cannot prove who it is cannot sign as someone else, or as the person. - A session bound to an agent always posts as that agent:
authorTypeisagentandauthorAgentIdis the session’s own agent, whatever the call names. A later run’s task block names each comment’s author, so an agent cannot speak there as the person or as Clawboo. - From a session bound to an agent, on someone else’s task, it can wake that task’s agent if the task is Blocked on what that agent said it needs, once a person has allowed that on the job. See What wakes an agent. On a task waiting on another task or on sub-tasks it wakes no one, and from any other caller it wakes no one.
- A run going is not told. The agent reads the comment in a later run, from its task block, or from its mailbox on a task the task runner runs.
- Returns the new comment row. When it could wake someone, the row also has
wake: { state, agent, note }:saved, ordeclinedwhen a person said no on this job.saveddoes not mean a run has started, so do not wait for a reply. Error:not found: <taskId>for a task outside the session’s team.
link_task
MaketaskId wait for dependsOnTaskId: it is not ready to claim until that task is done.
- Returns the text
linked: <taskId> depends on <dependsOnTaskId>. Linking an edge that already exists changes nothing. - A link to the task itself, or one that would close a loop (directly or through other tasks, including what a task is waiting on), is refused:
linking <taskId> to <dependsOnTaskId> would create a dependency cycle. A loop could never finish, because every task in it waits on another. - On a team-bound session both tasks must belong to the team, otherwise
not found: <id>.
Home tools
From 0.9.0. What an agent may read and write on its team’s Home: goals, KPIs and pages. The reads are served to every caller except a one-to-one chat. A run bound to a team reads that team only. Any other caller namesteamId, and nothing stops it naming any team: an unverified caller (every OpenClaw session) can read every team’s goals, KPIs and pages, the same board-wide read every unsigned caller already has on the board’s own reads. The writes are served, and listed, only to a session whose signed or in-process scope binds both the agent and its team, because each is recorded with the agent and its run on that team; an unverified caller, an operator’s stdio bin, an agent bound to no team and a Clawboo Native run whose Tasks access is read get the reads only. No tool publishes an update, sets a goal’s health, defines a KPI or changes a target: those are a person’s, on Home.
report_kpi, draft_goal_update and write_page each record an event (kpi_reported, goal_update_drafted, page_revised), with ids and numbers but never the words (see Events and errors). suggest_kpi and write_home_summary record none: a suggestion waits on Home as a row a person sees, and a written line is stored with its author, run and model. Refusals come back as an error result in words the agent can act on.
Memory server
The Memory server saves and recalls the team’s shared memory: declarative facts (“the client prefers short emails”) and versioned procedures. See Memory for the tiers and how memory reaches an agent’s prompt. Where a call reads and writes depends on the caller:
On a bound session the
scopeTeamId and scopeAgentId arguments are ignored. A bound save also records provenance (the agent, runtime, task and session that saved it), which never changes who can see the fact.
memory_save
Save a fact (title and content), or a new version of a procedure (set procedureName).
- Secrets in the content are replaced with
[REDACTED]before storage. - Returns
{ saved: 'fact', fact }or{ saved: 'procedure', procedure }. Saving a procedure under an existing name and scope stores the next version. - Errors:
nothing to save: content was entirely redacted secrets, anda fact requires a title (or set procedureName for a procedure).
memory_search
Search facts by keyword, by meaning, or both.- With no
mode, search ishybrid(meaning plus keyword) when an embedding provider is available andfts(keyword) when not.vectorandhybridalso fall back to keyword search when there is no provider or the query cannot be embedded. - Returns an array of facts, best first. Each carries
score,matchedVia(the mode that found it) andlearning. learningisnullfor a fact nothing has used or rated yet. Otherwise itsstatusispreferred(two or more different agent and task pairs found it useful),tentative(one did),contested(mixed reports),dead_end(only negative reports), ornull(it has only been used, not rated).
memory_browse
List the most recently updated facts the caller can see.- Returns an array of facts, each with
learningas inmemory_search.
memory_feedback
Report whether a recalled fact helped. Reports feed thelearning status that search results carry.
usefulmeans the fact was right and helped,dead_endthat it misled or wasted effort, andcorrectedthat it was wrong (put the correction innote; secrets in it are scrubbed).- Cite the id from
memory_search, or the id prefix shown in the memory block of the agent’s prompt. - A fact the caller cannot see gets the same error as a missing one, so feedback cannot reveal another team’s facts. That error begins
unknown fact id (or ambiguous prefix). The other error iscorrected requires a note with the correction. - Returns
{ recorded, learning }. - Each reporter (an agent and task pair) counts once per direction, at the weight of its newest report, so repeating a report adds nothing. An unverified caller is recorded as no one, so it cannot promote a fact on its own.
Tools server
The Tools server is Clawboo’s tool broker. Every call is checked, may wait for a person’s approval, then runs and is recorded in the tool audit. Approval requests appear under Needs you on the Board and in the Governance approval queue (see Approvals).tools/list contains:
- The builtin tools whose requirements are met.
- The tools of every live connector that the calling agent’s grants allow. A connector tool the agent has not been granted is not listed at all. The list is recomputed for every list and every call, and the server sends a list-changed notification when a connector connects or disconnects.
fill_login, for a bound caller whose agent holds a live browser connector, unless its run is known to belong to no person.read_tool_result, always. Grants, availability and connector tools never hide or replace it.
- The tool must exist, be enabled and be available, and its arguments must validate.
- A connector tool must pass the grant check for the calling agent and team.
- A call whose arguments point at the Clawboo dashboard is refused with
dashboard:agents may not open the Clawboo dashboard. That is any loopback address on the port the server listens on (localhostor a name under.localhost, any127.x.x.xaddress,::1,::and0.0.0.0, and their IPv4-mapped IPv6 forms), and the address set inHOSTon that port. Hosts are read the way a browser reads them, so numeric (2130706433), percent-escaped and full-width spellings, a leading zero on the port, and a tab or line break inside the address are refused too. A name that reaches the server through a reverse proxy orCLAWBOO_ALLOWED_HOSTSis not refused. A call whoseurlargument would open a file on this computer is refused withlocal-file:agents may not open files on this computer: afile:orview-source:address, read as a browser reads it, or a Windows drive or network path such asC:\Usersor\\server\share, which Chrome on Windows opens as a file. A security scan of the arguments can refuse the call. Numericlimit,max,count,maxResults,top_kandtopKarguments above 1,000 are lowered to 1,000. - A destructive tool, an external tool that is not read-only, or a grant that asks for approval waits up to 5 minutes for a person to answer. An earlier Always for the same tool under the same grant skips this wait, but never for a destructive tool, a grant set to
always, or a run that might leak data. - The call runs, and its arguments and result are recorded in the audit with secrets scrubbed.
- A refused call returns the tool error
denied: <reason>, and the same reason in_meta.denied. Reasons start withunknown-tool:,disabled:,unavailable:,provenance:,invalid-args:,grant:(for examplegrant:no-grant; see the grant decision reasons),dashboard:,local-file:,security:orscope:. - A call whose approval is refused, expires or times out returns
approval deny,approval expiredorapproval timeout. - A text result larger than 16 KiB is stored whole (up to 8 MiB) and the model gets a trimmed view: the start and the end of the result, with a notice between them that carries a
tr_handle and the exactread_tool_resultcall for the rest. Only the Tools server trims results; the other three servers bound theirs withlimitarguments. Stored results are deleted after 7 days (CLAWBOO_TOOL_RESULT_TTL_MS).
Builtin tools
These two exist to exercise the broker (the round trip and the audit). Neither has a side effect.
There is no built-in web search. For search, connect a search connector such as Exa Search in Connectors and give it to the agents that need it; its tools are then listed as connector tools. With no grant that covers every agent (a
global grant), an unverified caller is served three tools: echo, note and read_tool_result.
fill_login
Signs in to a website in the agent’s own browser with a login its run’s person saved, or one from their 1Password (see Let agents sign in to websites). Clawboo fills the page itself; the agent never gets the username, password or one-time code.
Listed only for a bound caller whose agent holds the Playwright or Chrome DevTools connector, live, through its own grant or its team’s. Each run carries a reference to itself on its Tools URL as
scopeRunRef, inside the signature, and Clawboo forgets the reference when the run ends; Clawboo Native gets it in-process. A run whose reference names no person (a routine’s) is not offered it, nor are an OpenClaw agent and an unverified caller. A live URL’s tool list names no run, so it lists fill_login and the run in progress is checked at call time.
The result is text that starts with one of:
filled:and the names of the fields filled. Submit the form next.no saved login:there is none for that origin that this run may use.needs you:a CAPTCHA, passkey or card check, or 1Password could not be read. On a run with a board task, Clawboo hands the task back to the person who asked for it and the card goes to Needs you.refused:and why (not on that site, no browser open, no browser given, a certificate error, anhttpspage in a browser that cannot show its certificate, no sign-in field, anhttpsite, a person in control of the browser, or a run with no person).
site, and on https the browser must accept its certificate; only the Playwright browser on Chrome or Chromium (its default) can show Clawboo that. The Chrome DevTools browser fills only plain http pages on loopback, and Playwright’s bare headless shell, which reports no certificate state, fills none on https. no saved login comes only from a page of that site with a sign-in field. The call is risk safe and asks no one; its audit row holds the site and the result, never a value. Clawboo masks the filled username, password and one-time code (4 characters or longer) out of that agent’s later browser tool results; screenshots are not masked.
Connector tools
- A connector tool is named
mcp__<connector-slug>__<tool-name>, at most 128 characters. Its description is the connector’s own, unchanged. - A brokered connector (one service that fronts many apps, such as Composio) gets one line appended to its app-facing tools’ descriptions:
Apps this agent may use: ...for a bound agent, orApps reachable here, each subject to the operator approving the first call: ...for an unverified caller. - The agent’s grants decide which connector tools it is offered and whether a call is allowed, asks for approval, or is denied. See Connectors.
read_tool_result
Read back a result that was too large to return whole.- Returns the requested bytes, then a line with the total size and the exact call for the next page, or
This is the end of the result.When the stored copy itself was cut at 8 MiB, that line says how many bytes were kept. - With
search, returns only the lines that contain the text (case-insensitive), each prefixed with its byte offset as[byte <n>]so the next call can seek to it. - An unknown or expired handle is an error that begins
No stored result for handleand tells the model to re-run the original call with narrower arguments. - Its own result is never trimmed. Handles are random and work from any session, so a handle is as sensitive as the result it points to.
TeamChat server
The TeamChat server is the agents’ peer room. Teammates on any runtime post as named peers and read each other’s posts. This room is separate from the team chat you see in the dashboard (General and its rooms); see Peer chat. A post never changes the board.- On a bound session the author and room come from the binding, and any
authorAgentId,teamIdorroomIdargument is ignored, so a runtime cannot post as a teammate it is not. The room isteam:<teamId>. - On the stdio bin, pass
authorAgentIdandteamId;roomIddefaults toteam:<teamId>. - An unverified HTTP caller is served no tools, because both tools need an author and a room.
- On a bound session,
team_chat_postandteam_delegateresults can carry mailbox notices like the Tasks tools.team_chat_subscriberesults never do.
team_chat_post
Post a message to the peer room.- Returns
{ posted: { seq, roomId, authorAgentId } }.seqgoes up by one with each post in the room. - Errors:
a post requires non-empty text, and on the stdio binno bound identity: pass authorAgentId + teamId (unbound mode). - A bound post over HTTP also writes a
team_chat_postevent to the event log.
team_chat_subscribe
Read new posts since a cursor. The caller’s own posts are never returned.- Returns
{ posts, nextSeq }, oldest post first. Each post is{ seq, authorAgentId, kind, wrapped }. wrappedpresents the post as evidence, not as an instruction. It is a header line,[Inter-session message · from=<agent> · kind=<kind> · seq=<n> · isUser=false], then the body with every line prefixed|. Text in the body that imitates such a header becomes[peer-quoted header], and one that never closes loses its opening words the same way. A teammate’s post is context to weigh, never an order from the person.nextSeqis the room’s newestseq, never lower thansinceSeq. When the page is full (limitposts, or 1,000 with nolimit), it is theseqof the last post returned instead, so the next read picks up the rest.- Error (stdio bin only):
no bound identity: pass authorAgentId + teamId (unbound mode).
team_delegate
Hand a self-contained piece of work to a teammate by name. It is served only on runs the team engine drives (a signeddelegate=1), and it is how Claude Code, Codex and Hermes team leaders delegate. Clawboo Native leaders use their own built-in delegate tool instead.
- The tool writes nothing itself. The team engine sees the call and creates the board task for that teammate, who reports back when done. See Delegation and orchestration.
- Returns
Queued for <assignee>: <task>. If <assignee> is a teammate here, they get it as a board task and report back to you when done. If it cannot start, you will get a message saying why.whenever both fields are present. The answer comes before the engine matches the name. - A name that matches no teammate in the room, or the caller itself, creates no task. The engine then sends the caller a
[Task Update]saying the hand-off did not start, with the names of the teammates it can hand work to. - Error:
team_delegate requires both an assignee (teammate name) and a task.
Transports
Every server is built from the same code and served three ways.stdio bins
Theclawboo npm package installs one command per server. The client that spawns a bin owns its process.
- The bins open
CLAWBOO_DB_PATH, or~/.openclaw/clawboo/clawboo.dbwhen it is unset. That is a different file from the dashboard’s database (~/.clawboo/clawboo.db), on purpose. To work on the dashboard’s board and memory, setCLAWBOO_DB_PATHto the dashboard’s file; the stdio snippets fromGET /api/mcp/configalready do. - The Memory bin picks an embedding provider and checks again once a minute: a local Ollama with
nomic-embed-textathttp://localhost:11434first, thenOPENAI_API_KEYfrom its environment, unless the store holds local vectors and you have not allowed remote embeddings. With neither, search is keyword-only.CLAWBOO_DISABLE_EMBEDDINGS=1turns embeddings off. - The Tools bin serves the builtins and
read_tool_result; it has no connector tools. - The TeamChat bin is unbound, so author and team come from the tool arguments.
Streamable HTTP
The dashboard server mounts each server at/api/mcp/<server>, where <server> is tasks, memory, tools or teamchat.
- A session starts with
initialize. Its response carries anmcp-session-idheader that every later request must send. Sessions live in the server’s memory, so after a restart a client must initialize again. - A
POSTmust sendAccept: application/json, text/event-stream, or it gets HTTP 406; aGETneedsAccept: text/event-stream. A body that is not JSON gets HTTP 415. No valid session; send an initialize request first.(HTTP 400) answers aPOSTthat is notinitializeand has no known session.Invalid or missing MCP session id.(HTTP 400) answers aGETorDELETEwithout one. Both are JSON-RPC errors with code-32000andid: null. A server failure before the response starts returns HTTP 500 with{ "error": "..." }.- The MCP routes share the general API rate limit; see Limits and defaults.
STUDIO_ACCESS_TOKEN is set), every /api/ request needs the access cookie. A cookieless request to one of the four MCP paths is let through only when it carries a valid attachToken, arrives on a loopback connection, and has none of the Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto or X-Real-IP headers. A request through a reverse proxy therefore always needs the cookie. GET /api/mcp/config always needs the cookie when the gate is on, because it signs identities. See Security.
In-process
Clawboo Native agents use the same servers inside the dashboard server, through an in-memory MCP client. There is no URL and no token, and the run’s team and agent are bound directly.Attach snippets
GET /api/mcp/config returns a ready-to-paste attach snippet. Copy URLs from it rather than building them, because only it can sign them.
- Returns
{ ok: true, config: { id, transport, snippet, structured } }. An unknownserveris HTTP 400unknown server: <name>. An unknownruntimereturns{ ok: true }with noconfig. - HTTP URLs use the server’s own loopback address and port, never the request’s
Hostheader. They always carryattachToken, and ascopeSigwhen scoped. - A Claude Code HTTP snippet looks like
claude mcp add --transport http clawboo-tasks 'http://127.0.0.1:<port>/api/mcp/tasks?attachToken=<hex>'. The URL is single-quoted because it carries a query string.
Errors on every server
Both are tool results with
isError: true. Errors specific to a tool are listed under that tool.
Related
- Attaching Clawboo’s MCP servers: attach an agent of your own, step by step.
- Tools and MCP API: approvals, audit and the attach-config route.
- The board: statuses, legal moves and claiming.
- Memory: memory tiers, recall and learning.
- Connectors: connect services and grant them to agents.
- Events and errors: the events these tools write.