Tools (WednesdayAI)
WednesdayAI exposes first-class agent tools for browser, canvas, nodes, and cron. These replace the oldopenclaw-* skills: the tools are typed, no shelling,
and the agent should rely on them directly.
Disabling tools
You can globally allow/deny tools viatools.allow / tools.deny in openclaw.json
(deny wins). This prevents disallowed tools from being sent to model providers.
- Matching is case-insensitive.
*wildcards are supported ("*"means all tools).- Use
tools.alsoAllowto add tools or action tokens without replacing an existing allowlist. For non-sandbox agents,gateway.config_applyis denied by default;tools.alloworalsoAllow: ["gateway.config_apply"]re-enables it. Bare*does not. - If
tools.allowonly references unknown or unloaded plugin tool names, WednesdayAI logs a warning and ignores the allowlist so core tools stay available.
Tool profiles (base allowlist)
tools.profile sets a base tool allowlist before tools.allow/tools.deny.
Per-agent override: agents.list[].tools.profile.
Profiles:
minimal:session_statusonlycoding:group:fs,group:runtime,group:sessions,group:memory,imagemessaging:group:messaging,sessions_list,sessions_history,sessions_send,agents_nudge,session_statusfull: no restriction (same as unset)
Provider-specific tool policy
Usetools.byProvider to further restrict tools for specific providers
(or a 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 either provider (e.g. google-antigravity) or
provider/model (e.g. openai/gpt-5.2).
Example (keep global coding profile, but minimal tools for Google Antigravity):
Tool groups (shorthands)
Tool policies (global, agent, sandbox) supportgroup:* entries that expand to multiple tools.
Use these in tools.allow / tools.deny.
Available groups:
group:runtime:exec,bash,processgroup:fs:read,write,edit,delete,apply_patchgroup:sessions:sessions_list,sessions_history,sessions_send,agents_nudge,sessions_spawn,session_statusgroup:memory:memory_search,memory_getgroup:web:web_search,web_fetchgroup:ui:browser,canvasgroup:automation:cron,gatewaygroup:messaging:messagegroup:nodes:nodesgroup:device: every device tool of the run’s linked nodesgroup:openclaw: all built-in WednesdayAI tools (excludes provider plugins)
Plugins + tools
Plugins can register additional tools (and CLI commands) beyond the core set. See Plugins for install + config, and Skills for how tool usage guidance is injected into prompts. Some plugins ship their own skills alongside tools (for example, the voice-call plugin). Optional plugin tools:- Lobster: typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host).
- LLM Task: JSON-only LLM step for structured workflow output (optional schema validation).
- Diffs: read-only diff viewer and PNG or PDF file renderer for before/after text or unified patches.
Tool inventory
apply_patch
Apply structured patches across one or more files. Use for multi-hunk edits.
Experimental: enable via tools.exec.applyPatch.enabled (OpenAI models only).
tools.exec.applyPatch.workspaceOnly defaults to true (workspace-contained). Set it to false only if you intentionally want apply_patch to write/delete outside the workspace directory.
apply_patch is OpenAI-only. Non-OpenAI providers can remove files with the delete tool instead.
delete
Delete one file inside the agent workspace.
Core parameters:
path(required): file to delete, relative to the workspace root (file_pathis accepted as an alias).
- Files only: directories, the workspace root, and missing paths are refused.
- Always workspace-contained: refuses paths outside the agent workspace (or the active workspace lane), even with
tools.fs.workspaceOnly: false. - For symlinks, the link is removed, not its target. In a sandbox, a symlink whose in-container resolution leaves the workspace (for example into another writable bind) is refused instead of removed.
- Available for every provider and independent of
exec(unlikeapply_patch). - Included in the sandbox default allow list; absent when the sandbox workspace is read-only (
workspaceAccess: "ro"). - Part of
group:fsand thecodingprofile.
exec
Run shell commands in the workspace.
Core parameters:
command(required)yieldMs(auto-background after timeout, default 10000)background(immediate background)timeout(seconds; kills the process if exceeded, default 1800)elevated(bool; run on host if elevated mode is enabled/allowed; only changes behavior when the agent is sandboxed)host(sandbox | gateway | node)security(deny | allowlist | full)ask(off | on-miss | always)node(node id/name forhost=node)- Need a real TTY? Set
pty: true.
- Returns
status: "running"with asessionIdwhen backgrounded. - Use
processto poll/log/write/kill/clear background sessions. - If
processis disallowed,execruns synchronously and ignoresyieldMs/background. elevatedis gated bytools.elevatedplus anyagents.list[].tools.elevatedoverride (both must allow) and is an alias forhost=gateway+security=full.elevatedonly changes behavior when the agent is sandboxed (otherwise it’s a no-op).host=nodecan target a macOS companion app or a headless node host (wednesdayai node run).- gateway/node approvals and allowlists: Exec approvals.
process
Manage background exec sessions.
Core actions:
list,poll,log,write,kill,clear,remove
pollreturns new output and exit status when complete.logsupports line-basedoffset/limit(omitoffsetto grab the last N lines).processis scoped per agent; sessions from other agents are not visible.
loop-detection (tool-call loop guardrails)
WednesdayAI tracks recent tool-call history and blocks or warns when it detects repetitive no-progress loops.
Enable with tools.loopDetection.enabled: true (default is false).
genericRepeat: repeated same tool + same params call pattern.knownPollNoProgress: repeating poll-like tools with identical outputs.pingPong: alternatingA/B/A/Bno-progress patterns.- Per-agent override:
agents.list[].tools.loopDetection.
web_search
Search the web using Brave Search API.
Core parameters:
query(required)count(1–10; default fromtools.web.search.maxResults)
- Requires a Brave API key (recommended:
wednesdayai configure --section web, or setBRAVE_API_KEY). - Enable via
tools.web.search.enabled. - Responses are cached (default 15 min).
- 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)
- Enable via
tools.web.fetch.enabled. maxCharsis clamped bytools.web.fetch.maxCharsCap(default 50000).- Responses are cached (default 15 min).
- For JS-heavy sites, prefer the browser tool.
- See Web tools for setup.
- See Firecrawl for the optional anti-bot fallback.
browser
Control the dedicated WednesdayAI-managed browser.
Core actions:
status,start,stop,tabs,open,focus,closesnapshot(aria/ai)screenshot(returns image block +MEDIA:<path>)act(UI actions: click/type/press/hover/drag/select/fill/resize/wait/evaluate)navigate,console,pdf,upload,dialog
profiles— list all browser profiles with statuscreate-profile— create new profile with auto-allocated port (orcdpUrl)delete-profile— stop browser, delete user data, remove from config (local only)reset-profile— kill orphan process on profile’s port (local only)
profile(optional; defaults tobrowser.defaultProfile)target(sandbox|host|node)node(optional; picks a specific node id/name) Notes:- Requires
browser.enabled=true(default istrue; setfalseto disable). - All actions accept optional
profileparameter for multi-instance support. - When
profileis omitted, usesbrowser.defaultProfile(defaults to “chrome”). - Profile names: lowercase alphanumeric + hyphens only (max 64 chars).
- Port range: 18800-18899 (~100 profiles max).
- Remote profiles are attach-only (no start/stop/reset).
- If a browser-capable node is connected, the tool may auto-route to it (unless you pin
target). snapshotdefaults toaiwhen Playwright is installed; useariafor the accessibility tree.snapshotalso supports role-snapshot options (interactive,compact,depth,selector) which return refs likee12.actrequiresreffromsnapshot(numeric12from AI snapshots, ore12from role snapshots); useevaluatefor rare CSS selector needs.- Avoid
act→waitby default; use it only in exceptional cases (no reliable UI state to wait on). uploadcan optionally pass arefto auto-click after arming.uploadalso supportsinputRef(aria ref) orelement(CSS selector) to set<input type="file">directly.
canvas
Drive the node Canvas (present, eval, snapshot, A2UI).
Core actions:
present,hide,navigate,evalsnapshot(returns image block +MEDIA:<path>)a2ui_push,a2ui_reset
- Uses gateway
node.invokeunder the hood. - If no
nodeis provided, the tool picks a default (single connected node or local mac node). - A2UI is v0.8 only (no
createSurface); the CLI rejects v0.9 JSONL with line errors. - Quick smoke:
wednesdayai nodes canvas a2ui push --node <id> --text "Hello from A2UI".
nodes
Discover and target paired nodes; send notifications; capture camera/screen.
Core actions:
status,describepending,approve,reject(pairing)notify(macOSsystem.notify)run(macOSsystem.run)camera_list,camera_snap,camera_clip,screen_recordlocation_get,notifications_list,notifications_actiondevice_status,device_info,device_permissions,device_health
- Camera/screen commands require the node app to be foregrounded.
- Images return image blocks +
MEDIA:<path>. - Videos return
FILE:<path>(mp4). - Location returns a JSON payload (lat/lon/accuracy/timestamp).
runparams:commandargv array; optionalcwd,env(KEY=VAL),commandTimeoutMs,invokeTimeoutMs,needsScreenRecording.
run):
Device tools
Tool names have the formnode_<id>_<command>.
A connected node that describes its commands with typed commandSpecs (see
Command descriptors) gets one agent tool per
described command, for example node_878e64e8_device_status. <id> is the first 8 letters and
digits of the node id, lowercased; <command> is the command name lowercased, with each run of
characters other than letters, digits, _, and - replaced by _. Names over 64 characters, or
a second tool with the same name, are skipped with a warning. The tool’s parameters are the node’s
inputSchema; its description is the descriptor’s description plus (device: <node name>).
A run sees a node’s device tools only when:
- the node’s device is linked to the run’s person in
session.identityLinks(device:<nodeId>); - the command passes the node command allowlist (
gateway.nodes.allowCommands/gateway.nodes.denyCommands); - for a descriptor with
proactive: false, the turn is user-initiated (not cron, heartbeat, or other background turns).
before_tool_call hooks. group:device names all of them: tools.deny: ["group:device"] removes
them, and a restrictive profile such as coding drops them unless tools.alsoAllow includes
group:device; group:plugins does not include them. Calls go through the gateway node.invoke, which validates the arguments against
the descriptor and applies per-node limits (see
Command descriptors) before the node sees the call.
The nodes tool stays available for commands without a descriptor.
image
Analyze an image with the configured image model.
Core parameters:
image(path or URL; also accepts a JSON-encoded array of paths, for example'["/tmp/a.png","/tmp/b.png"]'— invalid JSON or a non-string entry is treated as a literal path)images(array of paths or URLs, up tomaxImages, default 20)prompt(optional; defaults to “Describe the image.”)model(optional override)maxBytesMb(optional size cap)
- Only available when
agents.defaults.imageModelis configured (primary or fallbacks), or when an implicit image model can be inferred from your default model + configured auth (best-effort pairing). - Uses the image model directly (independent of the main chat model).
pdf
Analyze one or more PDF documents.
For full behavior, limits, config, and examples, see PDF tool.
message
Send messages and channel actions across Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams.
Core actions:
send(text + optional media; MS Teams also supportscardfor Adaptive Cards)poll(WhatsApp/Discord/MS Teams polls)react/reactions/read/edit/deletepin/unpin/list-pinspermissionsthread-create/thread-list/thread-replysearchstickermember-info/role-infoemoji-list/emoji-upload/sticker-uploadrole-add/role-removechannel-info/channel-listvoice-statusevent-list/event-createtimeout/kick/ban
sendroutes WhatsApp via the Gateway; other channels go direct.polluses the Gateway for WhatsApp and MS Teams; Discord polls go direct.- When a message tool call is bound to an active chat session, sends are constrained to that session’s target to avoid cross-context leaks.
cron
Manage Gateway cron jobs and wakeups.
Core actions:
status,listadd,update,remove,run,runswake(enqueue system event + optional immediate heartbeat)
addexpects a full cron job object (same schema ascron.addRPC), with one exception:identityis excluded from the tool schema — identity attribution is operator-only (CLI, gateway RPC, Web UI).updateuses{ jobId, patch }(idaccepted for compatibility); the patch cannot setidentityeither.
gateway
Restart or apply updates to the running Gateway process (in-place).
Core actions:
restart(authorizes + sendsSIGUSR1for in-process restart;wednesdayai gatewayrestart in-place)config.get/config.schemaconfig.apply(validate + write config + restart + wake; default-denied for non-sandbox agents)config.patch(merge partial update + restart + wake)update.run(run update + restart + wake)
- Use
delayMs(defaults to 2000) to avoid interrupting an in-flight reply. restartis enabled by default; setcommands.restart: falseto disable it.config.applyandconfig.patchrequirebaseHashfrom a priorconfig.get. The tool does not auto-fill it.- Policy can allow or deny individual actions (
gateway.config_apply,gateway.config_patch,gateway.config_get,gateway.restart,gateway.update_run). For non-sandbox agents,gateway.config_applyis denied by default; re-enable withtools.allowortools.alsoAllow: ["gateway.config_apply"]. Bare*does not re-enable it. - Even when apply is allowed, dropping a top-level key without request-level
allowTopLevelKeyRemovalis refused. The agent tool does not send that field. See Config writes.
sessions_list / sessions_history / sessions_send / sessions_spawn / session_status
List sessions, inspect transcript history, or send to another session.
Core parameters:
sessions_list:kinds?,limit?,activeMinutes?,messageLimit?(0 = none)sessions_history:sessionKey(orsessionId),limit?,includeTools?sessions_send:sessionKey(orsessionId),message,timeoutSeconds?(0 = fire-and-forget)sessions_spawn:task,label?,runtime?,agentId?,model?,thinking?,cwd?,runTimeoutSeconds?,thread?,mode?,cleanup?,sandbox?,attachments?,attachAs?,completionDelivery?session_status:sessionKey?(default current; acceptssessionId),model?(defaultclears override)
mainis the canonical direct-chat key; global/unknown are hidden.messageLimit > 0fetches last N messages per session (tool messages filtered).- Session targeting is controlled by
tools.sessions.visibility(defaulttree: current session + spawned subagent sessions). If you run a shared agent for multiple users, consider settingtools.sessions.visibility: "self"to prevent cross-session browsing. sessions_sendwaits for final completion whentimeoutSeconds > 0.- Delivery/announce happens after completion and is best-effort;
status: "ok"confirms the agent run finished, not that the announce was delivered. sessions_spawnsupportsruntime: "subagent" | "acp"(subagentdefault). For ACP runtime behavior, see ACP Agents.sessions_spawnstarts a sub-agent run and delivers the completion back to the requester chat.- Supports one-shot mode (
mode: "run") and persistent thread-bound mode (mode: "session"withthread: true). - If
thread: trueandmodeis omitted, mode defaults tosession. mode: "session"requiresthread: true.- If
runTimeoutSecondsis omitted, WednesdayAI usesagents.defaults.subagents.runTimeoutSecondswhen set; otherwise timeout defaults to0(no timeout). - Discord thread-bound flows depend on
session.threadBindings.*andchannels.discord.threadBindings.*. - Reply format includes
Status,Result, and compact stats. Resultis the assistant completion text; if missing, the latesttoolResultis used as fallback.completionDelivery("parent" | "direct", for the subagent runtime and forruntime: "acp"withmode: "run") selects how a top-level completion is delivered; defaults to the configured mode. See Completion delivery.
- Supports one-shot mode (
- Top-level completions default to parent-first delivery: the result is passed to the parent on a durable agent turn (survives gateway restarts; sibling completions fan in to exactly one parent turn) and the parent authors the user-facing reply. Explicit
directsends the completion straight to the requester channel and returns its result directly (no queue fallback); it is suppressed while sibling runs are pending. sessions_spawnsupports inline file attachments for subagent runtime only (ACP rejects them). Each attachment hasname,content, and optionalencoding(utf8orbase64) andmimeType. Files are materialized into the child workspace at.openclaw/attachments/<uuid>/with a.manifest.jsonmetadata file. The tool returns a receipt withcount,totalBytes, per filesha256, andrelDir. Attachment content is automatically redacted from transcript persistence.- Configure limits via
tools.sessions_spawn.attachments(enabled,maxTotalBytes,maxFiles,maxFileBytes,retainOnSessionKeep). attachAs.mountPathis a reserved hint for future mount implementations.
- Configure limits via
sessions_spawnis non-blocking and returnsstatus: "accepted"immediately.sessions_sendruns a reply‑back ping‑pong (replyREPLY_SKIPto stop; max turns viasession.agentToAgent.maxPingPongTurns, 0–5).- After the ping‑pong, the target agent runs an announce step; reply
ANNOUNCE_SKIPto suppress the announcement. - Sandbox clamp: when the current session is sandboxed and
agents.defaults.sandbox.sessionToolsVisibility: "spawned", WednesdayAI clampstools.sessions.visibilitytotree.
agents_list
List agent ids that the current session may target with sessions_spawn.
Notes:
- Result is restricted to per-agent allowlists (
agents.list[].subagents.allowAgents) plus the members of any team the session’s agent leads (agents.teams). - Each entry carries the agent’s
descriptionwhen one is configured. - When
["*"]is configured, the tool includes all configured agents and marksallowAny: true.
agents_nudge
Wake another agent to run one durable turn with your message in its main session. Fire-and-forget; used for agent-to-agent handoffs.
Core parameters:
agentId: target agent ID (string, required)message: instruction or context to run in the target agent’s main session (string, required, at most 8,000 characters; delivered to the target as untrusted context)dedupeKey?: optional idempotency key. When omitted it defaults to the caller’s session key plus the tool-call id, so a re-executed tool call cannot double-wake the target. Providers that omit tool-call ids get a synthesized one that repeats across runs; those are ignored and each call admits its own turn
{ status: "accepted", agentId, workId, delivery }: nudge accepted and enqueued as anagent.turn{ status: "error", error }: nudge rejected or enqueuing failed (e.g. queue full, depth exceeded, invalid agent){ status: "forbidden", error }: caller lacks permission to nudge the target agent
- Gating: cross-agent nudges require both
tools.sessions.visibility: "all"andtools.agentToAgent(enabled: trueand the target agent allowed inallow). - Sandbox clamp: when the current session is sandboxed and
agents.defaults.sandbox.sessionToolsVisibility: "spawned", WednesdayAI clamps session tools visibility totree, refusing cross-agent nudges. - For full grant configuration, deduplication semantics, and hop limits, see Agent coordination.
Parameters (common)
Gateway-backed tools (canvas, nodes, cron):
gatewayUrl(defaultws://127.0.0.1:18789)gatewayToken(if auth enabled)timeoutMs
gatewayUrl is set, include gatewayToken explicitly. Tools do not inherit config
or environment credentials for overrides, and missing explicit credentials is an error.
Browser tool:
profile(optional; defaults tobrowser.defaultProfile)target(sandbox|host|node)node(optional; pin a specific node id/name)
Recommended agent flows
Browser automation:browser→status/startsnapshot(ai or aria)act(click/type/press)screenshotif you need visual confirmation
canvas→presenta2ui_push(optional)snapshot
nodes→statusdescribeon the chosen nodenotify/run/camera_snap/screen_record
Safety
- Avoid direct
system.run; usenodes→runonly with explicit user consent. - Respect user consent for camera/screen capture.
- Use
status/describeto ensure permissions before invoking media commands.
How tools are presented to the agent
Tools are exposed in two parallel channels:- System prompt text: a human-readable list + guidance.
- Tool schema: the structured function definitions sent to the model API.