Tools reference

All tools available through mcp.clawnify.com via tools/call.

clawnify_execute

Run TypeScript on your agent’s managed runtime. Returns stdout, stderr, exit code, and duration.

Input:

Output:

{
  "execution_id": "<uuid>",
  "stdout": "...",
  "stderr": "...",
  "exit_code": 0,
  "duration_ms": 412,
  "timed_out": false,
  "substrate_id": "<opaque>",
  "runtime": "openclaw"
}

Notes:

• Resource caps enforced: 512 MB memory, 50% CPU, 128 tasks.
• Runs on your org’s managed runtime, isolated per-org. No cross-org compute.
• The agent’s environment is pre-wired: file system, connected integrations, and scoped credentials are all available.

clawnify_docs_search

Search across your org’s apps’ procedure docs. Returns ranked hits.

Input:

Output:

{
  "hits": [
    {
      "app_slug": "quotes",
      "app_name": "Quotes",
      "procedure_name": "createQuote",
      "snippet": "Create a new quote for a customer with line items.",
      "score": 1.5
    }
  ]
}

Procedure-level hits outweigh app-level hits.

clawnify_list_apps

List the apps in your org.

Input: none.

Output:

{
  "apps": [
    {
      "id": "<uuid>",
      "slug": "quotes",
      "name": "Quotes",
      "description": "Customer quote generation",
      "status": "live",
      "created_at": "2026-..."
    }
  ]
}

clawnify_list_agents

List your org’s agents. Each entry is one server — its single main agent (the “employee”, one per server) — with a specialized_agents array of the non-main agents on that server. Start here to find which agents exist and which server_id to pass to the session / transcript / skill tools.

Input: none.

Output:

{
  "agents": [
    {
      "server_id": "<uuid>",
      "name": "Sales Agent",   // the employee (main agent)
      "status": "ready",
      "region": "eu",
      "specialized_agents": [  // non-main agents on this server
        { "id": "lead-qualifier", "name": "Lead Qualifier", "status": "idle", "session_count": 12 }
      ]
      // "specialized_unavailable": true appears instead when the server is
      // unreachable and its specialized agents could not be read.
    }
  ]
}

Managing agents (the FDE tools)

These drive your org’s agents from an MCP client. Each takes an optional server_id (defaults to your org’s single server; with more than one, pass it — find ids with clawnify_list_agents). All require a user credential (your JWT / OAuth); an on-box agent token can’t call them.

clawnify_list_agent_sessions

A server’s stored sessions across all its agents, newest first, with token counters (a high contextTokens flags a bloated, drift-prone session).

Input: agent_id?, server_id?, limit?, active_minutes?.

clawnify_get_session_transcript

One session’s transcript tail (raw JSONL turns) — where an agent veered, looped, or burned tokens.

Input: key (from clawnify_list_agent_sessions), server_id?, agent_id?, limit?.

clawnify_list_agent_skills

The effective skill inventory an agent can actually run — workspace + shared + bundled ∩ allowlist — not just its workspace folder.

Input: agent? (default main), server_id?.

clawnify_get_agent_instructions

Read an agent’s AGENTS.md (its authored instructions) plus a content hash. Read this before editing and pass the hash to clawnify_set_agent_instructions.

Input: agent? (default main), server_id?.

Output:

{ "agent": "main", "content": "<AGENTS.md text>", "hash": "<sha256>" }

clawnify_set_agent_instructions

Replace an agent’s AGENTS.md with new full text. Reversible (write again) and reviewable — the result returns before / after, so you can show the user the diff. Takes effect on the agent’s next session, no restart. AGENTS.md only — skills are edited with the clawnify CLI, flows with the flow tools below.

Pass the hash from clawnify_get_agent_instructions as base_hash: if the file changed since you read it, the write is rejected instead of overwritten.

Input: content (required — full new text), agent? (default main), base_hash?, server_id?.

Output:

{
  "ok": true,
  "agent": "main",
  "hash": "<new sha256>",
  "changed": true,
  "before": "<old AGENTS.md text>",
  "after": "<new AGENTS.md text>"
}

Managing flows

The ClawFlow authoring loop, for clients with no terminal. Same access rule as the agent tools above: a user credential only. Each takes an optional agent_id (defaults to your org’s single agent).

A flow has two states, and mixing them up is the classic mistake: the draft is the file you edit, the published version is what runs. Which one a run or trigger executes depends on whether the flow has ever been published:

• Has published versions → the latest one runs. Your draft edit is inert until you publish it.
• Never published → the draft runs. Editing it changes production immediately, with no publish step.

