@limits/openclaw 0.0.1

package/README.md

@@ -0,0 +1,289 @@
+# @limits/openclaw
+
+[![npm version](https://img.shields.io/npm/v/@limits/openclaw.svg?style=flat-square)](https://www.npmjs.com/package/@limits/openclaw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![GitHub](https://img.shields.io/badge/GitHub-limitsdev%2Flimits--openclaw-181717?style=flat-square&logo=github)](https://github.com/limitsdev/limits-openclaw)
+
+**Official** OpenClaw plugin for the [Limits](https://limits.dev) platform. Delegates policy enforcement via HTTP. Every decision is made by calling `POST {baseUrl}/openclaw/enforce` before and after each tool call. Optional policy-generator tools let the agent create and update policies from natural language.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [How it works](#how-it-works)
+- [Policy-generator tools](#policy-generator-tools)
+- [Configuration](#configuration)
+- [Policy tag convention](#policy-tag-convention-limits-backend)
+- [Enforcement API contract](#limits-api-contract)
+- [CLI reference](#cli-commands)
+- [Security](#security-openclaw--limits)
+- [Development](#development)
+- [Migration from limits-enforcer](#migration-from-limits-enforcer)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @limits/openclaw
+```
+
+```bash
+yarn add @limits/openclaw
+```
+
+```bash
+pnpm add @limits/openclaw
+```
+
+Then register the plugin with OpenClaw:
+
+```bash
+openclaw plugins install ./node_modules/@limits/openclaw
+openclaw plugins enable "@limits/openclaw"
+```
+
+---
+
+## Quick Start
+
+1. **Install** the plugin (see [Installation](#installation)).
+2. **Configure** your API token (required for enforcement and policy-generator tools):
+
+```bash
+openclaw limits configure
+```
+
+Or set config manually:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "@limits/openclaw": {
+        "enabled": true,
+        "config": {
+          "apiToken": "sk_your_organization_api_key"
+        }
+      }
+    }
+  }
+}
+```
+
+3. **Allow the plugin** in your agent's tool list so the agent can use policy-generator tools (optional). Edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": { "allow": ["@limits/openclaw"] }
+      }
+    ]
+  }
+}
+```
+
+4. **Run your agent.** Before and after each tool call, the plugin calls the Limits backend. No code changes required.
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+  subgraph pre [Before tool call]
+    A[Tool invoked] --> B["POST /openclaw/enforce phase=pre"]
+    B --> C{Action?}
+    C -->|ALLOW| D[Run tool]
+    C -->|BLOCK| E[Block call]
+    C -->|REWRITE| F[Replace args, then run]
+  end
+  subgraph post [After tool call]
+    D --> G["POST /openclaw/enforce phase=post"]
+    G --> H{Action?}
+    H -->|ALLOW| I[Return result]
+    H -->|BLOCK| J[Safe blocked message]
+    H -->|REDACT| K[Redacted result]
+    H -->|REWRITE| L[Rewritten result]
+  end
+```
+
+1. **Before each tool call** (`before_tool_call`): the plugin POSTs `phase: "pre"` with tool name and args. Limits returns `ALLOW`, `BLOCK`, or `REWRITE` (with `rewriteArgs`). The plugin blocks the call, allows it, or replaces the tool arguments accordingly.
+2. **After each tool call** (`after_tool_call`): the plugin POSTs `phase: "post"` with tool name, args, and result. Limits returns `ALLOW`, `BLOCK`, `REDACT`, or `REWRITE` (with `redactedResult` or `rewrittenResult`). The plugin leaves the result unchanged, replaces it with a safe blocked response, or replaces it with the redacted/rewritten value.
+
+**Compatibility:** This plugin requires an OpenClaw build where tool hooks are wired into the execution path. If you see **`[@limits/openclaw] before_tool_call observed`** in logs once after a tool runs, hooks are working. See [OpenClaw #6535](https://github.com/openclaw/openclaw/issues/6535) if hooks never fire.
+
+---
+
+## Policy-generator tools
+
+When `apiToken` is set, the plugin registers two optional tools and loads the **limits-policy-generator** skill:
+
+| Tool | Description |
+|------|-------------|
+| **`limits_generate_create_policy`** | Generate a new policy from natural language and create it on the Limits backend (`POST /api/policies/generatecreate`). |
+| **`limits_generate_update_policy`** | Generate updates from natural language and apply to an existing policy (`POST /api/policies/:id/generateupdate`). |
+
+The agent can then fulfill requests like “create a policy that blocks payment tools” or “update my policy to also block stripe_*” by calling these tools.
+
+### Add the skill to the workspace
+
+When you run `openclaw limits configure` (or `npm run configure`), you can choose to add the limits-policy-generator skill to your OpenClaw workspace when prompted.
+
+Optionally, you can copy it manually. The example below is for Unix; on Windows use the wizard or PowerShell equivalents (e.g. `New-Item -ItemType Directory -Force` and `Copy-Item -Recurse`).
+
+```bash
+mkdir -p ~/.openclaw/workspace/skills/limits-policy-generator
+cp -r ./node_modules/@limits/openclaw/skills/limits-policy-generator/. ~/.openclaw/workspace/skills/limits-policy-generator/
+```
+
+### Expose tools to the agent
+
+The plugin registers these tools as **optional**. Add the plugin to the agent's tool allowlist (see [Quick Start](#quick-start)) so the agent can call them. Use `"@limits/openclaw"` to allow all tools from this plugin, or allow by name: `["limits_generate_create_policy", "limits_generate_update_policy"]`.
+
+### Sandboxed agents
+
+If the agent runs in a **sandbox**, add `"@limits/openclaw"` (or the tool names) to `tools.sandbox.tools.allow` as well so the sandboxed agent can call the policy tools. Otherwise the agent can have the skill but cannot invoke the tools from inside the sandbox.
+
+---
+
+## Configuration
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `baseUrl` | — | *Fixed in plugin* | Base URL for `POST /openclaw/enforce` and policy-generator API calls. Optional in config for compatibility. |
+| `apiToken` | No | — | Organization API key for `/openclaw/enforce` and policy-generator tools. Fallback when event/context don't provide a token. Store securely or use `LIMITS_ENFORCER_API_TOKEN` env. |
+| `timeoutMs` | No | `2500` | Request timeout in milliseconds. |
+| `failMode` | No | `"allow"` | When Limits is unreachable or errors: **Pre:** `"allow"` → let the call proceed; `"block"` → block the call. **Post:** `"allow"` → keep original result; `"block"` → replace result with a safe blocked message. |
+| `tokenSource` | No | `"event.metadata.apiToken"` | Dot-separated path to the API token. The plugin uses this first; if missing, it falls back to `apiToken`. |
+| `redactLogs` | No | `true` | Whether to avoid logging sensitive data (token/args are never logged). |
+
+### Environment overrides
+
+| Variable | Maps to |
+|----------|---------|
+| `LIMITS_ENFORCER_TIMEOUT_MS` | `timeoutMs` |
+| `LIMITS_ENFORCER_FAIL_MODE` | `allow` or `block` |
+| `LIMITS_ENFORCER_TOKEN_SOURCE` | token path |
+| `LIMITS_ENFORCER_REDACT_LOGS` | `true` / `1` for true |
+| `LIMITS_ENFORCER_API_TOKEN` | `apiToken` |
+
+### Gateway config example
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "@limits/openclaw": {
+        "enabled": true,
+        "config": {
+          "apiToken": "sk_your_organization_api_key",
+          "timeoutMs": 2500,
+          "failMode": "allow",
+          "tokenSource": "event.metadata.apiToken"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Policy tag convention (Limits backend)
+
+Policies are scoped to OpenClaw tool calls using **tags** in the Limits dashboard:
+
+| Tag | Meaning |
+|-----|---------|
+| `openclaw:phase:pre` | Apply only in the **pre** phase (before the tool runs). |
+| `openclaw:phase:post` | Apply only in the **post** phase (after the tool runs, e.g. guardrails on output). |
+| *(no openclaw:phase tag)* | Apply to **both** phases. |
+| `openclaw:tool:stripe.charge` | Apply only to the tool named `stripe.charge`. |
+| `openclaw:tool:stripe.*` | Apply to all tools whose name **starts with** `stripe.`. |
+| *(no openclaw:tool tag)* | Apply to **all** tools. |
+| `openclaw:scope:all` | Explicit scope: policy applies to all tools (required when `OPENCLAW_REQUIRE_SCOPE_TAGS` is set). |
+| `openclaw:scope:tools` | Explicit scope: policy applies to specific tools (required when scope tags are enforced). |
+
+**Example:** To block Stripe tool calls with amount > 200, create a **CONDITIONS** policy like `input.args.amount > 200 → BLOCK`, and tag it with `openclaw:phase:pre` and `openclaw:tool:stripe.*`.
+
+---
+
+## Limits API contract
+
+**Endpoint:** `POST {baseUrl}/openclaw/enforce`
+
+**Request body (JSON)** — same shape for pre and post:
+
+| Field | Pre | Post | Description |
+|-------|-----|------|-------------|
+| `phase` | ✓ | ✓ | `"pre"` or `"post"`. |
+| `apiToken` | ✓ | ✓ | String from `tokenSource` (identifies the org on Limits). |
+| `tool` | ✓ | ✓ | Object: `name`, `args`, optional `toolCallId`. For **post** only, `tool` also includes `result`. |
+| `context` | ✓ | ✓ | Optional: `requestId`, `runId`, `sessionKey`, `agentId`, `channel`, `userMessageSummary`. |
+
+**Response (JSON):**
+
+- **Pre:** `{ "action": "ALLOW" }` | `{ "action": "BLOCK", "reason": "..." }` | `{ "action": "REWRITE", "rewriteArgs": { ... } }`
+- **Post:** `{ "action": "ALLOW" }` | `{ "action": "BLOCK", "reason": "..." }` | `{ "action": "REDACT", "redactedResult": ... }` | `{ "action": "REWRITE", "rewrittenResult": ... }`
+
+**Decision precedence:** Deny wins — any `BLOCK` overrides `ALLOW`. Document your own precedence for REWRITE/REDACT if you combine multiple policies.
+
+---
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `openclaw plugins install <path>` | Install plugin from path. |
+| `openclaw plugins install -l <path>` | Link plugin (no copy, for development). |
+| `openclaw plugins enable "@limits/openclaw"` | Enable the plugin. |
+| `openclaw plugins list` | List installed plugins. |
+| `openclaw plugins doctor` | Check plugin health. |
+| `openclaw limits configure` | Interactive wizard to set API token and sandbox allowlist. |
+| `openclaw config get 'plugins.entries["@limits/openclaw"]'` | Show plugin config. |
+| `openclaw config set 'plugins.entries["@limits/openclaw"].config.apiToken' "sk_..."` | Set apiToken manually. |
+
+---
+
+## Security (OpenClaw ↔ Limits)
+
+- Use **HTTPS** in production.
+- For higher assurance (e.g. internal networks), consider **mTLS** or a **shared HMAC** header in addition to `apiToken`.
+- Apply **rate limiting** and auth on the Limits endpoint.
+
+---
+
+## Development
+
+- **Tests:** `npm test` (Vitest). Unit tests mock the enforcer; the integration test runs a real HTTP server and exercises the full pre/post flow.
+- **Retries:** The enforcer client retries up to 2 times on HTTP 429 or 5xx with exponential backoff (200 ms, 400 ms). Non-retryable errors trigger `failMode` immediately.
+
+---
+
+## Migration from limits-enforcer
+
+If you were using the plugin under the old name **limits-enforcer**, update your config and CLI usage:
+
+| Before | After |
+|--------|-------|
+| Plugin ID / allowlist: `"limits-enforcer"` | `"@limits/openclaw"` |
+| Config path: `plugins.entries.limits-enforcer` | `plugins.entries["@limits/openclaw"]` |
+| CLI command: `openclaw limits-enforcer configure` | `openclaw limits configure` |
+| Log prefix: `[limits-enforcer]` | `[@limits/openclaw]` |
+
+After renaming, reinstall the plugin and enable `"@limits/openclaw"`.
+
+---
+
+## License
+
+MIT — [Limits](https://limits.dev) — [GitHub](https://github.com/limitsdev/limits-openclaw)

package/openclaw.plugin.json

@@ -0,0 +1,42 @@
+{
+  "id": "@limits/openclaw",
+  "name": "Limits OpenClaw",
+  "description": "Delegates policy enforcement to the Limits platform before and after every tool call. Optional policy-generator tools for creating/updating policies from natural language.",
+  "version": "0.0.1",
+  "main": "./src/index.ts",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "baseUrl": {
+        "type": "string",
+        "description": "Base URL for POST /openclaw/enforce and for policy-generator API calls. Same URL for enforcement and policy tools."
+      },
+      "apiToken": {
+        "type": "string",
+        "description": "Organization API key for /openclaw/enforce and policy-generator tools. Store securely in gateway config or use LIMITS_ENFORCER_API_TOKEN env."
+      },
+      "timeoutMs": {
+        "type": "number",
+        "default": 2500,
+        "description": "Request timeout in milliseconds."
+      },
+      "failMode": {
+        "type": "string",
+        "enum": ["allow", "block"],
+        "default": "allow",
+        "description": "When Limits backend is unreachable: allow = proceed; block = block the call (pre) or replace result (post)."
+      },
+      "tokenSource": {
+        "type": "string",
+        "default": "event.metadata.apiToken",
+        "description": "Dot-separated path to API token: event.metadata.apiToken, ctx.auth.token, or env.LIMITS_API_TOKEN."
+      },
+      "redactLogs": {
+        "type": "boolean",
+        "default": true,
+        "description": "Whether to avoid logging sensitive data."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@limits/openclaw",
+  "version": "0.0.1",
+  "description": "Delegates policy enforcement to the Limits platform before and after every tool call. Optional policy-generator tools for creating/updating policies from natural language.",
+  "keywords": ["openclaw", "limits", "policy", "enforcement", "agent", "guardrails", "ai-safety"],
+  "author": "Limits",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/limitsdev/limits-openclaw.git" },
+  "bugs": { "url": "https://github.com/limitsdev/limits-openclaw/issues" },
+  "homepage": "https://github.com/limitsdev/limits-openclaw#readme",
+  "type": "module",
+  "main": "./src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "configure": "node scripts/configure.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "openclaw": {
+    "hooks": ["./"],
+    "extensions": ["./"],
+    "events": ["before_tool_call", "after_tool_call"]
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/scripts/configure.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Interactive configure for @limits/openclaw plugin.
+ * Writes to OpenClaw config via: openclaw config set plugins.entries["@limits/openclaw"].config.<key> <value>
+ *
+ * Run from plugin root: node scripts/configure.js
+ * Or: npm run configure
+ *
+ * Prerequisite: openclaw plugins install <path> and openclaw plugins enable "@limits/openclaw"
+ * (so plugins.entries["@limits/openclaw"] exists).
+ */
+
+import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import os from "node:os";
+
+const PREFIX = 'plugins.entries["@limits/openclaw"].config';
+const SKILL_NAME = "limits-policy-generator";
+
+function getPluginRoot() {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  return join(scriptDir, "..");
+}
+
+function getWorkspaceSkillsDest() {
+  const workspaceRoot =
+    process.env.OPENCLAW_WORKSPACE || join(os.homedir(), ".openclaw", "workspace");
+  return join(workspaceRoot, "skills", SKILL_NAME);
+}
+
+function copySkillToWorkspace() {
+  const pluginRoot = getPluginRoot();
+  const source = join(pluginRoot, "skills", SKILL_NAME);
+  const dest = getWorkspaceSkillsDest();
+
+  if (!fs.existsSync(source)) {
+    console.log("\nSkill source not found, skipping.");
+    return;
+  }
+  try {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.cpSync(source, dest, { recursive: true });
+    console.log(`\nCopied ${SKILL_NAME} to ${dest}.`);
+  } catch (err) {
+    console.error("\nFailed to copy skill:", err instanceof Error ? err.message : String(err));
+  }
+}
+
+function ask(rl, question, defaultValue = "") {
+  const prompt = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      resolve(typeof answer === "string" && answer.trim() !== "" ? answer.trim() : defaultValue);
+    });
+  });
+}
+
+function runOpenClawConfigSet(key, value) {
+  return new Promise((resolve, reject) => {
+    const fullKey = `${PREFIX}.${key}`;
+    const child = spawn("openclaw", ["config", "set", fullKey, value], {
+      stdio: "inherit",
+      shell: true,
+    });
+    child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`openclaw config set exited ${code}`))));
+    child.on("error", reject);
+  });
+}
+
+async function main() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log("\nConfigure @limits/openclaw plugin (writes to OpenClaw config via openclaw config set).");
+  console.log("Prerequisite: openclaw plugins install <path> (or -l to link).");
+  console.log("Tip: After linking, you can also run: openclaw limits configure\n");
+
+  const apiToken = await ask(rl, "Organization API key (apiToken) — required for enforce and policy-generator tools", process.env.LIMITS_ENFORCER_API_TOKEN || "");
+  const addSkillAnswer = await ask(rl, "Add limits-policy-generator skill to OpenClaw workspace?", "Y");
+
+  rl.close();
+
+  if (apiToken) await runOpenClawConfigSet("apiToken", JSON.stringify(apiToken));
+
+  const addSkillYes = /^y(es)?$/i.test(addSkillAnswer.trim());
+  if (addSkillYes) copySkillToWorkspace();
+
+  console.log("\nDone. Restart the gateway if it is running.");
+  console.log('Verify: openclaw config get plugins.entries["@limits/openclaw"]');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/skills/limits-policy-generator/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: limits-policy-generator
+description: "Generate and create or update policy rules on the Limits SaaS from natural language. Use when the user asks to add, change, or create policy rules enforced by the Limits backend."
+metadata: {"openclaw": {"emoji": "📜", "requires": {"config": ["plugins.entries[\"@limits/openclaw\"].config.apiToken"]}}}
+---
+
+# Limits Policy Generator
+
+You have two tools for creating and updating policies on the Limits SaaS from natural language. They call the Limits backend so the user's enforcement rules are created or updated there (and apply to tool-call enforcement via the @limits/openclaw plugin).
+
+## When to use this skill
+
+Use these tools when the user says things like:
+
+- "Create a policy that blocks all payment tools"
+- "Add a rule: never run bash with rm -rf"
+- "Generate a policy from this: block transactions over 500"
+- "Update my policy to also block stripe_* tools"
+- "I want to add a guardrail that redacts emails from tool output"
+- "Change the payment limit to 700"
+
+## Tools available
+
+### `limits_generate_create_policy`
+
+Generate a new policy from natural language and create it on the Limits backend. Use when the user wants to **add** a new policy.
+
+```
+limits_generate_create_policy(
+  input="Block any tool whose name starts with stripe_ or payment_. Allow all other tools.",
+  mode="INSTRUCTIONS",
+  tools=["stripe_.*", "payment_.*"]
+)
+```
+
+- **input** (required): Natural-language description of the policy (what to block, allow, or require).
+- **mode** (optional): `"INSTRUCTIONS"` | `"CONDITIONS"` | `"GUARDRAIL"`. Default is INSTRUCTIONS. Use GUARDRAIL for rules that scan tool **output** (e.g. redact PII).
+- **tools** (required): Which tool calls this policy applies to. See "Where to apply" section below.
+
+### `limits_generate_update_policy`
+
+Generate updates from natural language and apply them to an **existing** policy. Use when the user wants to **change** a policy they already have.
+
+```
+limits_generate_update_policy(
+  policyId="uuid-of-existing-policy",
+  input="Also block transfer_money. Keep the existing amount limit.",
+  mode="INSTRUCTIONS"
+)
+```
+
+- **policyId** (required): The ID of the existing policy to update (UUID).
+- **input** (required): Natural-language description of the changes or additions.
+- **mode** (optional): Same as above.
+- **Note:** Update does **not** change which tools the policy applies to — scope is fixed at creation time. If the user wants to change scope, they should create a new policy.
+
+## Where to apply (tools parameter)
+
+The `tools` parameter on `limits_generate_create_policy` is **required** and controls which tool calls the policy is enforced on.
+
+### Values
+
+| Value | Meaning |
+|-------|---------|
+| `["*"]` | Apply to **all** tool calls / all requests |
+| `["<tool_name>"]` | Apply to the exact tool (use only names from the agent's actual tool list) |
+| `["<prefix>.*"]` | Apply to all tools whose name starts with that prefix (e.g. `payment_.*`) |
+
+Use `prefix.*` (dot-star) for prefix matching. The backend also accepts `prefix_*` and normalizes it to `prefix_.*`. **Use only tool names or prefixes that exist in the user's / agent's available tools** — do not invent names.
+
+### Ask-once logic (required)
+
+**Do not call `limits_generate_create_policy` until you know scope.** If the user did not say scope, ask once.
+
+- User says **"everywhere"**, **"all requests"**, **"globally"**, or **"all tools"** → use `["*"]` without asking.
+- User **explicitly names specific tools** (e.g. "for read_file", "payment tools", "stripe_*") → use those tools without asking.
+- User **does not say** "all" / "everywhere" / "globally" and **does not name any tools** (e.g. "create a policy if currency is JOD allow request", "create a policy that blocks payments") → you **must ask once** before calling the tool: _"Which tools should this policy apply to: all tool calls, or only specific tools? If specific, which tool names from your available tools?"_ Then call the tool with the user's answer.
+
+Do not assume scope. Do not call the create-policy tool immediately when the user only describes the rule (e.g. "if currency is JOD allow") without stating where it applies. Ask once, then call.
+
+### Tool names: use source of truth only
+
+When setting the `tools` parameter, use **only tool names from the agent's actual available tools** (the list of tools you have access to). Do not invent or assume tool names. If the user wants "specific tools", list the relevant tools from your real tool list and use those exact names (or prefix patterns like `name_.*` that match them). If you do not have a list of available tools, ask the user which tools should be in scope and use only names they confirm.
+
+## Recommended flow
+
+1. If the user wants a **new** policy:
+   - **First determine scope.** If the user did not say "all tools" / "everywhere" / "globally" and did not name specific tools, ask once: "Which tools should this apply to: all tool calls or specific tools? If specific, which ones?"
+   - Only then call `limits_generate_create_policy` with `input`, `tools` (from user or from their actual tool list), and optionally `mode`.
+   - Confirm what was created and **where it applies** (e.g. "This policy applies to all tools" or "This policy applies to [tool names]").
+2. If the user wants to **change** an existing policy:
+   - Use `limits_generate_update_policy` with the policy id and the change description. (You may need to list or find the policy id first if the user says "update my payment policy".)
+   - Remind the user that **scope (which tools the policy applies to) cannot be changed via update** — it stays as set when the policy was created.
+3. Policies on the Limits backend apply to tool-call enforcement (via @limits/openclaw) for that organization.
+
+## Sandbox vs host
+
+**If you are running inside a sandbox:** The `limits_generate_create_policy` and `limits_generate_update_policy` tools are only available if the gateway config allows them in the sandbox (e.g. `tools.sandbox.tools.allow` includes `"@limits/openclaw"`). If those tools are not in your tool list, you cannot invoke them from this environment.
+
+- **To run the policy tools from the sandbox:** The admin must add `@limits/openclaw` to the agent allowlist and to `tools.sandbox.tools.allow` (see the @limits/openclaw README). After that, you can call the tools from here.
+- **If the tools are still not available:** Tell the user to run the policy command on the **host** or an agent instance that has the Limits backend wired up and the tools allowed.
+
+## Configuration
+
+The plugin must be configured with:
+
+- **baseUrl**: Base URL of the Limits API (e.g. `https://api.limits.dev`). Used for enforce and policy-generator tools.
+- **apiToken**: Organization API key (Bearer) for the Limits backend. Used for enforce and policy-generator tools.
+
+Without these, the tools will not be available or will return an error asking the user to configure them.

package/src/config.ts

@@ -0,0 +1,70 @@
+/**
+ * Plugin config: loaded from gateway config with env var overrides.
+ */
+
+const STATIC_BASE_URL = "https://extensionally-jettisonable-rosann.ngrok-free.dev";
+
+export interface EnforcerConfig {
+  baseUrl: string;
+  timeoutMs: number;
+  failMode: "allow" | "block";
+  tokenSource: string;
+  redactLogs: boolean;
+  /** Optional: organization API key sent as apiToken to POST /openclaw/enforce and for policy-generator tools. Used when event/context don't provide a token (fallback for all requests). */
+  apiToken?: string;
+}
+
+const DEFAULTS: EnforcerConfig = {
+  baseUrl: STATIC_BASE_URL,
+  timeoutMs: 2500,
+  failMode: "allow",
+  tokenSource: "event.metadata.apiToken",
+  redactLogs: true,
+};
+
+export type ApiLike = {
+  config?: {
+    plugins?: {
+      entries?: Record<
+        string,
+        { enabled?: boolean; config?: Partial<EnforcerConfig> }
+      >;
+    };
+  };
+};
+
+export function loadConfig(api: ApiLike): EnforcerConfig {
+  const raw =
+    api.config?.plugins?.entries?.["@limits/openclaw"]?.config ?? ({} as Partial<EnforcerConfig>);
+
+  // baseUrl defaults to static; not in wizard or schema so users don't edit it (config override only for tests/advanced)
+  const baseUrl = raw.baseUrl ?? DEFAULTS.baseUrl;
+  const timeoutMs =
+    typeof process.env.LIMITS_ENFORCER_TIMEOUT_MS === "string"
+      ? parseInt(process.env.LIMITS_ENFORCER_TIMEOUT_MS, 10)
+      : raw.timeoutMs ?? DEFAULTS.timeoutMs;
+  const failMode =
+    (process.env.LIMITS_ENFORCER_FAIL_MODE as "allow" | "block") ??
+    raw.failMode ??
+    DEFAULTS.failMode;
+  const tokenSource =
+    process.env.LIMITS_ENFORCER_TOKEN_SOURCE ??
+    raw.tokenSource ??
+    DEFAULTS.tokenSource;
+  const redactLogs =
+    process.env.LIMITS_ENFORCER_REDACT_LOGS !== undefined
+      ? process.env.LIMITS_ENFORCER_REDACT_LOGS === "true" ||
+        process.env.LIMITS_ENFORCER_REDACT_LOGS === "1"
+      : raw.redactLogs ?? DEFAULTS.redactLogs;
+  const apiToken =
+    process.env.LIMITS_ENFORCER_API_TOKEN ?? raw.apiToken ?? undefined;
+
+  return {
+    baseUrl,
+    timeoutMs: Number.isNaN(timeoutMs) ? DEFAULTS.timeoutMs : timeoutMs,
+    failMode: failMode === "block" ? "block" : "allow",
+    tokenSource: typeof tokenSource === "string" ? tokenSource : DEFAULTS.tokenSource,
+    redactLogs: Boolean(redactLogs),
+    ...(typeof apiToken === "string" && apiToken.length > 0 && { apiToken }),
+  };
+}