> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafter.so/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Integration

> Set up Rafter security for OpenClaw

# OpenClaw Integration

Rafter integrates seamlessly with [OpenClaw](https://openclaw.com) to add local security to your development workflow.

## Setup

### 1. Install Rafter CLI

Install globally:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @rafter-security/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @rafter-security/cli
  ```
</CodeGroup>

### 2. Initialize Local Security

Run initialization (auto-detects OpenClaw):

```bash theme={null}
rafter agent init
```

If OpenClaw is detected, Rafter will:

* ✓ Install skill to `~/.openclaw/workspace/skills/rafter-security/SKILL.md` (the canonical ClawHub path; was `~/.openclaw/skills/rafter-security.md` in v0.7.7 and earlier — reinstall on top of the old layout strips the legacy file)
* ✓ Write ClawHub-required top-level frontmatter (`name`, `description`, `version`) alongside the `openclaw:` runtime block
* ✓ Enable agent integration in config
* ✓ Set up security policies

<Note>**Alternative install:** since v0.8.0, the rafter-security skill is also auto-published to [ClawHub](https://clawhub.ai) on every prod release. OpenClaw users can install via `clawhub skill install rafter-security` as an alternative to `rafter agent init --with-openclaw`.</Note>

### 3. Restart OpenClaw

Restart OpenClaw to load the Rafter skill:

```bash theme={null}
# Stop OpenClaw
openclaw stop

# Start OpenClaw
openclaw start
```

## How It Works

Once integrated, OpenClaw uses Rafter for security-sensitive operations:

```
User → OpenClaw → Rafter Security → Safe Execution
```

### Example Flow

**User request:**

```
"Commit these changes to git"
```

**OpenClaw processes:**

1. Generates commit message
2. Calls Rafter: `rafter agent exec "git commit -m '...'"`
3. Rafter evaluates command risk level
4. Rafter scans staged files for secrets (for git commands)
5. If clean: Executes commit
6. If secrets found or command blocked: Alerts user

## Skill Commands

The Rafter skill provides these commands to OpenClaw:

### `/rafter-scan`

Scan files for secrets before operations.

**When OpenClaw uses it:**

* Before git commits
* When reading sensitive files
* After generating code with credentials

**Example:**

```
User: "Is there anything sensitive in this codebase?"
OpenClaw: rafter secrets .
```

> **Note:** `rafter agent scan` still works but is deprecated — it will be removed in a future major version.

### `/rafter-bash`

Execute shell commands with validation.

**When OpenClaw uses it:**

* For any shell command execution
* Before destructive operations
* When using sudo

**Example:**

```
User: "Install the dependencies"
OpenClaw: rafter agent exec "npm install"
```

### `/rafter-audit`

View security event logs.

**When OpenClaw uses it:**

* After blocked commands
* When reviewing security events
* For compliance reporting

**Example:**

```
User: "Show me recent security events"
OpenClaw: rafter agent audit --last 10
```

## Configuration

### Risk Levels for OpenClaw

Choose based on your use case:

<AccordionGroup>
  <Accordion title="Minimal (Development)" icon="shield-check">
    Best for: Local development, prototyping

    ```bash theme={null}
    rafter agent config set agent.riskLevel minimal
    ```

    * Allows most commands
    * Basic secret detection
    * Minimal interruption to workflow
  </Accordion>

  <Accordion title="Moderate (Recommended)" icon="shield">
    Best for: General use, team environments

    ```bash theme={null}
    rafter agent config set agent.riskLevel moderate
    ```

    * Blocks critical commands
    * Requires approval for high-risk operations
    * Secret scanning on all git operations
    * **Default setting**
  </Accordion>

  <Accordion title="Aggressive (Production)" icon="shield-halved">
    Best for: Sensitive environments, compliance requirements

    ```bash theme={null}
    rafter agent config set agent.riskLevel aggressive
    ```

    * Maximum security checks
    * Requires approval for most operations
    * Comprehensive audit logging
    * Best for production agents
  </Accordion>
</AccordionGroup>

### Command Policy

Control how commands are handled:

```bash theme={null}
# Default: Approve dangerous commands
rafter agent config set agent.commandPolicy.mode approve-dangerous

# Alternative: Block specific patterns only
rafter agent config set agent.commandPolicy.mode deny-list

# Permissive: Allow all (not recommended)
rafter agent config set agent.commandPolicy.mode allow-all
```

## Usage Examples

### Safe Development Workflow

```
User: "Create a new feature for user authentication"

OpenClaw:
1. Generates code
2. Runs rafter secrets  # Check for secrets
3. If clean, proceeds
4. Creates git commit with rafter agent exec
5. Scans staged files again
6. Commits successfully
```

### Blocked Dangerous Operation

```
User: "Clean up all files in the project"

OpenClaw generates: rm -rf /

Rafter:
🚫 Command BLOCKED
Risk Level: CRITICAL
Reason: Matches blocked pattern: rm -rf /

OpenClaw: "This command is too dangerous. Please specify which files to delete."
```

### Approval Required

```
User: "Force push to main branch"

OpenClaw generates: git push --force origin main

Rafter:
⚠️  Command requires approval
Risk Level: HIGH
Approve this command? (yes/no):

User: no

OpenClaw: "Command cancelled. Would you like to push normally instead?"
```

## Best Practices

<Card title="Recommended Setup" icon="list-check">
  1. **Start with moderate risk level**: Adjust based on experience
  2. **Review audit logs daily**: `rafter agent audit --last 20`
  3. **Train agents on Rafter commands**: Ensure agents know when to use security checks
  4. **Test policies in development**: Before deploying to production
  5. **Keep Rafter updated**: `npm update -g @rafter-security/cli`
</Card>

## Monitoring

### View Agent Activity

Check what your agent is doing:

```bash theme={null}
# Recent command executions
rafter agent audit --event command_intercepted

# Secret detections
rafter agent audit --event secret_detected

# Filter by agent
rafter agent audit --agent openclaw --last 50
```

### Audit Reports

Generate reports for compliance:

```bash theme={null}
# Export last 7 days as JSON
rafter agent audit --since $(date -v-7d +%Y-%m-%d) --json > agent-audit.json
```

## Troubleshooting

### Skill Not Loading

If OpenClaw doesn't recognize Rafter commands:

1. **Check skill file exists:**
   ```bash theme={null}
   ls ~/.openclaw/workspace/skills/rafter-security/SKILL.md
   ```
   (Pre-0.8.0 layout was `~/.openclaw/skills/rafter-security.md` — that path is no longer read by ClawHub at runtime.)

2. **Reinstall skill:**
   ```bash theme={null}
   rafter agent init --force
   ```

3. **Restart OpenClaw:**
   ```bash theme={null}
   openclaw restart
   ```

### Commands Not Being Validated

If commands bypass Rafter:

1. **Check config:**
   ```bash theme={null}
   rafter agent config get agent.environments.openclaw.enabled
   # Should be: true
   ```

2. **Verify policy mode:**
   ```bash theme={null}
   rafter agent config get agent.commandPolicy.mode
   ```

3. **Enable if disabled:**
   ```bash theme={null}
   rafter agent config set agent.environments.openclaw.enabled true
   ```

### False Positives

If safe commands are being blocked:

1. **Check audit log:**
   ```bash theme={null}
   rafter agent audit --last 5
   ```

2. **Adjust risk level:**
   ```bash theme={null}
   rafter agent config set agent.riskLevel minimal
   ```

3. **Report issue:** [rafter-cli/issues](https://github.com/raftersecurity/rafter-cli/issues)

## Advanced Configuration

### Custom Blocked Patterns

Add organization-specific patterns:

Edit `~/.rafter/config.json`:

```json theme={null}
{
  "agent": {
    "commandPolicy": {
      "blockedPatterns": [
        "rm -rf /",
        "kubectl delete namespace production",
        "terraform destroy"
      ]
    }
  }
}
```

### Approval Patterns

Require approval for specific commands:

```json theme={null}
{
  "agent": {
    "commandPolicy": {
      "requireApproval": [
        "git push --force",
        "npm publish",
        "docker push.*production"
      ]
    }
  }
}
```

## Multi-Agent Setup

Running multiple OpenClaw instances:

```bash theme={null}
# Each agent gets same config by default
# Customize per-agent if needed:

# Agent 1 (aggressive)
export RAFTER_RISK_LEVEL=aggressive
openclaw start --name agent1

# Agent 2 (moderate)
export RAFTER_RISK_LEVEL=moderate
openclaw start --name agent2
```

## Support

<Card title="Need Help?" icon="question">
  * Documentation: [docs.rafter.so](https://docs.rafter.so)
  * OpenClaw Docs: [openclaw.com/docs](https://openclaw.com/docs)
  * Issues: [rafter-cli/issues](https://github.com/raftersecurity/rafter-cli/issues)
  * Community: [OpenClaw Discord](https://openclaw.com/discord)
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="book" href="/guides/agent-security/reference">
    Complete CLI command reference
  </Card>

  <Card title="Secret Scanning" icon="key" href="/guides/agent-security/secret-scanning">
    Learn about secret detection
  </Card>
</CardGroup>