OpenClaw Integration¶

Comprehensive guide for using Preloop as a governance layer with OpenClaw.

Overview¶

OpenClaw is an open-source AI coding agent that runs locally and can execute shell commands, modify files, browse the web, and interact with external services. When combined with Preloop, you get a powerful human-in-the-loop safety layer that:

Intercepts dangerous operations before they execute
Requires approval for shell commands, file writes, and sensitive actions
Provides audit logging for all AI-initiated operations
Enables custom policies tailored to your security requirements

Example Policies

See the OpenClaw Policy Examples for ready-to-use policy configurations.

Why Use Preloop with OpenClaw?¶

OpenClaw is incredibly capable - it can execute shell commands, modify files, browse the web, and interact with external services. This power comes with risk:

Without Preloop	With Preloop
OpenClaw can run any shell command	Dangerous commands require approval
Files can be modified silently	Sensitive paths trigger review
No audit trail	Complete operation history
All-or-nothing access	Granular policy control
Local-only governance	Team-wide policy enforcement

Integration Methods¶

Preloop offers multiple integration patterns depending on your workflow and infrastructure requirements.

Method 1: Preloop as MCP Server¶

Configure OpenClaw to connect to Preloop as an MCP server for policy enforcement. This is the recommended approach for most users.

How it works:

OpenClaw sends tool calls to Preloop via MCP protocol
Preloop evaluates policies against the tool call
If approval is required, Preloop waits for human decision
Approved calls are forwarded to the underlying tool
Results are returned to OpenClaw

Configuration:

Add Preloop as an MCP server in your OpenClaw configuration:

