{"_id":"@cogna8/openclaw-plugin","_rev":"5-a8cb741332dc94d0e3edce7089eeb7cf","name":"@cogna8/openclaw-plugin","dist-tags":{"latest":"0.5.2"},"versions":{"0.2.1":{"name":"@cogna8/openclaw-plugin","version":"0.2.1","license":"MIT","_id":"@cogna8/openclaw-plugin@0.2.1","maintainers":[{"name":"danielmackle","email":"daniel@cogna8.ai"}],"homepage":"https://github.com/Cogna8/openclaw-plugin#readme","bugs":{"url":"https://github.com/Cogna8/openclaw-plugin/issues"},"dist":{"shasum":"dbbdcda403b8c2482854ced2f1169242eec9b12c","tarball":"https://registry.npmjs.org/@cogna8/openclaw-plugin/-/openclaw-plugin-0.2.1.tgz","fileCount":10,"integrity":"sha512-JkWlQMZgg1ACHAsoTAnpmyXLb6vx9J45a+blNCkrPLEo3VGWX+1ZHENux0CXC4fQTj7KmqSiN8/Yoe5MU8G97g==","signatures":[{"sig":"MEYCIQDHgTAcemn55Pry0u0hsMZJHV4Ut7gUlSDAA0iw6/A9AQIhAKwZ5uuPDVaXtktMXw/1QazoXTFF6M11SUdlSHN8MrPZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17609},"main":"./src/index.ts","type":"module","types":"./src/index.ts","gitHead":"b459faed9e1bbe32c6d6df2deaad5a6052b4e6b9","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"danielmackle","email":"daniel@cogna8.ai"},"openclaw":{"build":{"openclawVersion":"2026.4.15","pluginSdkVersion":"2026.4.15"},"compat":{"pluginApi":">=2026.4.0","minGatewayVersion":">=2026.4.0"},"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/Cogna8/openclaw-plugin.git","type":"git"},"_npmVersion":"11.9.0","description":"Gate OpenClaw tool calls through Cogna8's action authority runtime","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","openclaw":"^2026.4.15","typescript":"^5.6.0","@types/node":"^22.0.0"},"peerDependencies":{"openclaw":"^2026.4.15"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-plugin_0.2.1_1776867402051_0.2967066063651913","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@cogna8/openclaw-plugin","version":"0.3.0","license":"MIT","_id":"@cogna8/openclaw-plugin@0.3.0","maintainers":[{"name":"danielmackle","email":"daniel@cogna8.ai"}],"homepage":"https://github.com/Cogna8/openclaw-plugin#readme","bugs":{"url":"https://github.com/Cogna8/openclaw-plugin/issues"},"dist":{"shasum":"40ce569b96896e9ac14b2a8c8e6000957bb37ca1","tarball":"https://registry.npmjs.org/@cogna8/openclaw-plugin/-/openclaw-plugin-0.3.0.tgz","fileCount":11,"integrity":"sha512-nRxdRQ6Fo02ZKKeSUF2ZEMtUcpN/IPyshJtM+ii+KI6/icMKS5GxoI5N4WVH+vosDqSazDpVk0IW+fhZ7wgZXA==","signatures":[{"sig":"MEUCIQDKfcc5r70RLCogBcjwY0dr0L4L63+O3q5fbIoKSxfmOwIgF/1dOaMqlPRiz95qdpMWgvN8sUeTbr0y7Ux6Dhid2r0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21550},"main":"./src/index.ts","type":"module","types":"./src/index.ts","gitHead":"f632070c1a29384519c5bedef4f2bbfdce1dc09f","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"danielmackle","email":"daniel@cogna8.ai"},"openclaw":{"build":{"openclawVersion":"2026.4.15","pluginSdkVersion":"2026.4.15"},"compat":{"pluginApi":">=2026.4.0","minGatewayVersion":">=2026.4.0"},"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/Cogna8/openclaw-plugin.git","type":"git"},"_npmVersion":"11.9.0","description":"Gate OpenClaw tool calls through Cogna8's action authority runtime","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","openclaw":"^2026.4.15","typescript":"^5.6.0","@types/node":"^22.0.0"},"peerDependencies":{"openclaw":"^2026.4.15"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-plugin_0.3.0_1777114552000_0.8509907675516155","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@cogna8/openclaw-plugin","version":"0.5.0","license":"MIT","_id":"@cogna8/openclaw-plugin@0.5.0","maintainers":[{"name":"danielmackle","email":"daniel@cogna8.ai"}],"homepage":"https://github.com/Cogna8/openclaw-plugin#readme","bugs":{"url":"https://github.com/Cogna8/openclaw-plugin/issues"},"dist":{"shasum":"f6e43992baabc32932ec8a5b4817001235f7e93b","tarball":"https://registry.npmjs.org/@cogna8/openclaw-plugin/-/openclaw-plugin-0.5.0.tgz","fileCount":13,"integrity":"sha512-f7eTL9Nl/fPLfQD1Cx0XsfbXjnhbO1oQMO3ARf8DT+cYXLrGdVP+po8mn3nT0AkCWVBLtGv6iFYKbNcj3TfzuQ==","signatures":[{"sig":"MEUCIQDyAyKTsRuT2K7WMbDGynMuz+Rp5Plfo9y0urEU+zQzuAIgNT2Lf90RTuc0B6zLypSZ5WWzt9bwPVY8EdyFMrDDL8U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31459},"main":"./src/index.ts","type":"module","types":"./src/index.ts","gitHead":"c4648ad1b4a92a40ef61c82817696053cb18e5cd","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"danielmackle","email":"daniel@cogna8.ai"},"openclaw":{"build":{"openclawVersion":"2026.4.15","pluginSdkVersion":"2026.4.15"},"compat":{"pluginApi":">=2026.4.0","minGatewayVersion":">=2026.4.0"},"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/Cogna8/openclaw-plugin.git","type":"git"},"_npmVersion":"11.9.0","description":"Gate OpenClaw tool calls through Cogna8's action authority runtime","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","openclaw":"^2026.4.15","typescript":"^5.6.0","@types/node":"^22.0.0"},"peerDependencies":{"openclaw":"^2026.4.15"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-plugin_0.5.0_1777270929495_0.5542833772201943","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@cogna8/openclaw-plugin","version":"0.5.1","license":"MIT","_id":"@cogna8/openclaw-plugin@0.5.1","maintainers":[{"name":"danielmackle","email":"daniel@cogna8.ai"}],"homepage":"https://github.com/Cogna8/openclaw-plugin#readme","bugs":{"url":"https://github.com/Cogna8/openclaw-plugin/issues"},"dist":{"shasum":"278f00396470d5b6b550890b0b28df363e4066d6","tarball":"https://registry.npmjs.org/@cogna8/openclaw-plugin/-/openclaw-plugin-0.5.1.tgz","fileCount":13,"integrity":"sha512-fRnDJvLy1LdfXYxuVYgTeWeKHQx9Le6sLlJaYZ86/skSiJFcg1GzmUVMirCcIwiFYwL0GLoLVAAYLI1Sb8smAQ==","signatures":[{"sig":"MEYCIQDcEM6iNYzrL9pgZkUy6T0l2UGRLbkVOjeBdglj2YOCQQIhAOvi6rVKWC00BMyB/hg94bllgDfn/TE+/nV3YHZ00Ab7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31497},"main":"./src/index.ts","type":"module","types":"./src/index.ts","gitHead":"5691a6b60774ad074377ec499d36e4006121c038","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"danielmackle","email":"daniel@cogna8.ai"},"openclaw":{"build":{"openclawVersion":"2026.4.15","pluginSdkVersion":"2026.4.15"},"compat":{"pluginApi":">=2026.4.0","minGatewayVersion":">=2026.4.0"},"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/Cogna8/openclaw-plugin.git","type":"git"},"_npmVersion":"11.9.0","description":"Gate OpenClaw tool calls through Cogna8's action authority runtime","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","openclaw":"^2026.4.15","typescript":"^5.6.0","@types/node":"^22.0.0"},"peerDependencies":{"openclaw":"^2026.4.15"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-plugin_0.5.1_1777272421505_0.3998895398553477","host":"s3://npm-registry-packages-npm-production"}},"0.5.2":{"name":"@cogna8/openclaw-plugin","version":"0.5.2","type":"module","main":"./src/index.ts","types":"./src/index.ts","publishConfig":{"access":"public"},"description":"Gate OpenClaw tool calls through Cogna8's action authority runtime","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Cogna8/openclaw-plugin.git"},"scripts":{"typecheck":"tsc --noEmit","test":"vitest run"},"peerDependencies":{"openclaw":"^2026.4.15"},"devDependencies":{"@types/node":"^22.0.0","openclaw":"^2026.4.15","typescript":"^5.6.0","vitest":"^1.6.0"},"openclaw":{"extensions":["./src/index.ts"],"compat":{"pluginApi":">=2026.4.0","minGatewayVersion":">=2026.4.0"},"build":{"openclawVersion":"2026.4.15","pluginSdkVersion":"2026.4.15"}},"gitHead":"f395762697de966583803f0868e5e78b98805719","_id":"@cogna8/openclaw-plugin@0.5.2","bugs":{"url":"https://github.com/Cogna8/openclaw-plugin/issues"},"homepage":"https://github.com/Cogna8/openclaw-plugin#readme","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-ePdhr29mzCBRm+/8CKOMRxKrvH/m/7EojM81OebeQS3rILLPDl7WSNHahpq2CuyjJQtJoPgkI7I4fbbu+DUwtA==","shasum":"845079685b5638b885da015c4f53547ec539addd","tarball":"https://registry.npmjs.org/@cogna8/openclaw-plugin/-/openclaw-plugin-0.5.2.tgz","fileCount":13,"unpackedSize":31497,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD/T11/ftQJM2xr3ydbtYc9W5EV28ZXJ2IkBxzTHyW39wIgKteA9Z0NdrESMla/1qoh/VgByefoM2htYvnb0S4FdS0="}]},"_npmUser":{"name":"danielmackle","email":"daniel@cogna8.ai"},"directories":{},"maintainers":[{"name":"danielmackle","email":"daniel@cogna8.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-plugin_0.5.2_1777272646823_0.35350839113187393"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T14:16:41.933Z","modified":"2026-04-27T06:50:47.132Z","0.2.1":"2026-04-22T14:16:42.208Z","0.3.0":"2026-04-25T10:55:52.145Z","0.5.0":"2026-04-27T06:22:09.656Z","0.5.1":"2026-04-27T06:47:01.694Z","0.5.2":"2026-04-27T06:50:46.989Z"},"bugs":{"url":"https://github.com/Cogna8/openclaw-plugin/issues"},"license":"MIT","homepage":"https://github.com/Cogna8/openclaw-plugin#readme","repository":{"type":"git","url":"git+https://github.com/Cogna8/openclaw-plugin.git"},"description":"Gate OpenClaw tool calls through Cogna8's action authority runtime","maintainers":[{"name":"danielmackle","email":"daniel@cogna8.ai"}],"readme":"![OpenClaw + Cogna8](https://raw.githubusercontent.com/Cogna8/openclaw-plugin/main/docs/assets/openclaw-cogna8.png)\n\n# Cogna8 OpenClaw Plugin\n\nGate OpenClaw tool calls through Cogna8's action authority runtime.\n\nInstall it, enable a few policies in the Cogna8 Portal, and your OpenClaw agents stop writing secrets to `.env`, deleting your home directory, or pushing to `main` without confirmation.\n\n## Quick start (5 minutes)\n\n### 1. Get an API key\n\nSign in at [openclaw.cogna8.ai](https://openclaw.cogna8.ai) with Google, then visit **Dashboard → API Keys** and click **Generate key**. Copy the key (starts with `cg8_sk_`).\n\n### 2. Install the plugin\n\n```bash\ngit clone https://github.com/Cogna8/openclaw-plugin.git\ncd openclaw-plugin\nnpm install\nopenclaw plugins install .\n```\n\n### 3. Configure\n\nAdd the plugin to your OpenClaw config (`~/.openclaw/config.json5` or equivalent):\n\n```json5\n{\n  plugins: {\n    entries: {\n      cogna8: {\n        enabled: true,\n        config: {\n          apiKey: \"cg8_sk_<your-key-here>\"\n        }\n      }\n    }\n  }\n}\n```\n\nThen restart the gateway:\n\n```bash\nopenclaw gateway restart\n```\n\n### 4. Pick your policies\n\nVisit **Dashboard → Policies** at [openclaw.cogna8.ai](https://openclaw.cogna8.ai) and enable the pre-built templates:\n\n- **Block shell command execution** — prevents `bash`, `sh`, `zsh`, `powershell`, and related variants\n- **Block file deletions** — prevents `rm`, `unlink`, `trash`, and compound variants\n- **Block file writes** — prevents writes including to `.env`, `.ssh`, `.aws`, credentials files\n- **Block outbound HTTP** — prevents data exfiltration via HTTP calls\n- **Block code execution** — prevents `python`, `node`, `eval`, and related execution tools\n\nYou can also create custom rules for specific tools — for example, confirm rules that pause for your approval before running `sudo`, `rm -rf`, or `git push` to protected branches.\n\n### How confirmations appear\n\nWhen a confirm rule matches a tool call, OpenClaw delivers an approval prompt through whichever channel you're using — Telegram inline keyboard, Slack Block Kit buttons, Discord components, TUI prompt, or any other channel supported by your OpenClaw setup. You approve or deny in-channel. OpenClaw handles the UX; Cogna8 records the outcome for your audit log.\n\n### 5. Verify\n\nTrigger a tool call in OpenClaw. In the gateway logs you'll see:\n\n```\n[cogna8] Agent registered (external_id=default, public_id=agt_..., status=synced)\n[cogna8] Registered. Evaluating tool calls against https://openclaw-api.cogna8.ai (agent: default, failureMode: open)\n```\n\nIf a block rule matches, you'll see `[cogna8] Blocked tool call <tool_name> ...`.\n\nIf a confirm rule matches, you'll see `[cogna8] Approval required for <tool_name> (decision_id=ev_...)`.\n\nIn the Portal, the **Usage** page shows your evaluation count incrementing live, and the **Agents** page shows your plugin's registration.\n\n## How it works\n\nWhen an OpenClaw agent is about to call a tool, the plugin sends the tool-call context to Cogna8's service. Cogna8 evaluates it against your active policies and returns one of:\n\n- `allow` - the tool call proceeds\n- `block` - the tool call is stopped with a reason shown to the agent\n- `confirm` - the tool call pauses for user approval\n\nIf the Cogna8 service is unreachable, behaviour depends on `failureMode`:\n\n- `failureMode: \"open\"` (default) allows tool calls\n- `failureMode: \"closed\"` blocks tool calls\n\nAll policy logic runs server-side. The plugin is a thin transport layer. You can change policies from the Portal without touching your OpenClaw config.\n\n## Configuration options\n\n| Option | Default | Meaning |\n|---|---|---|\n| `apiKey` | required | Cogna8 API key from [openclaw.cogna8.ai/dashboard/keys](https://openclaw.cogna8.ai/dashboard/keys) |\n| `serverUrl` | `https://openclaw-api.cogna8.ai` | Cogna8 service base URL |\n| `agentId` | `default` | Agent identifier sent to Cogna8 |\n| `timeoutMs` | `3000` | Evaluate request timeout in milliseconds |\n| `failureMode` | `open` | `open` allows on failure, `closed` blocks on failure |\n\n## Resilience\n\nThe plugin automatically retries transient service errors and trips a circuit breaker on sustained failure to keep your tool calls healthy during deploys, blips, or service outages.\n\n**Retry policy** (not configurable):\n\n- Single retry on 502, 503, 504, and network errors (ECONNRESET, ETIMEDOUT, EAI_AGAIN, ENETUNREACH).\n- 200ms delay before retry.\n- Both attempts share the `timeoutMs` budget — total time is bounded at the configured `timeoutMs` (default 3000ms).\n- 4xx, 500, and abort errors are not retried.\n\n**Circuit breaker** (not configurable):\n\n- After 5 consecutive transient failures, the breaker opens.\n- While open, evaluate calls bypass the service for 30 seconds and apply `failureMode` directly.\n- A single successful evaluate after cooldown closes the breaker.\n\nThese behaviors are intentionally not configurable in v0.4. They use sensible defaults derived from operational experience. If you observe them mis-tuned in production, file an issue.\n\n## Automatic agent registration\n\nOn plugin load, the plugin registers the configured agent with Cogna8 by calling `POST /api/v1/agents/register`. Registration is idempotent - subsequent restarts return `synced` status.\n\n## Multi-agent support\n\nThis plugin transparently handles multiple OpenClaw agents within a single install.\n\nWhen OpenClaw provides agent identity in the `before_tool_call` context (`ctx.agentId`), the plugin uses that identity as the Cogna8 agent's `external_id`. Each distinct agent is registered with the service on first sight and is then resolved independently on every evaluate request. Agents have independent rules and audit trails.\n\nWhen OpenClaw does not provide agent identity, or provides an empty value, the plugin falls back to `config.agentId` (default `\"default\"`). This preserves backward compatibility for single-agent installs.\n\nRegistration is lazy. The first tool call for a newly seen agent waits for registration before evaluate, so the service can resolve the agent. Subsequent calls for that agent do not repeat registration in the same plugin process. If the plugin process restarts, agents may be re-registered; the service treats this idempotently and returns `synced`.\n\n**Capacity:** a Cogna8 account allows up to 10 active agents by default. If you need more, contact us. Attempts to register an 11th agent are rejected by the service; evaluate calls for that unregistered agent will fall back to your configured `failureMode`.\n\n**Migrating from multiple plugin configs to one:** if you currently run multiple plugin instances with distinct `agentId` values, you can collapse them into a single install. Existing Cogna8 agent rows are keyed by `external_id`, so rule continuity is preserved as long as OpenClaw supplies the same agent identity.\n\n## Free tier\n\n- 10,000 evaluations per month\n- 10 registered agents\n- 25 rules per agent\n- Burst rate 100 requests/minute per API key\n\n## Links\n\n- [OpenClaw Portal](https://openclaw.cogna8.ai) - manage keys, policies, and view usage\n- [Cogna8](https://cogna8.ai) - product site\n- [Report a bug](https://github.com/Cogna8/openclaw-plugin/issues/new)\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}