clawnify_list_flows and clawnify_get_flow both report published_version (null = never published), so check it before editing.

The usual loop: clawnify_list_flows → clawnify_get_flow → edit the JSON → clawnify_write_flow (with base_hash) → clawnify_publish_flow.

clawnify_list_flows

Every flow on the agent’s box: name, description, trigger, declared inputs, node tree, and published (the live version number; null = never published, so the draft is what runs).

Input: agent_id?.

clawnify_get_flow

One flow’s full draft definition, plus a content hash and published_version.

Input: name (file base name, e.g. lead-router), agent_id?.

Output:

{
  "ok": true,
  "name": "lead-router",
  "file": "lead-router.json",
  "flow": { "flow": "lead-router", "nodes": [/* … */] },
  "hash": "<sha256>",
  "published_version": 3
}

clawnify_write_flow

Create or replace a flow’s draft with a complete FlowDefinition — the whole definition, not a patch, so read it first and send it back modified.

The box validates it against its live step registry (including plugin-registered steps like clawnify_app / clawnify_action) before writing: an invalid flow is rejected with the engine’s own errors and nothing is written. Pass the hash from clawnify_get_flow as base_hash and a concurrent edit fails instead of being overwritten.

Input: name, flow (the definition), base_hash?, agent_id?.

Output:

{
  "ok": true,
  "flow": "lead-router",
  "file": "/home/openclaw/.openclaw/workspace/flows/lead-router.json",
  "nodes": 6,
  "warnings": [],
  "created": false,
  "hash": "<new sha256>",
  "published_version": 3,
  "note": "Draft saved. The box still runs published v3 — publish to make this edit live."
}

clawnify_publish_flow

Publish the draft as the next numbered version — this is what makes an edit live. The engine re-validates, then snapshots it; earlier versions are kept.

Input: name, agent_id?. Output: { ok, flow, version, file }.

clawnify_run_flow

Start a run of the flow’s published version. Returns immediately with an instanceId — runs are asynchronous. This performs the flow’s real side effects (messages, email, writes to connected systems), so confirm before running one on someone’s behalf.

Input: name, input? (becomes the flow’s inputs), agent_id?.

clawnify_get_flow_runs

Inspect executions: pass run_id for one run in full (status, per-node trace, approval info — how to find where a flow failed), or omit it for a summary list.

Input: run_id?, name? (filter by the flow’s declared name), status? (running | completed | paused | waiting | failed | cancelled), agent_id?.

clawnify_get_usage

Current plan + quota.

Input: none.

Output:

{
  "subscription": {
    "plan": "first_hire",
    "status": "active",
    "current_period_end": "2026-..."
  }
}

company_knowledge_search

Search your org’s Company Knowledge — your single source of truth for policies, pricing, brand, SOPs, and FAQs — and get back the most relevant passages with a citation. Use it whenever you need a company fact, then cite the answer as Per <Title> v<N>.

Input:

Returns the matching passages with their title, version, and citation. An empty result means nothing matched — answer from another source.

company_knowledge_get

Read a full Company Knowledge document by id (from a search result). Returns the complete document, including links to related ones. Only published documents are visible.

Input: id (required) — the document to read; version (optional) — a specific version, otherwise the latest.

projects_list

List the Projects available to the agent — its own workspace, the company file library, and any shared client or engagement Projects. Projects hold scoped working reference for one client or engagement, separate from org-wide Company Knowledge.

Input: none. Returns each Project’s id, name, and kind.

project_search

Search within one Project (get its id from projects_list) for reference about that specific client or engagement.

Input:

memory_recall

Search the agent’s long-term memory and return the most relevant durable memories — preferences, past commitments, and facts it saved earlier.

Input:

memory_write

Save something the agent should remember across sessions — a preference, a commitment, or a stable fact. Not for throwaway task state.

Input:

<app_slug>_<procedure> — per-app direct tools

For apps with five or fewer procedures, each procedure appears as a direct tool with the same name as the procedure. Parameters and return shape match the app’s manifest.

Example:

Your quotes app has a createQuote procedure that takes { customer_id, items }. It shows up as quotes_createQuote in tools/list. The agent calls it with the same arguments it would pass to the procedure directly.

Apps with more than five procedures don’t auto-project — the agent reaches them via clawnify_execute instead (write code that imports the typed client; clawnify_docs_search helps it find the right procedure).

Errors

All tools return MCP-shaped { content: [...], isError: true } on failure. JSON-RPC errors (auth, rate limit, malformed request) come back as standard JSON-RPC error responses.

Common error codes: