Skip to main content

Plugin analysis runtime operations

Plugins can run focused LLM analysis (api.runtime.analysis) alongside normal agent turns. This page covers what operators need: which model and credentials those runs use, the resource limits that bound them, and how to observe them.

Model and credential selection

  • An analysis run uses the caller-supplied provider + model pair when the plugin sets one; otherwise it falls back to the agent’s configured default model (agents.defaults.model.primary or the per-agent override). A provider without a model is rejected outright.
  • Credentials resolve through the same auth-profile plumbing as agent turns. Plugins may pin a profile with authProfileId; otherwise the default profile order applies. aws-sdk auth (Amazon Bedrock) and GitHub Copilot token exchange are both supported.
  • Tool-less runs (the common case) execute as a single direct provider completion carrying only the plugin’s prompt and input — they do not load the agent system prompt, so their token cost is bounded by what the plugin sends.

Resource limits

Tune the global analysis budget in openclaw.json:
Operator plugins.analysisConcurrency global fields win when set. Otherwise WednesdayAI takes the most permissive maxParallel / maxSequential among winning enabled plugin manifests. Inner maxParallelPerPlugin / maxSequentialPerPlugin attach to that plugin id. Operator per-plugin fields are a uniform ceiling when set. Omitting maxSequentialPerPlugin inherits maxSequential. Config is snapshotted when plugins load. Restart the gateway after changing it (Linux: systemctl --user restart openclaw-gateway; macOS: wednesdayai gateway restart --deep). The timeout bounds the whole run: model resolution, credential resolution (including OAuth refresh and Copilot token exchange), and the provider call. Analysis runs execute in the shared analysis command lane, so they do not compete with the active user turn.

Plugin hook timeouts

Every plugin hook defaults to 30 seconds. A hung handler is killed and logged instead of blocking the gateway. Override per hook name (or set default) with:
Cascade: api.on(..., { timeoutMs }) then plugins.hookTimeouts then plugin manifest hookTimeouts then 30 s. Restart required. See Configuration reference.

Observability

  • Every analysis run emits run.started and run.completed diagnostic events. Direct-path runs carry metadata.analysisTransport: "direct" so dashboards can split them from embedded agent runs. run.completed reports durationMs and exitStatus (ok | error).
  • Logs use the plugins/runtime/analysis subsystem. Successful and empty runs log at info; failures and timeouts log at warn with the error text, provider, model, purpose, and plugin id. Concurrency rejects log analysis run rejected at info with error: "analysis concurrency limit exceeded" and admissionBoundary (plugin-queue | global-queue | plugin-active | global-active). Zero overflow caps never emit the queue tokens.
  • Results report token usage (input, output, cacheRead, cacheWrite, total) when the provider returns it, so per-plugin analysis cost is attributable from diagnostics consumers (e.g. the OTel exporter).

Failure modes

  • rejected — invalid request (empty purpose/input, provider without model, disallowed tool) or the hierarchical budget is full. Invalid requests reject before any credential or provider work. Budget rejects use error: "analysis concurrency limit exceeded" and the admissionBoundary log field above.
  • timeout — the run exceeded its clamped timeoutMs; the provider call is aborted, not abandoned.
  • error — credential resolution failed, the provider returned an error, or JSON output failed to parse (model text is preserved in the result for the parse case).
Analysis transcripts are transient: they are not synced to session storage, and analysis runs skip sandbox startup, workspace cwd changes, and global hook dispatch.