Skip to main content

Tools (WednesdayAI)

WednesdayAI exposes first-class agent tools for browser, canvas, nodes, and cron. These replace the old openclaw-* skills: the tools are typed, no shelling, and the agent should rely on them directly.

Disabling tools

You can globally allow/deny tools via tools.allow / tools.deny in openclaw.json (deny wins). This prevents disallowed tools from being sent to model providers.
Notes:
  • Matching is case-insensitive.
  • * wildcards are supported ("*" means all tools).
  • Use tools.alsoAllow to add tools or action tokens without replacing an existing allowlist. For non-sandbox agents, gateway.config_apply is denied by default; tools.allow or alsoAllow: ["gateway.config_apply"] re-enables it. Bare * does not.
  • If tools.allow only 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_status only
  • coding: group:fs, group:runtime, group:sessions, group:memory, image
  • messaging: group:messaging, sessions_list, sessions_history, sessions_send, agents_nudge, session_status
  • full: no restriction (same as unset)
Example (messaging-only by default, allow Slack + Discord tools too):
Example (coding profile, but deny exec/process everywhere):
Example (global coding profile, messaging-only support agent):

Provider-specific tool policy

Use tools.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):
Example (provider/model-specific allowlist for a flaky endpoint):
Example (agent-specific override for a single provider):

Tool groups (shorthands)

Tool policies (global, agent, sandbox) support group:* entries that expand to multiple tools. Use these in tools.allow / tools.deny. Available groups:
  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, delete, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, agents_nudge, 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:device: every device tool of the run’s linked nodes
  • group:openclaw: all built-in WednesdayAI tools (excludes provider plugins)
Example (allow only file tools + browser):

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_path is accepted as an alias).
Notes:
  • 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 (unlike apply_patch).
  • Included in the sandbox default allow list; absent when the sandbox workspace is read-only (workspaceAccess: "ro").
  • Part of group:fs and the coding profile.

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 for host=node)
  • Need a real TTY? Set pty: true.
Notes:
  • Returns status: "running" with a sessionId when backgrounded.
  • Use process to poll/log/write/kill/clear background sessions.
  • If process is disallowed, 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 it’s a no-op).
  • host=node can 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
Notes:
  • poll returns new output and exit status when complete.
  • log supports line-based offset/limit (omit offset to grab the last N lines).
  • process is 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: alternating A/B/A/B no-progress patterns.
  • Per-agent override: agents.list[].tools.loopDetection.
Search the web using Brave Search API. Core parameters:
  • query (required)
  • count (1–10; default from tools.web.search.maxResults)
Notes:
  • Requires a Brave API key (recommended: wednesdayai configure --section web, or set BRAVE_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)
Notes:
  • Enable via tools.web.fetch.enabled.
  • maxChars is clamped by tools.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, close
  • snapshot (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
Profile management:
  • profiles — list all browser profiles with status
  • create-profile — create new profile with auto-allocated port (or cdpUrl)
  • delete-profile — stop browser, delete user data, remove from config (local only)
  • reset-profile — kill orphan process on profile’s port (local only)
Common parameters:
  • profile (optional; defaults to browser.defaultProfile)
  • target (sandbox | host | node)
  • node (optional; picks a specific node id/name) Notes:
  • Requires browser.enabled=true (default is true; set false to disable).
  • All actions accept optional profile parameter for multi-instance support.
  • When profile is omitted, uses browser.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).
  • snapshot defaults to ai when Playwright is installed; use aria for the accessibility tree.
  • snapshot also supports role-snapshot options (interactive, compact, depth, selector) which return refs like e12.
  • act requires ref from snapshot (numeric 12 from AI snapshots, or e12 from role snapshots); use evaluate for rare CSS selector needs.
  • Avoid act → wait by default; use it only in exceptional cases (no reliable UI state to wait on).
  • upload can optionally pass a ref to auto-click after arming.
  • upload also supports inputRef (aria ref) or element (CSS selector) to set <input type="file"> directly.

canvas

Drive the node Canvas (present, eval, snapshot, A2UI). Core actions:
  • present, hide, navigate, eval
  • snapshot (returns image block + MEDIA:<path>)
  • a2ui_push, a2ui_reset
Notes:
  • Uses gateway node.invoke under the hood.
  • If no node is 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, describe
  • pending, approve, reject (pairing)
  • notify (macOS system.notify)
  • run (macOS system.run)
  • camera_list, camera_snap, camera_clip, screen_record
  • location_get, notifications_list, notifications_action
  • device_status, device_info, device_permissions, device_health
Notes:
  • 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).
  • run params: command argv array; optional cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.
Example (run):

Device tools

Tool names have the form node_<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).
Device tools then pass the normal tool policy (profile, allow/deny, per-agent, sandbox) and 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 to maxImages, default 20)
  • prompt (optional; defaults to “Describe the image.”)
  • model (optional override)
  • maxBytesMb (optional size cap)
Notes:
  • Only available when agents.defaults.imageModel is 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 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 via the Gateway; other channels go direct.
  • poll uses 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, list
  • add, update, remove, run, runs
  • wake (enqueue system event + optional immediate heartbeat)
