Orca OpenClaw Plugin

OpenClaw plugin wrapper for Orca runtime guardrails.

What this plugin does

This plugin adds Orca-native lifecycle hooks to OpenClaw. It lets OpenClaw call the Orca CLI for policy checks, audit logging, and runtime safety decisions without duplicating policy logic.

The plugin is a thin integration layer. The Orca CLI remains the source of truth for all policy decisions.

Prerequisites

• Orca CLI built and available in PATH (run orca doctor to verify)
• OpenClaw host installed

Orca is not bundled into this plugin package. Fast setup:

./scripts/install-orca-plugin.sh openclaw project

Windows:

.\scripts\install-orca-plugin.ps1 openclaw project

Install from local path

If you have OpenClaw installed locally:

openclaw plugins install ./integrations/openclaw-plugin

The strongest local protection remains running OpenClaw through orca run -- openclaw; the OpenClaw plugin provides native guardrails where OpenClaw plugin hooks support them.

Install from npm

After npm publication, install with:

openclaw plugins install npm:orca-openclaw-plugin

If OpenClaw's security scanner blocks the install (the plugin uses child_process to call the orca binary), use:

openclaw plugins install npm:orca-openclaw-plugin --dangerously-force-unsafe-install

If OpenClaw supports bare npm package installs:

openclaw plugins install orca-openclaw-plugin

Important: When installed via npm, OpenClaw currently loads the plugin in cli-metadata mode, which wires api.on to a no-op. This means before_tool_call hooks will not fire and the plugin cannot block destructive commands. For full protection, run OpenClaw through Orca (orca run -- openclaw) or install the plugin as a local path / bundled extension.

Install from ClawHub

The plugin is published to ClawHub as orca-openclaw-plugin.

openclaw plugins install clawhub:orca-openclaw-plugin

If OpenClaw's security scanner blocks the install, use:

openclaw plugins install clawhub:orca-openclaw-plugin --dangerously-force-unsafe-install

Note: The clawhub: install protocol requires a recent OpenClaw version. If your version does not support it, use the local path or npm install methods instead.

For submission details, see docs/integrations/openclaw-clawhub.md.

Verify install

Run the Orca plugin doctor:

orca plugin doctor openclaw

Expected output sections:

• Orca version
• Policy status (present/valid)
• Plugin directories (openclaw: found)
• Host binaries (openclaw: detected or not detected)

Hooks included

The plugin registers lifecycle hooks that call orca hook openclaw <event>:

| Event | When it fires | Behavior | |-------|---------------|----------| | session.start | At the start of an OpenClaw session | Informational (readiness log) | | tool.before | Before OpenClaw invokes a tool | Blocking — Orca can prevent the tool call | | tool.after | After OpenClaw finishes using a tool | Informational (audit only) | | session.end | When the session ends | Informational (audit only) |

OpenClaw does not currently expose dedicated permission lifecycle hooks to this plugin. Permission-like blocking is handled through tool.before before the tool call executes.

How hooks call Orca

Each hook sends a JSON payload to orca hook openclaw <event> via stdin and reads a JSON decision from stdout. The plugin preserves OpenClaw's expected return values. Human-readable logs go to stderr.

Example payload for tool.before:

{
  "version": 1,
  "host": "openclaw",
  "event": "tool.before",
  "payload": {
    "tool": "shell",
    "command": "git status"
  },
  "session_id": "session-uuid",
  "timestamp": "2026-01-01T00:00:00Z"
}

Example response:

{
  "version": 1,
  "decision": "allow",
  "risk": "low",
  "category": "command",
  "reason": "policy_allow",
  "message": "Allowed by policy"
}

If the decision is block, the plugin throws an error that prevents the tool from executing.

Run redteam

orca redteam --ci

Replay sessions

orca replay --session last --verify

Uninstall

Remove the plugin from your OpenClaw configuration:

openclaw plugins uninstall orca

This plugin does not mutate host configuration, so uninstalling is safe.

Known limitations

• npm/global installs: api.on is a no-op in current OpenClaw versions.
  OpenClaw loads npm-installed plugins with registrationMode: "cli-metadata", where api.on is wired to a no-op function. This means before_tool_call and after_tool_call hooks never fire for npm/ClawHub/global installs, so the plugin cannot block destructive tool calls.
  Workaround: For full runtime guardrails, run OpenClaw through Orca:
  orca run -- openclaw
  The plugin will still log a prominent warning when it detects this situation.
  Fix needed in OpenClaw: api.on (or an equivalent typed-hook API) must be exposed for npm plugins with explicit user opt-in.
• Hooks are advisory for informational events; blocking hooks depend on OpenClaw honoring thrown errors.
• The strongest protection remains orca run -- openclaw.
• Plugin installation depends on OpenClaw version and plugin loading mechanism.
• No telemetry is collected.
• npm package support has been prepared for orca-openclaw-plugin.
• ClawHub submission is complete. The plugin is published as [email protected].

Security model

• This plugin calls the Orca CLI; it does not reimplement policy logic.
• No raw secrets are persisted in plugin files.
• Secrets are redacted from payloads before sending to Orca (keys matching password, token, secret, api_key, etc. are replaced with [REDACTED]).
• Hook return values remain valid for OpenClaw parsing.
• Human logs go to stderr.
• CI mode never prompts.
• This plugin does not claim stronger enforcement than OpenClaw hooks support.

No MCP server behavior

The OpenClaw plugin does not add MCP server behavior or drone-specific plugin features.

Strongest protection warning

The Orca OpenClaw plugin adds lifecycle hooks for OpenClaw. For the strongest local protection, run the OpenClaw process itself through Orca with orca run -- openclaw.

OpenClaw Security Scan Notice

OpenClaw's plugin security scanner blocks plugins that use child_process. The Orca plugin legitimately needs this to call the orca CLI binary for policy enforcement.

If installation is blocked, use:

openclaw plugins install npm:orca-openclaw-plugin --dangerously-force-unsafe-install

Or for ClawHub:

openclaw plugins install clawhub:orca-openclaw-plugin --dangerously-force-unsafe-install

This is a known limitation. The plugin is safe — it only calls the local orca binary that you already installed and trust.