Appendix A: Tool Reference

This appendix provides a complete reference for every OpenClaw tool available to practitioners. Whether you're debugging a tool call, designing a new automation, or writing skill definitions — this is the canonical reference. The tools are the primitives that all higher-level patterns are built from, and understanding their parameters, behaviors, and constraints is foundational to everything in this handbook.

OpenClaw ships built-in tools across several functional areas: file operations, shell execution, web automation, messaging, media generation, session/sub-agent management, memory, scheduling, and gateway control. Plugins can register additional tools.

Tool Summary

Tool(s) Category What it does
read, write, edit, apply_patch File operations File I/O in the workspace
exec, process Shell execution Run shell commands; manage background sessions
code_execution Shell execution Run sandboxed remote Python analysis
browser Web automation Control a Chromium browser
web_search, x_search, web_fetch Web automation Search the web, fetch page content
message Messaging Send/react/poll messages across all channels
canvas UI presentation Drive node Canvas (present, eval, snapshot)
nodes Device control Discover and target paired devices
cron, gateway Automation control Manage scheduled jobs; inspect/patch/restart gateway
image, image_generate Media Analyze or generate images
music_generate Media Generate music tracks
video_generate Media Generate videos
tts Media One-shot text-to-speech
sessions_* / subagents Session management List/history/send/spawn sessions and sub-agents
memory_get, memory_search Memory Read and search memory files
session_status Session tools Lightweight status/readback and per-session model override

File Operations

read

Read file contents with offset/limit pagination. Supports text files and images (jpg, png, gif, webp sent as attachments). Output capped at 2000 lines or 50KB per call. For large files, use offset/limit to paginate.

Parameters:
- path* (string) — file path (relative or absolute)

Optional: offset (line number to start, 1-indexed), limit (max lines)

write

Create or overwrite files. Automatically creates parent directories. Binary content not supported via this tool.

Parameters:
- path (string) — destination file path
- content (string) — content to write

edit

Make precise edits to a file using exact text replacement. Each oldText must match a unique, non-overlapping region. Do not include large unchanged regions to connect distant changes.

Parameters:
- path (string) — file to edit
- edits (array) — list of {oldText, newText} replacement pairs

apply_patch

Apply multi-hunk patches to files. More powerful than edit for scattered changes across a file.

Parameters:
- path (string) — target file
- patches (array) — patch objects with hunk ranges and content

Shell Execution

exec

Run shell commands with full control over working directory, timeout, PTY mode, security restrictions, and environment variables. The most commonly used tool for automation scripting.

Parameters:
- command* (string) — shell command to execute
- workdir (string) — working directory (defaults to cwd)
- timeout (number) — seconds before killing the process
- pty (boolean) — run in pseudo-terminal for interactive programs (coding agents, terminal UIs)
- security (string) — deny, allowlist, or full; controls exec policy enforcement
- env (object) — environment variables to inject
- yieldMs (number) — auto-background after this many milliseconds

Key behavior: exec has a restricted PATH compared to your terminal. Use full paths or inject PATH via the env parameter. This is the most common cause of "command not found" in cron jobs.

process

Manage long-running background command sessions started via exec with background:true or yieldMs. Companion tool to exec for ongoing operations.

Parameters:
- action* (string) — list, poll, log, write, send-keys, submit, kill
- sessionId (string) — session ID from exec background start

Actions: list shows all sessions; poll waits for output; log retrieves buffered output; write sends stdin; send-keys sends key tokens; submit sends a line; kill terminates the session.

code_execution

Run sandboxed remote Python analysis. Useful for data processing, math, and code evaluation without managing a local Python environment.

Parameters:
- code* (string) — Python code to execute
- language (string) — language identifier (default: python)
- timeout (number) — execution timeout in seconds

Web Automation

browser

Control a Chromium browser for JavaScript-rendered pages, login flows, and visual monitoring. Uses snapshot/screenshot/act pattern.

Parameters:
- action* (string) — status, start, stop, open, snapshot, screenshot, act, navigate, tabs
- profile (string) — browser profile: openclaw (default, isolated) or user (logged-in)
- url (string) — URL for open or navigate actions
- ref (string) — element reference for act operations
- request (object) — action details: {kind: "click|type|press|hover|drag|evaluate|wait", ...}

Act kinds: click, clickCoords, type, press, hover, drag, select, fill, resize, wait, evaluate, close

