This plugin integrates OpenClaw with Agent Control, a security and policy layer for agent tool use. It registers OpenClaw tools with Agent Control and can block unsafe tool invocations before they execute.
- Enforce policy before tool execution, so unsafe or disallowed actions never run.
- Carry session and channel context into evaluations, so policies can reason about where a request came from and how the agent is being used.
- Example: Only allow specific tools in slack channels, but allow fully if DM from an approved user.
- Allow read tool, but only from an allowlist of paths.
- Example: Only allow specific tools in slack channels, but allow fully if DM from an approved user.
- Policies can be updated and propagated to your OpenClaw without having to reboot the gateway.
When the gateway starts, the plugin loads the OpenClaw tool catalog and syncs it to Agent Control. On every tool call, the plugin intercepts the invocation through a before_tool_call hook, builds an evaluation context (session, channel, provider, agent identity), and sends it to Agent Control for a policy decision. If the evaluation comes back safe the call proceeds normally. If it comes back denied the call is blocked and the user sees a rejection message.
The plugin handles multiple agents, caches the resolved tool catalog briefly to keep the pre-tool hook fast, and re-syncs automatically when the catalog drifts.
Install and configure with the minimum required settings:
openclaw plugins install agent-control-openclaw-plugin
openclaw config set plugins.entries.agent-control-openclaw-plugin.enabled true
openclaw config set plugins.entries.agent-control-openclaw-plugin.config.serverUrl "http://localhost:8000"Restart the gateway. The plugin is now active with fail-open defaults and warn-level logging.
For authenticated setups, also set:
openclaw config set plugins.entries.agent-control-openclaw-plugin.config.apiKey "ac_your_api_key"Here is an example policy which blocks all tools except read and memory for anyone who is not an admin. For read you can specify approved files and folders.
To use it, make sure your OpenClaw agent is already registered with Agent Control, then go to your agent in Agent Contorl UI, click "Add Control" -> "Create Contorl" -> "Write your own" and copy paste JSON.
| Setting | Type | Default | Description |
|---|---|---|---|
serverUrl | string | — | Base URL for the Agent Control server. Required. |
apiKey | string | — | API key for authenticating with Agent Control. |
agentName | string | openclaw-agent | Base name used when registering agents with Agent Control. |
agentVersion | string | — | Version string sent to Agent Control during agent sync. |
timeoutMs | integer | SDK default | Client timeout in milliseconds. |
failClosed | boolean | false | Block tool calls when Agent Control is unreachable. See Fail-open vs fail-closed. |
observabilityEnabled | boolean | true | Emit pre-tool control execution events to Agent Control observability. Enabled by default unless explicitly set to false. |
logLevel | string | warn | Logging verbosity. See Logging. |
userAgent | string | openclaw-agent-control-plugin/0.1 | Custom User-Agent header for requests to Agent Control. |
All settings are configured through the OpenClaw CLI:
openclaw config set plugins.entries.agent-control-openclaw-plugin.config.<key><value>serverUrl and apiKey can also be set through environment variables. This is useful in container or CI environments where you do not want secrets in the OpenClaw config file.
| Variable | Equivalent config |
|---|---|
AGENT_CONTROL_SERVER_URL | serverUrl |
AGENT_CONTROL_API_KEY | apiKey |
Config values take precedence over environment variables when both are set.
By default, the plugin is fail-open: if Agent Control is unreachable or the evaluation request fails, tool calls are allowed through. This avoids breaking your gateway when Agent Control has a transient outage.
Set failClosed to true if you need the guarantee that no tool call executes without a policy decision. In fail-closed mode, a sync failure or evaluation error will block the tool call.
openclaw config set plugins.entries.agent-control-openclaw-plugin.config.failClosed trueObservability is enabled by default. Unless observabilityEnabled is explicitly set to false, the plugin sends control execution events to Agent Control's observability API after each before_tool_call evaluation.
- Events are emitted only for the
prestage because the current OpenClaw plugin SDK typings expose a pre-tool hook but no post-tool hook. - Emission is best-effort and non-blocking. Ingest failures are logged at
warnand do not change allow/block behavior. - The plugin stamps OpenTelemetry trace and span IDs when an active span exists, otherwise it generates OTEL-compatible IDs locally.
Disable it with:
openclaw config set plugins.entries.agent-control-openclaw-plugin.config.observabilityEnabled falseThe plugin stays quiet by default and only emits warnings, errors, and tool block events.
| Level | What it logs |
|---|---|
warn | Warnings, errors, and block events. This is the default. |
info | Adds lifecycle events: client init, gateway warmup, agent syncs. |
debug | Adds verbose diagnostics: phase timings, context building, evaluation details. |
openclaw config set plugins.entries.agent-control-openclaw-plugin.config.logLevel "debug"openclaw plugins list
openclaw plugins info agent-control-openclaw-plugin
openclaw plugins doctoropenclaw plugins enable agent-control-openclaw-plugin
openclaw plugins disable agent-control-openclaw-pluginopenclaw config unset plugins.entries.agent-control-openclaw-plugin.config.apiKey
openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.logLevel
openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.agentVersion
openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.observabilityEnabled
openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.userAgentopenclaw plugins uninstall agent-control-openclaw-plugin --force- Clone this repo anywhere on disk.
- Install dependencies and run the verification stack:
npm install
npm run lint
npm run typecheck
npm test- Link the plugin into your OpenClaw checkout:
openclaw plugins install -l /absolute/path/to/openclaw-plugin- Restart the gateway.
npm run coverage generates a report under coverage/ including coverage/lcov.info for Codecov uploads.
See AGENTS.md for project conventions, testing patterns, and the verification checklist.