Tools

OpenClaw exposes first-class agent tools for browser, canvas, nodes, and cron. These tools replace the old openclaw-* Skills: tools are typed, don't require shell invocation, and agents should depend on them directly.

Disabling Tools

You can globally allow/deny tools via tools.allow / tools.deny in openclaw.json (deny takes precedence). This prevents disallowed tools from being sent to model providers.

{
  tools: { deny: ["browser"] },
}

Notes:

• Matching is case-insensitive.
• * wildcards are supported ("*" means all tools).
• If tools.allow only references unknown or unloaded plugin tool names, OpenClaw logs a warning and ignores the allow list to ensure core tools remain available.

Tool Profile (Base Allow List)

tools.profile sets a base tool allow list before tools.allow/tools.deny. Per-agent override: agents.list[].tools.profile. Profiles:

• minimal: Only session_status
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: Unrestricted (same as unset)

Example (messaging only by default, with Slack + Discord tools allowed):

xxxxxxxxxx
{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

Example (coding profile, but deny exec/process everywhere):

xxxxxxxxxx
{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

Example (global coding profile, messaging-only support agent):

xxxxxxxxxx
{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

Provider-Specific Tool Policies

Use tools.byProvider to further restrict tools for specific providers (or single provider/model) without changing your global defaults. Per-agent override: agents.list[].tools.byProvider. This is applied after the base tool profile and before allow/deny lists, so it can only narrow the tool set. Provider keys accept provider (e.g., google-antigravity) or provider/model (e.g., openai/gpt-5.2). Example (keep global coding profile, but Google Antigravity uses minimal tools):

xxxxxxxxxx
{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Example (provider/model-specific allow list for flaky endpoints):

xxxxxxxxxx
{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

Example (agent-specific override for a single provider):

xxxxxxxxxx
{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

Tool Groups (Shorthand)

Tool policies (global, agent, sandbox) support group:* entries, which expand to multiple tools. Use these in tools.allow / tools.deny. Available groups:

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:openclaw: All built-in OpenClaw tools (excluding provider plugins)

Example (allow only file tools + browser):

xxxxxxxxxx
{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

Plugins + Tools

Plugins can register additional tools (and CLI commands) beyond the core set. See Plugins for installation + configuration, and Skills for how tool usage guidance is injected into prompts. Some plugins come with their own Skills (e.g., the voice-call plugin). Optional plugin tools:

• Lobster: Typed workflow runtime with resumable approvals (requires Lobster CLI on the Gateway host).
• LLM Task: JSON-only LLM step for structured workflow output (optional schema validation).

Tool Inventory

apply_patch

Apply structured patches across one or more files. Used for multi-block edits. Experimental: enabled via tools.exec.applyPatch.enabled (OpenAI models only).

exec

Run shell commands in the workspace. Core parameters:

• command (required)
• yieldMs (auto-background after timeout, default 10000)
• background (run immediately in background)
• timeout (seconds; kill process if exceeded, default 1800)
• elevated (boolean; if enabled/allowed elevated mode, runs on host; only changes behavior when agent is sandboxed)
• host (sandbox | gateway | node)
• security (deny | allowlist | full)
• ask (off | on-miss | always)
• node (node id/name when host=node)
• Need a real TTY? Set pty: true.

Notes:

• When running in background, returns status: "running" with a sessionId.
• Use process to poll/log/write/kill/clear background sessions.
• If process is not allowed, exec runs synchronously and ignores yieldMs/background.
• elevated is gated by tools.elevated plus any agents.list[].tools.elevated override (both must allow), and is an alias for host=gateway + security=full.
• elevated only changes behavior when the agent is sandboxed (otherwise a no-op).
• host=node can target macOS companion apps or headless node hosts (openclaw node run).
• Gateway/node approvals and allow lists: Exec Approvals.

process

Manage background exec sessions. Core operations:

• list, poll, log, write, kill, clear, remove

Notes:

• poll returns new output, and exit status when complete.
• log supports line-based offset/limit (omit offset to get last N lines).
• process is scoped by agent; sessions from other agents are invisible.

web_search

Search the web using the Brave Search API. Core parameters:

• query (required)
• count (1-10; default from tools.web.search.maxResults)

Notes:

• Requires a Brave API key (recommended: openclaw configure --section web, or set BRAVE_API_KEY).
• Enabled via tools.web.search.enabled.
• Responses are cached (default 15 minutes).
• See Web Tools for setup.

web_fetch

Fetch and extract readable content from a URL (HTML → markdown/text). Core parameters:

• url (required)
• extractMode (markdown | text)
• maxChars (truncate long pages)

Notes:

• Enabled via tools.web.fetch.enabled.
• Responses are cached (default 15 minutes).
• For JS-heavy websites, prefer the browser tool.
• See Web Tools for setup.
• See Firecrawl for optional anti-bot fallback.

browser

Control a dedicated OpenClaw-managed browser. Core operations:

• status, start, stop, tabs, open, focus, close
• snapshot (aria/ai)
• screenshot (returns image block + MEDIA:<path>)
• act (UI operations: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
• navigate, console, pdf, upload, dialog

Profile management:

• profiles — List all browser profiles and their status
• create-profile — Create a new profile with auto-assigned port (or cdpUrl)
• delete-profile — Stop browser, delete user data, remove from config (local only)
• reset-profile — Kill orphaned processes on profile port (local only)

Common parameters:

• profile (optional; defaults to browser.defaultProfile)
• target (sandbox | host | node)
• node (optional; select specific node id/name)

Notes:

• Requires browser.enabled=true (defaults to true; set to false to disable).
• All operations accept an optional profile parameter for multi-instance support.
• When profile is omitted, browser.defaultProfile is used (defaults to "chrome").
• Profile names: lowercase alphanumeric + hyphen only (max 64 chars).
• Port range: 18800-18899 (approx 100 profiles max).
• Remote profiles only support attach (no start/stop/reset).
• If a browser-capable node is connected, tools may auto-route to it (unless you pinned target).
• snapshot defaults to ai when Playwright is installed; use aria for accessibility tree.
• snapshot also supports role snapshot options (interactive, compact, depth, selector), returning refs like e12.
• act requires a ref from snapshot (12 from AI snapshot, or e12 from role snapshot); use evaluate for rare CSS selector needs.
• Avoid act → wait by default; use only in special cases (no reliable UI state to wait for).
• upload can optionally pass ref to auto-click after ready.
• upload also supports inputRef (aria ref) or element (CSS selector) to directly target <input type="file">.

canvas

Drive node Canvas (present, eval, snapshot, A2UI). Core operations:

• present, hide, navigate, eval
• snapshot (returns image block + MEDIA:<path>)
• a2ui_push, a2ui_reset

Notes:

• Internally uses Gateway node.invoke.
• If no node is provided, the tool picks a default (single connected node or local mac node).
• A2UI is v0.8 only (no createSurface); CLI rejects v0.9 JSONL with line errors.
• Quick smoke test: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

nodes

Discover and locate paired nodes; send notifications; capture camera/screen. Core operations:

• status, describe
• pending, approve, reject (pairing)
• notify (macOS system.notify)
• run (macOS system.run)
• camera_snap, camera_clip, screen_record
• location_get

Notes:

• Camera/screen commands require the node app to be in the foreground.
• Images return image block + MEDIA:<path>.
• Videos return FILE:<path> (mp4).
• Location returns JSON payload (lat/lon/accuracy/timestamp).
• run parameters: command argv array; optional cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

Example (run):

xxxxxxxxxx
{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

image

Analyze images using the configured image model. Core parameters:

• image (required path or URL)
• prompt (optional; defaults to "Describe the image.")
• model (optional override)
• maxBytesMb (optional size limit)

Notes:

• Only available when agents.defaults.imageModel is configured (primary or fallback), or when an implicit image model can be inferred from your default model + configured credentials (best-effort pairing).
• Uses image model directly (independent of the main chat model).

message

Send messages and channel operations across Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams. Core operations:

• send (text + optional media; MS Teams also supports card for Adaptive Cards)
• poll (WhatsApp/Discord/MS Teams polls)
• react / reactions / read / edit / delete
• pin / unpin / list-pins
• permissions
• thread-create / thread-list / thread-reply
• search
• sticker
• member-info / role-info
• emoji-list / emoji-upload / sticker-upload
• role-add / role-remove
• channel-info / channel-list
• voice-status
• event-list / event-create
• timeout / kick / ban

Notes:

• send routes WhatsApp through the Gateway; other channels send directly.
• poll uses the Gateway for WhatsApp and MS Teams; Discord polls send directly.
• When the message tool call is bound to an active chat session, sends are restricted to that session's target to avoid cross-context leakage.

cron

Manage Gateway scheduled tasks and wake. Core operations:

• status, list
• add, update, remove, run, runs
• wake (enqueue system event + optional immediate heartbeat)

Notes:

• add expects a complete task object (same schema as cron.add RPC).
• update uses { id, patch }.

gateway

Restart or apply updates to a running Gateway process in-place. Core operations:

• restart (authorize + send SIGUSR1 for in-process restart; openclaw gateway restarts in-place)
• config.get / config.schema
• config.apply (validate + write config + restart + wake)
• config.patch (merge partial update + restart + wake)
• update.run (run update + restart + wake)

Notes:

• Use delayMs (default 2000) to avoid interrupting in-progress replies.
• restart is disabled by default; enable with commands.restart: true.

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

List sessions, check transcription history, or send to another session. Core parameters:

• sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = none)
• sessions_history: sessionKey (or sessionId), limit?, includeTools?
• sessions_send: sessionKey (or sessionId), message, timeoutSeconds? (0 = fire-and-forget)
• sessions_spawn: task, label?, agentId?, model?, runTimeoutSeconds?, cleanup?
• session_status: sessionKey? (default current; accepts sessionId), model? (default clears override)

Notes:

• main is the canonical private chat key; global/unknown are hidden.
• messageLimit > 0 gets the last N messages per session (tool messages are filtered).
• When timeoutSeconds > 0, sessions_send waits for final completion.
• Delivery/announce happens after completion, best-effort; status: "ok" confirms the agent run completed, not that delivery succeeded.
• sessions_spawn starts a child agent run and sends announce replies back to the requesting chat.
• sessions_spawn is non-blocking, immediately returns status: "accepted".
• sessions_send runs a reply round-trip ping-pong (reply REPLY_SKIP to stop; max turns via session.agentToAgent.maxPingPongTurns, 0-5).
• After ping-pong, the target agent runs an announce step; reply ANNOUNCE_SKIP to suppress announce.

agents_list

List agent IDs that the current session can target with sessions_spawn. Notes:

• Results are limited by per-agent allow lists (agents.list[].subagents.allowAgents).
• When configured as ["*"], the tool includes all configured agents and marks allowAny: true.

Parameters (Common)

Tools supported by Gateway (canvas, nodes, cron):

• gatewayUrl (default ws://127.0.0.1:18789)
• gatewayToken (if auth is enabled)
• timeoutMs

Browser tool:

• profile (optional; defaults to browser.defaultProfile)
• target (sandbox | host | node)
• node (optional; pin specific node id/name)

Recommended Agent Flows

Browser automation:

1. browser → status / start
2. snapshot (ai or aria)
3. act (click/type/press)
4. screenshot if you need visual confirmation

Canvas rendering:

1. canvas → present
2. a2ui_push (optional)
3. snapshot

Node targeting:

1. nodes → status
2. describe on selected node
3. notify / run / camera_snap / screen_record

Security

• Avoid direct system.run; use nodes → run only with explicit user consent.
• Respect user consent for camera/screen capture.
• Use status/describe to verify permissions before calling media commands.

How Tools Are Presented to Agents

Tools are exposed via two parallel channels:

1. System prompt text: Human-readable list + guidance.
2. Tool schema: Structured function definitions sent to the model API.

This means the agent sees both "what tools exist" and "how to call them". If a tool does not appear in the system prompt or schema, the model cannot call it.

For more about tools, see: Tools - OpenClaw