Pattern: open → snapshot (find refs) → act (click/type) → snapshot (verify)

Search the web using Brave API. Returns titles, URLs, and snippets.

Parameters:
- query* (string) — search query
- count (number) — results to return (1-10, default 5)
- freshness (string) — day, week, month, year
- country (string) — 2-letter country code
- language (string) — ISO 639-1 language code
- search_lang (string) — Brave language code for results
- ui_lang (string) — locale code for UI elements

Search X (formerly Twitter) posts. Same parameter structure as web_search but targets social content.

web_fetch

Fetch and extract readable content from a URL as markdown or plain text. Respects cache headers; add cache-busting parameters or use browser for stale content.

Parameters:
- url* (string) — HTTP or HTTPS URL
- extractMode (string) — markdown (default) or text
- maxChars (number) — truncate at this character count

Messaging

message

Multi-channel messaging hub for WhatsApp, SMS, Discord, Telegram, and more.

Parameters:
- action* (string) — send, react, poll, search, read, edit, delete, pin, thread-create, thread-reply, and many more
- target (string) — recipient: E.164 for SMS, Telegram @username, Discord <channelId|user:ID>, WhatsApp handle
- message (string) — text content
- media (string) — image/audio/document URL or local path
- caption (string) — media caption
- channel (string) — channel type: whatsapp, telegram, discord, sms
- threadId (string) — thread identifier for threaded contexts

Send actions: send (plain message), react (emoji reaction), poll (create/poll), search (search messages)

Management actions: read (fetch messages), edit, delete, pin, thread-create, thread-reply

Common send parameters: replyTo, quoteText, silent, asVoice, forceDocument

UI Presentation

canvas

Drive node Canvas for UI presentation, eval, and snapshots.

Parameters:
- action* (string) — present, hide, navigate, eval, snapshot, a2ui_push, a2ui_reset
- url (string) — URL for present or navigate
- node (string) — target canvas node
- outputFormat (string) — png or jpg for snapshot

Device Control

nodes

Discover and target paired devices (mobile, desktop nodes connected to the gateway).

Parameters: Device identification via node name/id or via target routing. Used for cross-device command dispatch.

Scheduling and Gateway Control

cron

Manage scheduled jobs via the OpenClaw gateway scheduler.

Parameters:
- action* (string) — list, create, delete, enable, disable
- schedule (string) — cron expression or human-readable schedule
- command (string) — command or agent prompt to run
- name (string) — job name for identification

gateway

Inspect, patch, restart, or update the Gateway at runtime. Owner-only tool.

Parameters:
- action* (string) — one of: config.schema.lookup, config.get, config.patch, config.apply, update.run
- path (string) — config path for config.schema.lookup

Note: config.patch is preferred for partial updates; config.apply only for full replacement. Refuses to change tools.exec.ask or tools.exec.security.

Media Generation and Analysis

image

Analyze one or more images with the configured image model. Provides a prompt describing what to look for.

Parameters:
- image (string) — single image path or URL
- images (array) — multiple image paths or URLs (up to 20)
- prompt* (string) — description of what to analyze
- model (string) — model override

image_generate

Generate new images or edit reference images.

Parameters:
- prompt* (string) — generation prompt
- action (string) — generate (default) or list to inspect providers
- model (string) — provider/model override (e.g., openai/gpt-image-2)
- image (string) — reference image for edit mode
- images (array) — reference images for edit (up to 5)
- aspectRatio (string) — 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
- size (string) — exact size like 1024x1024
- background (string) — transparent, opaque, auto
- outputFormat (string) — png, jpeg, webp
- quality (string) — low, medium, high, auto
- resolution (string) — 1K, 2K, 4K

music_generate

Generate music tracks.

Parameters:
- prompt* (string) — music generation prompt
- action (string) — generate (default) or list
- model (string) — provider/model override
- durationSeconds (number) — target duration
- instrumental (boolean) — instrumental only
- lyrics (string) — lyrics to guide sung output
- image (string) — optional reference image

video_generate

Generate videos.

Parameters:
- prompt* (string) — video generation prompt
- action (string) — generate (default) or list
- model (string) — provider/model override
- durationSeconds (number) — target duration
- aspectRatio (string) — aspect ratio hint
- resolution (string) — 480P, 720P, 768P, 1080P
- image (string) — first frame reference
- images (array) — reference images
- audioRef (string) — background audio reference

tts

One-shot text-to-speech conversion.