Notes:
  • add expects a full cron job object (same schema as cron.add RPC), with one exception: identity is excluded from the tool schema — identity attribution is operator-only (CLI, gateway RPC, Web UI).
  • update uses { jobId, patch } (id accepted for compatibility); the patch cannot set identity either.

gateway

Restart or apply updates to the running Gateway process (in-place). Core actions:
  • restart (authorizes + sends SIGUSR1 for in-process restart; wednesdayai gateway restart in-place)
  • config.get / config.schema
  • config.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)
Notes:
  • Use delayMs (defaults to 2000) to avoid interrupting an in-flight reply.
  • restart is enabled by default; set commands.restart: false to disable it.
  • config.apply and config.patch require baseHash from a prior config.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_apply is denied by default; re-enable with tools.allow or tools.alsoAllow: ["gateway.config_apply"]. Bare * does not re-enable it.
  • Even when apply is allowed, dropping a top-level key without request-level allowTopLevelKeyRemoval is 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 (or sessionId), limit?, includeTools?
  • sessions_send: sessionKey (or sessionId), 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; accepts sessionId), model? (default clears override)
Notes:
  • main is the canonical direct-chat key; global/unknown are hidden.
  • messageLimit > 0 fetches last N messages per session (tool messages filtered).
  • Session targeting is controlled by tools.sessions.visibility (default tree: current session + spawned subagent sessions). If you run a shared agent for multiple users, consider setting tools.sessions.visibility: "self" to prevent cross-session browsing.
  • sessions_send waits for final completion when timeoutSeconds > 0.
  • Delivery/announce happens after completion and is best-effort; status: "ok" confirms the agent run finished, not that the announce was delivered.
  • sessions_spawn supports runtime: "subagent" | "acp" (subagent default). For ACP runtime behavior, see ACP Agents.
  • sessions_spawn starts 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" with thread: true).
    • If thread: true and mode is omitted, mode defaults to session.
    • mode: "session" requires thread: true.
    • If runTimeoutSeconds is omitted, WednesdayAI uses agents.defaults.subagents.runTimeoutSeconds when set; otherwise timeout defaults to 0 (no timeout).
    • Discord thread-bound flows depend on session.threadBindings.* and channels.discord.threadBindings.*.
    • Reply format includes Status, Result, and compact stats.
    • Result is the assistant completion text; if missing, the latest toolResult is used as fallback.
    • completionDelivery ("parent" | "direct", for the subagent runtime and for runtime: "acp" with mode: "run") selects how a top-level completion is delivered; defaults to the configured mode. See Completion delivery.
  • 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 direct sends the completion straight to the requester channel and returns its result directly (no queue fallback); it is suppressed while sibling runs are pending.
  • sessions_spawn supports inline file attachments for subagent runtime only (ACP rejects them). Each attachment has name, content, and optional encoding (utf8 or base64) and mimeType. Files are materialized into the child workspace at .openclaw/attachments/<uuid>/ with a .manifest.json metadata file. The tool returns a receipt with count, totalBytes, per file sha256, and relDir. Attachment content is automatically redacted from transcript persistence.
    • Configure limits via tools.sessions_spawn.attachments (enabled, maxTotalBytes, maxFiles, maxFileBytes, retainOnSessionKeep).
    • attachAs.mountPath is a reserved hint for future mount implementations.
  • sessions_spawn is non-blocking and returns status: "accepted" immediately.
  • sessions_send runs a reply‑back ping‑pong (reply REPLY_SKIP to stop; max turns via session.agentToAgent.maxPingPongTurns, 0–5).
  • After the ping‑pong, the target agent runs an announce step; reply ANNOUNCE_SKIP to suppress the announcement.
  • Sandbox clamp: when the current session is sandboxed and agents.defaults.sandbox.sessionToolsVisibility: "spawned", WednesdayAI clamps tools.sessions.visibility to tree.

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 description when one is configured.
  • When ["*"] is configured, the tool includes all configured agents and marks allowAny: 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
Results:
  • { status: "accepted", agentId, workId, delivery }: nudge accepted and enqueued as an agent.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
Notes:
  • Gating: cross-agent nudges require both tools.sessions.visibility: "all" and tools.agentToAgent (enabled: true and the target agent allowed in allow).
  • Sandbox clamp: when the current session is sandboxed and agents.defaults.sandbox.sessionToolsVisibility: "spawned", WednesdayAI clamps session tools visibility to tree, 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 (default ws://127.0.0.1:18789)
  • gatewayToken (if auth enabled)
  • timeoutMs
Note: when 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 to browser.defaultProfile)
  • target (sandbox | host | node)
  • node (optional; pin a specific node id/name)
Browser automation:
  1. browser → status / start
  2. snapshot (ai or aria)
  3. act (click/type/press)
  4. screenshot if you need visual confirmation
Canvas render:
  1. canvas → present
  2. a2ui_push (optional)
  3. snapshot
Node targeting:
  1. nodes → status
  2. describe on the chosen node
  3. notify / run / camera_snap / screen_record

Safety

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

How tools are presented to the agent

Tools are exposed in two parallel channels:
  1. System prompt text: a human-readable list + guidance.
  2. Tool schema: the structured function definitions sent to the model API.
That means the agent sees both “what tools exist” and “how to call them.” If a tool doesn’t appear in the system prompt or the schema, the model cannot call it.