openclaw.plugin.json

{
  "id": "agent-permissions",
  "name": "Agent Permissions",
  "description": "Permission and approval engine for OpenClaw agents. Reads rules from openclaw.json (allow/deny/ask arrays with wildcard support) and gates ANY tool call generically — built-in tools (bash, file edit, etc.) and tools registered by other plugins, with no inter-plugin coupling required. Consumer plugins can optionally register resolvers for richer prompts. In-chat approval via OpenClaw's native requireApproval. No network calls.",
  "version": "0.4.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "defaultMode": {
        "type": "string",
        "enum": ["default", "acceptEdits", "bypassPermissions", "dontAsk", "strict"],
        "default": "default",
        "description": "Global session disposition. 'default' = operator-opt-in (tools pass through unless an ask/deny rule matches). 'strict' = ask on anything not explicitly allowed (Claude-Code style). 'bypassPermissions'/'dontAsk' = allow everything (deny rules still respected)."
      },
      "allow": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Rule strings in the form 'ToolName' or 'ToolName(content)'. Content supports exact match, legacy prefix 'foo:*', and wildcard 'foo *'."
      },
      "deny": {
        "type": "array",
        "items": { "type": "string" }
      },
      "ask": {
        "type": "array",
        "items": { "type": "string" }
      },
      "dangerousPatterns": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Prefixes that may match allow rules but can never be allow-always-persisted. Defaults to the built-in list (python/node/eval/curl/wget/ssh/sudo/…). Override here to extend or replace."
      },
      "paramKeys": {
        "type": "object",
        "additionalProperties": { "type": "string" },
        "description": "Per-tool param-extraction map: { toolName: paramName }. When a tool call fires, if paramKeys[toolName] is set, the engine reads params[paramName] as the rule content for matching. Lets wildcard rules like 'clawnify_action(GMAIL_EMAIL_*)' match without the consumer plugin needing to register a resolver. Falls back to built-in extraction (shell command for bash/exec) or tool-wide matching when no entry exists."
      },
      "userRulesPath": {
        "type": "string",
        "description": "Defaults to ~/.openclaw/permissions.json. Persisted user-scope allow-always rules live here."
      },
      "localRulesPath": {
        "type": "string",
        "description": "Defaults to .openclaw/permissions.json in CWD. Persisted workspace-scope allow-always rules live here."
      },
      "approvalTimeoutMs": {
        "type": "number",
        "default": 540000,
        "description": "How long to wait for an in-chat approval response (ms). Capped by the gateway."
      }
    }
  }
}