cerone-openclaw-plugin

Check OpenClaw tool calls with Cerone before they run.

cerone-openclaw-plugin hooks into OpenClaw's before_tool_call flow and asks Cerone for a runtime decision before a tool executes.

No core patching. It uses the public plugin SDK and OpenClaw's built-in plugin approval flow.

What It Does

This plugin is for teams using OpenClaw with tools that can do real work:

• read or write files
• call internal or external APIs
• perform coding, ops, or support actions
• access repositories or workspace state

Cerone validates the intended tool call and returns a decision:

| Cerone response | OpenClaw action | |---|---| | approved | Allow the tool call | | flagged | Require OpenClaw approval by default | | rejected | Block the tool call | | Timeout / network failure / 5xx | Fail open by default, configurable via networkFailureBehavior | | trial_warning: true | Log a warning | | trial_stoploss: true | Block with Trial limit reached |

That means you can put a real runtime check in front of OpenClaw tool use without changing OpenClaw core.

Install

From npm:

openclaw plugins install cerone-openclaw-plugin

Local source checkout:

npm install
npm run build
openclaw plugins install ./path/to/cerone-openclaw-plugin

Linked local development install:

openclaw plugins install --link ./path/to/cerone-openclaw-plugin

After install, enable the plugin and configure it in openclaw.json.

Fast Mental Model

1. Bootstrap or reuse a Cerone trial / API key.
2. Create or reuse a Cerone agent for this OpenClaw environment.
3. Validate each before_tool_call against Cerone.
4. Allow, flag, or block based on the runtime decision.

If apiKey is omitted and trialMode is auto, the plugin can bootstrap a hosted Cerone trial automatically.

Once The Trial Starts, Do This Next

Do not stop at "trial bootstrapped."

Go immediately to the first value path:

1. Let the plugin create or reuse a Cerone agent for this OpenClaw environment.
2. Trigger one real tool call that flows through before_tool_call.
3. Check whether Cerone returned approved, flagged, or rejected.

If the plugin only starts a hosted trial but never validates a real tool call, you have not actually tested the runtime path yet.

If you do not set agentPurpose and agentCapabilities, the plugin derives a coding-oriented Cerone profile from the first OpenClaw tool call so first-run evaluation is easier. For non-coding workflows or stricter production policy, set those fields explicitly.

OpenClaw Configuration

Plugin runtime config belongs under plugins.entries.<plugin-id>.config. enabled stays on the plugin entry, not inside plugin config.

{
  "plugins": {
    "entries": {
      "cerone-openclaw-plugin": {
        "enabled": true,
        "config": {
          "baseUrl": "https://api.homersemantics.com",
          "timeoutMs": 1000,
          "flaggedBehavior": "requireApproval",
          "networkFailureBehavior": "allow",
          "approvalTimeoutMs": 120000,
          "includeContext": true,
          "includeDerivedPaths": true,
          "trialMode": "auto",
          "autoRegisterAgent": true,
          "persistAgentId": true,
          "agentPurpose": "Read repository files and inspect code inside OpenClaw for software engineering tasks.",
          "agentCapabilities": [
            "file_read",
            "file_write",
            "network_access",
            "api_call"
          ]
        }
      }
    }
  }
}

Config Fields

• apiKey: optional provisioned Cerone key.
• baseUrl: Cerone base URL. Defaults to https://api.homersemantics.com.
• timeoutMs: HTTP timeout for Cerone validation calls.
• flaggedBehavior: requireApproval | allow | block.
• networkFailureBehavior: allow | block.
• approvalTimeoutMs: OpenClaw plugin approval timeout.
• includeContext: include OpenClaw run metadata in action.context.
• includeDerivedPaths: include event.derivedPaths when available.
• trialMode: auto | off.
• autoRegisterAgent: create a Cerone agent automatically when needed.
• persistAgentId: persist trial token and Cerone agent_id.
• agentPurpose: optional. If omitted, the plugin derives a first-run coding-oriented purpose from the tool being called.
• agentCapabilities: optional. If omitted, the plugin derives a minimal first-run capability set from the tool being called and Cerone's current capability mapping.
• agentEnvironment: development | staging | production.
• stateFilePath: optional override for persisted plugin state.

Cerone Request Mapping

The plugin sends requests shaped like:

{
  "agent_id": "agt_...",
  "action": {
    "tool": "file_write",
    "parameters": {},
    "context": {
      "source": "openclaw",
      "sessionKey": "optional",
      "sessionId": "optional",
      "runId": "optional",
      "channelId": "optional",
      "toolCallId": "optional",
      "derivedPaths": [],
      "sdk_name": "cerone-openclaw-plugin",
      "sdk_version": "0.1.4",
      "runtime": "node",
      "integration_id": "openclaw-plugin",
      "client_session_id": "csn_...",
      "auth_session_id": "auth_...",
      "request_sequence": 1,
      "client_intent": "sdk_validate_called"
    }
  },
  "blocking": true,
  "timeout_ms": 1000
}

OpenClaw mapping is:

• approved -> return undefined
• flagged -> return requireApproval by default
• rejected -> return { block: true, blockReason }

Data Handling

This plugin sends tool invocation data to the Cerone API at runtime for validation.

Depending on how your OpenClaw tools are defined, that runtime data may include:

• tool names
• tool parameters
• file paths
• URLs
• prompts or query text
• session or run metadata you choose to include

Do not use this plugin with sensitive or regulated data unless your organization has approved that data flow. Avoid passing secrets or unnecessary sensitive payloads in tool parameters where possible.

See PRIVACY.md for the free-trial data handling policy.

Hosted service terms:

• TERMS_OF_SERVICE.md
• PRIVACY.md

Trial Token

If you want to try Cerone without a provisioned key, the plugin can bootstrap a hosted trial automatically.

You can also get the Cerone Python package separately:

pip install cerone

The current path for this plugin is hosted trial bootstrap, not a local CLI bootstrap requirement.

Notes

• this MVP does not rewrite event.params
• it does not require OpenClaw core changes
• it intentionally uses only before_tool_call
• it does not implement post-tool-call reporting or audit UI
• the plugin forwards stable SDK identity, integration id, auth-session correlation, and per-session request sequencing to help correlate trial bootstrap, agent creation, and validation attempts cleanly

License

See LICENSE for details.