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 undertools 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 anOpenClawPluginToolContext. 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:
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.agents.list[].tools.allow (or global tools.allow):
- 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: truefor 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: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:
- Discovery —
loadOpenClawPlugins({ cache: false, workspaceDir, config })with explicitplugins.enabled: true,plugins.allow, andplugins.load.pathspointing at fixture plugin files (.cjsentry plus anopenclaw.plugin.jsonmanifest). Explicit config survives the test-env plugin-off default. Returns the realPluginRegistry. - Factory resolution + filtering —
resolvePluginTools({ context })invokes each registered tool factory and appliesrunToolAllowlist(and the optional-toolallowpolicy). 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-emptyrunToolAllowlist; an emptyrunToolAllowlistinvokes no factory at all. DeclarenamesviaregisterTool(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 aPLUGIN_REGISTER_ERRORdiagnostic. - Adaptation —
toToolDefinitions(tools)produces the agent-facing definitions:labelfalls back tonamewhen unset, thrown errors are normalized into structured error results, andexecute(toolCallId, params, signal, onUpdate)passes theAbortSignalas the third argument (pi-agent-core calling convention) — never a host-context object. The vendorprepareArgumentsandexecutionModefields 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 futureAgentToolfield stops being forwarded.
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.