{"id":47997907,"url":"https://github.com/agentcontrol/openclaw-plugin","last_synced_at":"2026-05-06T10:02:28.105Z","repository":{"id":345801997,"uuid":"1173137173","full_name":"agentcontrol/openclaw-plugin","owner":"agentcontrol","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-30T23:28:19.000Z","size":360,"stargazers_count":18,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T00:18:42.749Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentcontrol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-05T03:32:01.000Z","updated_at":"2026-03-30T23:28:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentcontrol/openclaw-plugin","commit_stats":null,"previous_names":["agentcontrol/openclaw-plugin"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/agentcontrol/openclaw-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fopenclaw-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fopenclaw-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fopenclaw-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fopenclaw-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentcontrol","download_url":"https://codeload.github.com/agentcontrol/openclaw-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentcontrol%2Fopenclaw-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31245830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T15:15:33.278Z","status":"ssl_error","status_checked_at":"2026-03-31T15:15:28.327Z","response_time":111,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T12:05:35.694Z","updated_at":"2026-05-02T06:06:53.377Z","avatar_url":"https://github.com/agentcontrol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenClaw plugin for Agent Control\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/cat-plus-lobster-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/cat-plus-lobster-light.svg\"\u003e\n    \u003cimg src=\"https://cdn.jsdelivr.net/npm/agent-control-openclaw-plugin/assets/cat-plus-lobster-light.svg\" alt=\"Agent Control cat plus OpenClaw lobster\" width=\"430\"\u003e\n  \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://www.npmjs.com/package/agent-control-openclaw-plugin\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/agent-control-openclaw-plugin?logo=npm\" alt=\"npm version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/agentcontrol/openclaw-plugin/blob/main/package.json\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js\u0026logoColor=white\" alt=\"Node 24 or newer\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/agentcontrol/openclaw-plugin/actions/workflows/lint.yml\"\u003e\n    \u003cimg src=\"https://github.com/agentcontrol/openclaw-plugin/actions/workflows/lint.yml/badge.svg\" alt=\"CI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://app.codecov.io/gh/agentcontrol/openclaw-plugin\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/agentcontrol/openclaw-plugin/graph/badge.svg?branch=main\" alt=\"Codecov\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThis plugin integrates OpenClaw with [Agent Control](https://github.com/agentcontrol/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.\n\n## Why use this?\n\n- Enforce policy before tool execution, so unsafe or disallowed actions never run.\n- Carry session and channel context into evaluations, so policies can reason about where a request came from and how the agent is being used.\n  - Example: Only allow specific tools in slack channels, but allow fully if DM from an approved user.\n    - Allow read tool, but only from an allowlist of paths. \n- Policies can be updated and propagated to your OpenClaw without having to reboot the gateway.\n\n## How it works\n\nWhen 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.\n\nThe plugin handles multiple agents, tracks tool catalog changes between calls, and re-syncs automatically when the catalog drifts.\n\n## Quick start\n\nInstall and configure with the minimum required settings:\n\n```bash\nopenclaw plugins install agent-control-openclaw-plugin\n\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.enabled true\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.config.serverUrl \"http://localhost:8000\"\n```\n\nRestart the gateway. The plugin is now active with fail-open defaults and warn-level logging.\n\nFor authenticated setups, also set:\n\n```bash\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.config.apiKey \"ac_your_api_key\"\n```\n\n### Example policy\n\nHere is an [example policy](https://gist.github.com/lan17/02a63572228a2bbda3dc658cf8323d20) which blocks all tools except read and memory for anyone who is not an admin.  For read you can specify approved files and folders.\n\nTo 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\" -\u003e \"Create Contorl\" -\u003e \"Write your own\" and copy paste JSON.  \n\n## Configuration\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `serverUrl` | string | — | Base URL for the Agent Control server. **Required.** |\n| `apiKey` | string | — | API key for authenticating with Agent Control. |\n| `agentName` | string | `openclaw-agent` | Base name used when registering agents with Agent Control. |\n| `agentVersion` | string | — | Version string sent to Agent Control during agent sync. |\n| `timeoutMs` | integer | SDK default | Client timeout in milliseconds. |\n| `failClosed` | boolean | `false` | Block tool calls when Agent Control is unreachable. See [Fail-open vs fail-closed](#fail-open-vs-fail-closed). |\n| `observabilityEnabled` | boolean | `true` | Emit pre-tool control execution events to Agent Control observability. Enabled by default unless explicitly set to `false`. |\n| `logLevel` | string | `warn` | Logging verbosity. See [Logging](#logging). |\n| `userAgent` | string | `openclaw-agent-control-plugin/0.1` | Custom User-Agent header for requests to Agent Control. |\n\nAll settings are configured through the OpenClaw CLI:\n\n```bash\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.config.\u003ckey\u003e \u003cvalue\u003e\n```\n\n### Environment variables\n\n`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.\n\n| Variable | Equivalent config |\n|----------|-------------------|\n| `AGENT_CONTROL_SERVER_URL` | `serverUrl` |\n| `AGENT_CONTROL_API_KEY` | `apiKey` |\n\nConfig values take precedence over environment variables when both are set.\n\n## Fail-open vs fail-closed\n\nBy 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.\n\nSet `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.\n\n```bash\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.config.failClosed true\n```\n\n## Observability\n\nObservability 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.\n\n- Events are emitted only for the `pre` stage because the current OpenClaw plugin SDK typings expose a pre-tool hook but no post-tool hook.\n- Emission is best-effort and non-blocking. Ingest failures are logged at `warn` and do not change allow/block behavior.\n- The plugin stamps OpenTelemetry trace and span IDs when an active span exists, otherwise it generates OTEL-compatible IDs locally.\n\nDisable it with:\n\n```bash\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.config.observabilityEnabled false\n```\n\n## Logging\n\nThe plugin stays quiet by default and only emits warnings, errors, and tool block events.\n\n| Level | What it logs |\n|-------|-------------|\n| `warn` | Warnings, errors, and block events. This is the default. |\n| `info` | Adds lifecycle events: client init, gateway warmup, agent syncs. |\n| `debug` | Adds verbose diagnostics: phase timings, context building, evaluation details. |\n\n```bash\nopenclaw config set plugins.entries.agent-control-openclaw-plugin.config.logLevel \"debug\"\n```\n\n## OpenClaw CLI reference\n\n### Inspect plugin state\n\n```bash\nopenclaw plugins list\nopenclaw plugins info agent-control-openclaw-plugin\nopenclaw plugins doctor\n```\n\n### Enable or disable\n\n```bash\nopenclaw plugins enable agent-control-openclaw-plugin\nopenclaw plugins disable agent-control-openclaw-plugin\n```\n\n### Remove optional config keys\n\n```bash\nopenclaw config unset plugins.entries.agent-control-openclaw-plugin.config.apiKey\nopenclaw config unset plugins.entries.agent-control-openclaw-plugin.config.logLevel\nopenclaw config unset plugins.entries.agent-control-openclaw-plugin.config.agentVersion\nopenclaw config unset plugins.entries.agent-control-openclaw-plugin.config.observabilityEnabled\nopenclaw config unset plugins.entries.agent-control-openclaw-plugin.config.userAgent\n```\n\n### Uninstall\n\n```bash\nopenclaw plugins uninstall agent-control-openclaw-plugin --force\n```\n\n## Local development\n\n1. Clone this repo anywhere on disk.\n2. Install dependencies and run the verification stack:\n\n```bash\nnpm install\nnpm run lint\nnpm run typecheck\nnpm test\n```\n\n3. Link the plugin into your OpenClaw checkout:\n\n```bash\nopenclaw plugins install -l /absolute/path/to/openclaw-plugin\n```\n\n4. Restart the gateway.\n\n`npm run coverage` generates a report under `coverage/` including `coverage/lcov.info` for Codecov uploads.\n\n## Contributing\n\nSee [AGENTS.md](AGENTS.md) for project conventions, testing patterns, and the verification checklist.\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcontrol%2Fopenclaw-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentcontrol%2Fopenclaw-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentcontrol%2Fopenclaw-plugin/lists"}