Skip to main content

Plugin agent tools

WednesdayAI plugins can register agent tools (JSON‑schema functions) that are exposed to the LLM during agent runs. Tools can be required (always available) or optional (opt‑in). Agent tools are configured under tools in the main config, or per‑agent under agents.list[].tools. The allowlist/denylist policy controls which tools the agent can call.

Basic tool

Tool context identity

Plugin tool factories receive an OpenClawPluginToolContext. For tools that need owner checks, user attribution, or per-turn dedupe, prefer the typed nested identity fields over parsing tool arguments or session keys:
The same runtimeIdentity and turn objects are also available to before_tool_call, after_tool_call, and tool_result_persist hook contexts when the runtime has foreground run identity for the tool call. The normal agent tool wrapper path passes the same objects into before_tool_call, so plugins do not need a separate code path for hook-time authorization or dedupe. Existing flat fields such as agentId, sessionId, sessionKey, canonicalIdentity, and senderIsOwner remain available for compatibility. ctx.runtimeIdentity.identitySource ("sender" | "parent-session" | "job-config") reports how the resolved identity was attached — live message sender, inherited from the spawning session, or operator-configured cron/heartbeat attribution; it is absent when the run has no resolved identity, and also when a seam supplies canonicalIdentity without knowing its provenance (provenance is never guessed). identitySource implies canonicalIdentity, but a present canonicalIdentity does not guarantee identitySource.

Optional tool (opt‑in)

Optional tools are never auto‑enabled. Users must add them to an agent allowlist.
Enable optional tools in agents.list[].tools.allow (or global tools.allow):
Other config knobs that affect tool availability:
  • Allowlists that only name plugin tools are treated as plugin opt-ins; core tools remain enabled unless you also include core tools or groups in the allowlist.
  • tools.profile / agents.list[].tools.profile (base allowlist)
  • tools.byProvider / agents.list[].tools.byProvider (provider‑specific allow/deny)
  • tools.sandbox.tools.* (sandbox tool policy when sandboxed)

Rules + tips

  • Tool names must not clash with core tool names; conflicting tools are skipped.
  • Plugin ids used in allowlists must not clash with core tool names.
  • Prefer optional: true for tools that trigger side effects or require extra binaries/credentials.

Testing the real tool pipeline

Extension test suites can drive the exact loader → factory → allowlist → adapter pipeline the gateway uses, instead of mocking it. Import the testing seam:
This subpath is supported for test code only — never import it from production extension code, and it is never loaded by the runtime jiti loader (enforced by src/plugins/extension-import-boundary.test.ts). This is a deliberate divergence from upstream openclaw, which keeps its testing barrel repo-local. The three-step flow:
  1. Discovery — loadOpenClawPlugins({ cache: false, workspaceDir, config }) with explicit plugins.enabled: true, plugins.allow, and plugins.load.paths pointing at fixture plugin files (.cjs entry plus an openclaw.plugin.json manifest). Explicit config survives the test-env plugin-off default. Returns the real PluginRegistry.
  2. Factory resolution + filtering — resolvePluginTools({ context }) invokes each registered tool factory and applies runToolAllowlist (and the optional-tool allow policy). Entries registered as bare factories (no up-front tool names) cannot be pre-filtered, so they are invoked and filtered by their resolved tool names under a non-empty runToolAllowlist; an empty runToolAllowlist invokes no factory at all. Declare names via registerTool(factory, { names }) so restricted runs can skip the factory call entirely — and keep any dynamic discovery inside the factory cached, never re-discovered per run. When an unnamed factory returns no tool allowed in this run, or a named factory returns a tool outside its declared names, a one-time warning is logged and surfaced as a PLUGIN_REGISTER_ERROR diagnostic.
  3. Adaptation — toToolDefinitions(tools) produces the agent-facing definitions: label falls back to name when unset, thrown errors are normalized into structured error results, and execute(toolCallId, params, signal, onUpdate) passes the AbortSignal as the third argument (pi-agent-core calling convention) — never a host-context object. The vendor prepareArguments and executionMode fields are forwarded as-is, so the agent loop normalizes arguments (alias renames, legacy-shape folds) before validating them against the tool schema; a contract test fails if a future AgentTool field stops being forwarded.
Global-state hygiene: loadOpenClawPlugins activates the global plugin registry. Reset it between tests with setActivePluginRegistry(createEmptyPluginRegistry()) in afterEach (both re-exported from the same subpath). PluginLoadOptions, PluginRegistry, PluginToolRegistration, and HookContext are exported as types for annotating fixtures. The loader test src/plugin-sdk/testing.seam.test.ts is the canonical worked example.