Parameters:
- text* (string) — text to convert
- channel (string) — channel ID to pick output format
- timeoutMs (number) — provider request timeout

Session and Sub-agent Management

sessions_list

List stored conversation sessions.

Parameters:
- limit (number) — max sessions to return

sessions_history

Return a bounded, safety-filtered recall view of session history. Strips thinking tags, tool-call XML, malformed tokens, and applies redaction/truncation. Not a raw transcript dump.

Parameters:
- sessionId* (string) — target session
- limit (number) — max messages
- before (string) — message ID to page before

sessions_send

Send a message to an existing session.

Parameters:
- sessionId (string) — target session
- message (string) — message text
- replies (array) — reply options for structured responses

sessions_spawn

Spawn a sub-agent to handle a task in an isolated background session.

Parameters:
- prompt* (string) — task description for the sub-agent
- runtime (string) — runtime: acp (ACP harness) or omit for default
- context (string) — fork (share transcript context) or isolated
- background (boolean) — run in background (default: true)
- model (string) — model override
- thinking (string) — on or off

Important: Completion notification must use message send to the requesting channel, not system events.

sessions_yield

End your current turn and wait for sub-agent results. Used after spawning sub-agents to receive their results as the next message.

Parameters:
- message (string) — optional message to send while yielding

subagents

Manage sub-agent lifecycle: spawn, steer, kill, list.

Parameters:
- action* (string) — sub-agent action
- sessionId (string) — target sub-agent session

session_status

Lightweight /status-style readback for the current session. Can set a per-session model override with model=default to clear.

Parameters:
- model (string) — per-session model override label

Memory

memory_get

Safe exact excerpt read from MEMORY.md or memory/*.md. Defaults to bounded excerpt when lines omitted; shows truncation info when more exists. corpus=wiki reads from registered compiled-wiki supplements.

Parameters:
- path* (string) — memory file path
- from (number) — starting line
- lines (number) — line count to read
- corpus (string) — memory (default), wiki, or all

Mandatory recall step before answering questions about prior work, decisions, dates, people, or preferences. Searches MEMORY.md, memory/*.md, and optionally session transcripts.

Parameters:
- query* (string) — semantic search query
- corpus (string) — memory (memory files only), sessions (transcripts), wiki (compiled wiki), all (default)
- maxResults (number) — max results to return
- minScore (number) — minimum relevance score threshold

Tool Configuration Reference

Tool Groups

Use group:* shorthands in tools.allow / tools.deny lists:

Group Tools
group:runtime exec, process, code_execution (bash alias)
group:fs read, write, edit, apply_patch
group:sessions sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory memory_search, memory_get
group:web web_search, x_search, web_fetch
group:ui browser, canvas
group:automation cron, gateway
group:messaging message
group:nodes nodes
group:agents agents_list
group:media image, image_generate, music_generate, video_generate, tts
group:openclaw All built-in tools (excludes plugin tools)

Tool Profiles

Profile What's included
full Unrestricted baseline (same as unset)
coding group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, music_generate, video_generate
messaging group:messaging, sessions_list, sessions_history, sessions_send, session_status
minimal session_status only

sessions_history applies aggressive safety filtering: it strips thinking tags, tool-call XML payloads, malformed tokens, and applies redaction/truncation rather than serving as a raw transcript dump.

Key Items

  • exec + process — Shell command runner and background session manager; exec handles primary runs with timeout/PTY/security; process manages background sessions; together they cover all CLI automation needs. Remember exec has a restricted PATH — use full paths or inject PATH via env.
  • sessions_spawn + sessions_yield — Sub-agent orchestration pair; spawn tasks with optional transcript context sharing, then yield to receive results when they complete. Always notify via message send to the target channel, not system events.
  • memory_search — Mandatory recall step before answering questions about prior work; searches memory files and session transcripts; configure corpus to limit scope (memory only, sessions only, wiki supplements, or all).
  • browser — Web browser automation with snapshot/screenshot/act pattern; profile selection (openclaw vs user) determines cookie/auth scope; use snapshot with refs="aria" for stable UI references across calls.
  • web_search + web_fetch — Web research pair; web_search queries Brave API; web_fetch extracts page content; combined for research pipelines. For stale content, use browser tool instead.
  • message — Multi-channel messaging hub; supports WhatsApp, SMS, Discord, Telegram; media sends with captions; thread management for group conversations.