{
  "mcp": {
    "servers": {
      "preloop": {
        "transport": "http",
        "url": "https://preloop.ai/mcp/v1",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Or via the command line:

openclaw mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  preloop \
  https://preloop.ai/mcp/v1

Method 2: Managed OpenClaw Onboarding¶

If you already use OpenClaw locally, the Preloop CLI can detect it and onboard it into a managed configuration.

Validated against a live OpenClaw host, the current default config location is still commonly ~/.openclaw/openclaw.json, and the active model is often selected from agents.defaults.model.primary.

# Discovery that can prompt to onboard interactively
preloop agents discover

# Keep discovery read-only in scripts or CI
preloop agents discover --no-onboard-prompt

# Auto-onboard newly discovered agents without per-agent prompts
preloop agents discover --yes

# Preview the managed enrollment changes
preloop agents enroll openclaw --dry-run

# Apply the managed enrollment
preloop agents enroll openclaw

In managed OpenClaw onboarding, preloop agents discover can offer an interactive OpenClaw enrollment flow. Use --no-onboard-prompt when discovery should stay non-mutating, or --yes when you want discovery to auto-onboard new candidates. The managed enrollment step is equivalent to running preloop agents enroll openclaw.

When the onboarding succeeds, Preloop keeps the local setup intentionally narrow:

It imports the MCP servers currently configured in OpenClaw into your Preloop account when they can be represented there.
It imports the configured OpenClaw model into Preloop and attempts to rewrite OpenClaw to use the Preloop Gateway for model calls.
It rewrites the local OpenClaw MCP config so OpenClaw talks only to the managed preloop MCP server entry, routing governed tool access through the Preloop Tool Firewall.
It saves a backup of the original local OpenClaw config before writing the managed version.

What Managed Onboarding Creates in Preloop¶

Managed onboarding is more than a local config rewrite. It also creates durable control-plane records inside Preloop:

A managed agent record that represents the enrolled OpenClaw installation
A runtime session history that tracks individual active and completed sessions over time
A managed authentication boundary so OpenClaw can use short-lived Preloop-issued runtime access instead of reusing raw provider credentials everywhere
Imported MCP server metadata and an imported or reused AI model record when the local configuration can be represented safely

This distinction matters because one enrolled OpenClaw installation can accumulate multiple runtime sessions over time while still keeping one durable identity for audit history, model usage, and operator controls.

The importer currently handles two common config patterns:

Provider/model details declared directly under models.providers.
Provider auth declared indirectly under auth.profiles, which is common for built-in providers such as Google/Gemini.

When OpenClaw uses auth.profiles instead of an inline apiKey, Preloop can still import the model identity and rewrite the local config, but you may need to configure the upstream provider secret in Preloop separately.

How Governance Applies After Enrollment¶

After OpenClaw is enrolled, Preloop evaluates requests using the same subject-scoped governance model as the rest of the control plane:

Account defaults define the broad fallback for tool visibility and model access
Managed-agent scope can narrow which tools or models this specific OpenClaw runtime may use
API-key scope can narrow behavior further when a more specific token scope is present

In practice, this means an enrolled OpenClaw instance can be limited to a smaller set of MCP tools or allowed models than the rest of the account, even when the parent account has broader access.

Gemini Through the Gateway¶

Gemini models can work through the managed OpenClaw flow only when OpenClaw can be pointed at an OpenAI-compatible provider or base URL. In practice, OpenClaw must let Preloop set the model provider/base URL pair that routes requests through Preloop's OpenAI-compatible gateway.

On the validated live host, the active model was google/gemini-3.1-pro-preview. That shape is supported by the current onboarding logic: Preloop preserves the upstream provider identity as google, creates or reuses a gateway-enabled AI model, and rewrites OpenClaw to target a managed provider alias through the Preloop OpenAI-compatible gateway.

If your OpenClaw build cannot fully express that provider rewrite, managed onboarding can still succeed for MCP governance while leaving some model settings manual.

Fallback Behavior¶

Managed onboarding is designed to fail soft when model rewriting is unsupported or only partially supported:

MCP import and managed MCP enrollment can still complete.
The detected model may still be imported into Preloop if there is enough information to represent it there.
OpenClaw may be left on its existing model/provider settings, or require a manual follow-up edit, until full gateway rewriting is supported.

Treat the managed rewrite as complete only when OpenClaw can be configured to send model traffic to Preloop's OpenAI-compatible base URL.

Restore and Rollback¶

Managed onboarding creates a local backup before changing ~/.openclaw/openclaw.json. To roll back the local enrollment, use:

preloop agents restore openclaw

This restores the backed-up local OpenClaw config. Keep in mind that restore is a local config rollback: it does not promise to delete the managed agent record, durable credential, imported MCP servers, or imported model metadata from Preloop automatically.

Method 3: CLI Policy Sync¶

Use the preloop CLI to sync policies to your OpenClaw configuration. This approach is ideal for teams that want to manage policies centrally.

How it works:

Define policies in YAML files
Use preloop policy apply to upload and activate policies
Policies are applied to all connected MCP clients
Changes propagate automatically to all team members

Configuration:

# Apply a single policy
preloop policy apply examples/policies/openclaw/shell-approval.yaml

# Apply all policies in a directory
preloop policy apply examples/policies/openclaw/

# Preview changes before applying
preloop policy diff examples/policies/openclaw/shell-approval.yaml

Method 4: Webhook Integration¶

Configure OpenClaw to send approval requests to Preloop via webhooks. This is useful for custom integrations or when MCP is not available.

How it works:

OpenClaw calls your middleware service
Middleware forwards approval requests to Preloop API
Preloop sends notifications and waits for approval
Middleware receives approval decision and responds to OpenClaw

Configuration:

# middleware-config.yaml
preloop:
  api_url: "https://preloop.ai/api/v1"
  api_key: "${PRELOOP_API_KEY}"

  webhook:
    endpoint: "/webhooks/approval-result"
    secret: "${WEBHOOK_SECRET}"

Quick Start¶

Get started with Preloop and OpenClaw in under 5 minutes.

Create a free account at https://preloop.ai

2. Install the Preloop CLI¶

# macOS
brew install preloop/tap/preloop

# Linux
curl -fsSL https://preloop.ai/install.sh | sh

# npm (all platforms)
npm install -g @preloop/cli

3. Authenticate¶

preloop auth login

This opens your browser for authentication. After signing in, your CLI is authenticated.

4. Apply an OpenClaw Policy¶

# Apply the shell safety policy
preloop policy apply examples/policies/openclaw/shell-approval.yaml

# Verify the policy is active
preloop policy list

5. Onboard OpenClaw¶

# Discover local agents
preloop agents discover

# Preview the managed changes
preloop agents enroll openclaw --dry-run

# Apply the managed enrollment
preloop agents enroll openclaw

6. Test the Integration¶

# Run OpenClaw with a command that requires approval
openclaw "Delete all log files older than 7 days"

You should receive an approval request on your phone, email, or dashboard. In managed setups, OpenClaw should route MCP calls through the managed preloop MCP entry, and model calls only go through Preloop when the OpenClaw provider/base URL rewrite is supported by your OpenClaw build.

Policy Configuration¶

Shell Command Policies¶

Shell commands are often the most dangerous operations. Configure policies based on your risk tolerance:

Block Destructive Commands¶

tools:
  - name: "exec"
    source: "openclaw"
    conditions:
      - expression: |
          args.command.contains('rm -rf /') ||
          args.command.contains(':(){ :|:& };:') ||
          args.command.contains('dd if=/dev/zero')
        action: "deny"
        message: "Catastrophic commands are blocked"

Approve All Shell Commands (High Security)¶

tools:
  - name: "exec"
    source: "openclaw"
    approval_workflow: "manual-approval"

Approve Only Specific Patterns (Medium Security)¶

tools:
  - name: "exec"
    source: "openclaw"
    conditions:
      # Block sudo entirely
      - expression: "args.command.startsWith('sudo')"
        action: "deny"
        message: "Sudo commands require manual execution"

      # Require approval for package management
      - expression: |
          args.command.contains('npm install') ||
          args.command.contains('pip install') ||
          args.command.contains('apt install')
        approval_workflow: "manual-approval"

      # Require approval for git push
      - expression: "args.command.contains('git push')"
        approval_workflow: "manual-approval"

Browser Safety Policies¶

Control browser automation on sensitive websites:

tools:
  - name: "browser_navigate"
    source: "openclaw"
    conditions:
      # Banking and financial sites
      - expression: |
          args.url.contains('bank') ||
          args.url.contains('paypal.com') ||
          args.url.contains('stripe.com')
        approval_workflow: "manual-approval"

      # Cloud consoles
      - expression: |
          args.url.contains('console.aws.amazon.com') ||
          args.url.contains('portal.azure.com') ||
          args.url.contains('console.cloud.google.com')
        approval_workflow: "manual-approval"

      # Admin interfaces
      - expression: "args.url.contains('/admin') || args.url.contains('/settings')"
        approval_workflow: "manual-approval"

File Protection Policies¶

Protect sensitive files from modification:

tools:
  - name: "write_file"
    source: "openclaw"
    conditions:
      # Block credential files
      - expression: |
          args.path.endsWith('.env') ||
          args.path.contains('credentials') ||
          args.path.contains('secrets')
        action: "deny"
        message: "Credential files cannot be modified by AI"

      # Approve system config changes
      - expression: |
          args.path.startsWith('/etc/') ||
          args.path.contains('/.ssh/') ||
          args.path.contains('/.aws/')
        approval_workflow: "manual-approval"

CEL Condition Reference¶

Preloop uses Common Expression Language (CEL) for policy conditions. Here are common patterns for OpenClaw tools:

String Matching¶

# Exact match
args.command == "rm -rf /"

# Contains substring
args.command.contains("sudo")

# Starts with
args.path.startsWith("/etc/")

# Ends with
args.path.endsWith(".env")

# Regex match (via matches function)
args.command.matches("^rm\\s+-rf\\s+")

Logical Operators¶

# AND
args.command.contains("rm") && args.command.contains("-rf")

# OR
args.command.contains("sudo") || args.command.contains("doas")

# NOT
!args.path.startsWith("/tmp/")

List Operations¶

# Check if command starts with any dangerous prefix
["sudo", "su", "doas"].exists(p, args.command.startsWith(p))

# Check if path contains any sensitive directory
["/.ssh/", "/.aws/", "/.gnupg/"].exists(d, args.path.contains(d))

Context Variables¶

# User context
context.user.email == "admin@company.com"
context.user.role == "developer"

# Time-based conditions
now.hour >= 9 && now.hour < 17  # Business hours only

# Environment
context.environment == "production"

Workflow Examples¶

Code Review with Approval¶

Use OpenClaw to review PRs while requiring approval for any modifications:

$ openclaw "Review PR #123 for security issues and add comments"

OpenClaw: I found 3 security issues in this PR. I'll add review comments.

Tool call: add_pr_comment(...)

⏳ Waiting for approval...
   Approval request sent to your email and dashboard.

[You approve via email, mobile, or dashboard]

✓ Approval received!
✓ Comments added to PR #123

Database Migration with Approval¶

$ openclaw "Generate and run Alembic migration for the new User model"

OpenClaw: I'll generate the migration and run it.

Tool call: exec(command="alembic revision --autogenerate -m 'add_user_table'")
✓ Generated migration file

Tool call: exec(command="alembic upgrade head")
⏳ Waiting for approval...
   Migration detected - requires human review.

[You review the migration and approve]

✓ Migration applied successfully

Deployment with Safeguards¶

Configure policies to require approval for deployment operations:

tools:
  - name: "exec"
    source: "openclaw"
    conditions:
      - expression: |
          args.command.contains('deploy') ||
          args.command.contains('kubectl apply') ||
          args.command.contains('docker push') ||
          args.command.contains('terraform apply')
        approval_workflow: "deployment-approval"
        timeout_seconds: 1800  # 30 min timeout for deploy reviews

Enterprise Configuration¶

Team-Based Approvals¶

Configure different approval requirements based on team or role:

approval_workflows:
  - name: "production-deploy"
    description: "Requires senior engineer approval"
    approvers:
      - role: "senior-engineer"
      - role: "tech-lead"
    required_approvals: 1

  - name: "infrastructure-change"
    description: "Requires ops team approval"
    approvers:
      - team: "platform-ops"
    required_approvals: 2

Audit Logging¶

All OpenClaw operations through Preloop are logged:

{
  "timestamp": "2025-01-27T10:23:45Z",
  "user": "alice@company.com",
  "agent": "openclaw",
  "tool": "exec",
  "arguments": {
    "command": "rm -rf /tmp/cache/*"
  },
  "approval_status": "approved",
  "approver": "bob@company.com",
  "execution_result": "success"
}

Access audit logs via: - Dashboard: Settings → Audit Logs - API: GET /api/v1/audit/logs - Export: CSV, JSON, or SIEM integration

SSO Integration¶

For enterprise deployments, configure SSO for seamless authentication:

Set up SAML/OIDC in Preloop admin
Map OpenClaw users to Preloop accounts
Apply policies based on identity provider groups

Best Practices¶

1. Start Permissive, Then Tighten¶

Begin with approval requirements for obviously dangerous operations, then expand based on observed patterns:

# Phase 1: Block only the most dangerous
- expression: "args.command.contains('rm -rf /')"
  action: "deny"

# Phase 2: Add approval for destructive operations
- expression: "args.command.contains('rm -rf')"
  approval_workflow: "manual-approval"

# Phase 3: Require approval for all shell commands
approval_workflow: "manual-approval"

2. Use Descriptive Denial Messages¶

When blocking operations, explain why:

conditions:
  - expression: "args.command.startsWith('sudo')"
    action: "deny"
    message: |
      Sudo commands are blocked for AI agents.
      Please execute this command manually:
      {{ args.command }}

3. Set Appropriate Timeouts¶

Long-running operations need longer approval windows:

approval_workflows:
  - name: "quick-approval"
    timeout_seconds: 300  # 5 minutes for simple operations

  - name: "deployment-approval"
    timeout_seconds: 3600  # 1 hour for complex deployments

4. Enable Mobile Notifications¶

For time-sensitive approvals, enable push notifications:

Install the Preloop mobile app
Enable notifications for OpenClaw approvals
Approve from your phone, watch, or tablet

5. Review Audit Logs Regularly¶

Monitor OpenClaw's behavior to: - Identify patterns that need new policies - Detect unusual or suspicious activity - Optimize approval workflows

Troubleshooting¶

Connection Issues¶

MCP server not responding:

# Test connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://preloop.ai/mcp/v1/health

# Check OpenClaw MCP status
openclaw mcp list

Authentication failures:

Verify API key is valid and not expired
Check key has appropriate scopes
Ensure no extra whitespace in key
Try regenerating the API key

Managed enrollment succeeded, but model traffic still bypasses Preloop:

Verify that the imported AI model in Preloop has gateway routing enabled
Confirm the rewritten OpenClaw provider/base URL settings point at Preloop's OpenAI-compatible gateway
If the original OpenClaw config used auth.profiles, make sure the upstream provider secret was also configured in Preloop when required
Treat MCP governance as active even if model rewrite still needs manual follow-up

Approval Timeouts¶

Approvals expiring before you can respond:

Increase timeout in policy configuration
Enable push notifications
Check email spam folders for approval requests

Approvals not appearing:

Verify you're in the approvers list
Check tool matches policy conditions
Review audit logs for routing issues

Policy Not Triggering¶

Operations bypassing policies:

Verify policy is enabled
Check condition expressions match the tool arguments
Test with more specific conditions
Review policy evaluation order (first match wins)

Testing policies:

# Test policy evaluation without executing
preloop policy test \
  --tool "exec" \
  --args '{"command": "sudo rm -rf /"}' \
  shell-approval.yaml

CLI Issues¶

preloop command not found:

# Verify installation
which preloop

# Reinstall if needed
npm install -g @preloop/cli

# Or via brew
brew reinstall preloop/tap/preloop

Authentication expired:

# Re-authenticate
preloop auth logout
preloop auth login

The agent appears in Preloop, but no session activity is visible yet:

Start a fresh OpenClaw session and trigger at least one MCP or model action
Check the Agents and Runtime Sessions views in the console for recent activity
If model calls were expected, verify the runtime is using the managed gateway path rather than a direct provider path

Security Considerations¶

API Key Management¶

Generate separate API keys for each developer
Rotate keys regularly (monthly recommended)
Never commit keys to version control
Use environment variables: PRELOOP_API_KEY

For managed onboarding, prefer the enrolled runtime path where possible so OpenClaw can use Preloop-managed runtime access and subject-scoped governance instead of sharing one long-lived provider credential across every local installation.

Network Security¶

For enterprise deployments: - Use private endpoints where possible - Configure IP allowlists - Enable mTLS for MCP connections - Monitor for unusual traffic patterns

Data Privacy¶

Preloop processes tool call data for policy evaluation: - Command text and file paths are evaluated - Configure data retention policies - Use on-premise deployment for sensitive environments - Enable end-to-end encryption for approvals

OpenClaw Policy Examples - Ready-to-use policy files
CEL Expression Reference - Complete CEL documentation
Approval Workflows - Configure team approvals
Mobile Apps - Approve on the go

OpenClaw Integration¶

Overview¶

Why Use Preloop with OpenClaw?¶

Integration Methods¶

Method 1: Preloop as MCP Server¶

Method 2: Managed OpenClaw Onboarding¶

What Managed Onboarding Creates in Preloop¶

How Governance Applies After Enrollment¶

Gemini Through the Gateway¶

Fallback Behavior¶

Restore and Rollback¶

Method 3: CLI Policy Sync¶

Method 4: Webhook Integration¶

Quick Start¶

1. Sign Up for Preloop¶

2. Install the Preloop CLI¶

3. Authenticate¶

4. Apply an OpenClaw Policy¶

5. Onboard OpenClaw¶

6. Test the Integration¶

Policy Configuration¶

Shell Command Policies¶

Block Destructive Commands¶

Approve All Shell Commands (High Security)¶

Approve Only Specific Patterns (Medium Security)¶

Browser Safety Policies¶

File Protection Policies¶

CEL Condition Reference¶

String Matching¶

Logical Operators¶

List Operations¶

Context Variables¶

Workflow Examples¶

Code Review with Approval¶

Database Migration with Approval¶

Deployment with Safeguards¶

Enterprise Configuration¶

Team-Based Approvals¶

Audit Logging¶

SSO Integration¶

Best Practices¶

1. Start Permissive, Then Tighten¶

2. Use Descriptive Denial Messages¶

3. Set Appropriate Timeouts¶

4. Enable Mobile Notifications¶

5. Review Audit Logs Regularly¶

Troubleshooting¶

Connection Issues¶

Approval Timeouts¶

Policy Not Triggering¶

CLI Issues¶

Security Considerations¶

API Key Management¶

Network Security¶

Data Privacy¶

Related Resources¶