Skip to content

Commit 0adb899

Browse files
dbhurleydbhurley
committed
feat: add OpenClaw integration guide
- Create /integrations/openclaw.md with full extension documentation - Add OpenClaw to sidebar navigation - Fixes broken link from meshguard-openclaw npm package
1 parent 087e467 commit 0adb899

2 files changed

Lines changed: 338 additions & 0 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ export default defineConfig({
7171
{ text: 'LangChain', link: '/integrations/langchain' },
7272
{ text: 'CrewAI', link: '/integrations/crewai' },
7373
{ text: 'AutoGPT', link: '/integrations/autogpt' },
74+
{ text: 'OpenClaw', link: '/integrations/openclaw' },
7475
{ text: 'Clawdbot', link: '/integrations/clawdbot' },
7576
{ text: 'Claude Code', link: '/integrations/claude-code' },
7677
{ text: 'OpenAI Agents', link: '/integrations/openai-agents' },

‎docs/integrations/openclaw.md‎

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
---
2+
title: "OpenClaw Integration"
3+
description: "Integrate MeshGuard governance with OpenClaw AI agents using the official extension"
4+
---
5+
6+
# OpenClaw Integration
7+
8+
Integrate MeshGuard's governance control plane with [OpenClaw](https://openclaw.ai) agents using the official `meshguard-openclaw` extension. Enforce policies on every tool invocation with zero code changes.
9+
10+
::: tip OpenClaw = Clawdbot
11+
OpenClaw is the open-source rebrand of Clawdbot. Existing Clawdbot users can continue using the [Clawdbot integration guide](/integrations/clawdbot) — the SDK-based approach works for both.
12+
:::
13+
14+
## Installation
15+
16+
Install the official MeshGuard extension for OpenClaw:
17+
18+
```bash
19+
# npm
20+
npm install meshguard-openclaw
21+
22+
# pnpm
23+
pnpm add meshguard-openclaw
24+
25+
# Or via OpenClaw CLI
26+
openclaw plugins install meshguard-openclaw
27+
```
28+
29+
## Quick Start
30+
31+
### 1. Get MeshGuard Credentials
32+
33+
Sign up at [meshguard.app](https://meshguard.app) and create an agent to get:
34+
- **API Key** (`msk_xxx`)
35+
- **Agent ID** (`agent_xxx`)
36+
37+
### 2. Configure OpenClaw
38+
39+
Add to your `openclaw.json`:
40+
41+
```json
42+
{
43+
"plugins": ["meshguard-openclaw"],
44+
"meshguard": {
45+
"apiKey": "${MESHGUARD_API_KEY}",
46+
"agentId": "agent_xxx",
47+
"mode": "enforce"
48+
}
49+
}
50+
```
51+
52+
Or use environment variables:
53+
54+
```bash
55+
export MESHGUARD_API_KEY=msk_xxx
56+
export MESHGUARD_AGENT_ID=agent_xxx
57+
```
58+
59+
### 3. Define Policies
60+
61+
Create policies in the MeshGuard dashboard or via YAML:
62+
63+
```yaml
64+
name: openclaw-agent-policy
65+
version: "1.0"
66+
appliesTo:
67+
agentIds:
68+
- agent_xxx
69+
rules:
70+
- effect: allow
71+
actions:
72+
- "tool:read"
73+
- "tool:web_search"
74+
- "tool:web_fetch"
75+
description: Allow read operations
76+
77+
- effect: deny
78+
actions:
79+
- "tool:exec"
80+
conditions:
81+
command_pattern: "rm -rf /*"
82+
description: Block destructive commands
83+
alert: critical
84+
85+
- effect: allow
86+
actions:
87+
- "tool:*"
88+
description: Allow all other tools
89+
```
90+
91+
### 4. Run Your Agent
92+
93+
That's it! MeshGuard now:
94+
- Evaluates policies before each tool call
95+
- Blocks actions that violate policies (in enforce mode)
96+
- Logs all actions to the audit trail
97+
- Sends alerts for policy violations
98+
99+
## Configuration Options
100+
101+
| Option | Type | Default | Description |
102+
|--------|------|---------|-------------|
103+
| `enabled` | boolean | `true` | Enable/disable governance |
104+
| `apiKey` | string | required | MeshGuard API key |
105+
| `agentId` | string | required | MeshGuard agent ID |
106+
| `gatewayUrl` | string | `https://dashboard.meshguard.app` | MeshGuard gateway URL |
107+
| `mode` | string | `"enforce"` | `enforce`, `audit`, or `bypass` |
108+
| `auditLevel` | string | `"standard"` | `minimal`, `standard`, or `verbose` |
109+
| `cacheTimeoutMs` | number | `60000` | Policy cache duration (ms) |
110+
| `failOpen` | boolean | `false` | Allow actions if MeshGuard is unreachable |
111+
112+
## Governance Modes
113+
114+
| Mode | Behavior |
115+
|------|----------|
116+
| **enforce** | Block policy violations, log all actions |
117+
| **audit** | Log all actions, but don't block violations (shadow mode) |
118+
| **bypass** | Disable governance entirely |
119+
120+
::: warning Production Recommendation
121+
Always start with `audit` mode to validate your policies before switching to `enforce`.
122+
:::
123+
124+
## How It Works
125+
126+
```
127+
┌─────────────────────────────────────────────────────────────┐
128+
│ OpenClaw Agent │
129+
│ ┌─────────────────────────────────────────────────────────┐│
130+
│ │ Tool Invocation ││
131+
│ └────────────────────────┬────────────────────────────────┘│
132+
│ ▼ │
133+
│ ┌─────────────────────────────────────────────────────────┐│
134+
│ │ before_tool_call hook ││
135+
│ │ ┌─────────────────────────────┐ ││
136+
│ │ │ MeshGuard Extension │ ││
137+
│ │ │ - Evaluate policy │ ││
138+
│ │ │ - Check cache │ ││
139+
│ │ │ - Block if denied │ ││
140+
│ │ └─────────────────────────────┘ ││
141+
│ └────────────────────────┬────────────────────────────────┘│
142+
│ ▼ │
143+
│ ┌─────────────────────────────────────────────────────────┐│
144+
│ │ Tool Execution (if allowed) ││
145+
│ └────────────────────────┬────────────────────────────────┘│
146+
│ ▼ │
147+
│ ┌─────────────────────────────────────────────────────────┐│
148+
│ │ after_tool_call hook ││
149+
│ │ ┌─────────────────────────────┐ ││
150+
│ │ │ MeshGuard Extension │ ││
151+
│ │ │ - Log to audit trail │ ││
152+
│ │ │ - Record duration │ ││
153+
│ │ │ - Capture result/error │ ││
154+
│ │ └─────────────────────────────┘ ││
155+
│ └─────────────────────────────────────────────────────────┘│
156+
└─────────────────────────────────────────────────────────────┘
157+
│
158+
▼
159+
┌─────────────────────────────────────────────────────────────┐
160+
│ MeshGuard Cloud │
161+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
162+
│ │ Policy │ │ Audit │ │ Dashboard │ │
163+
│ │ Engine │ │ Store │ │ UI │ │
164+
│ └─────────────┘ └─────────────┘ └─────────────┘ │
165+
└─────────────────────────────────────────────────────────────┘
166+
```
167+
168+
## Tool Action Mapping
169+
170+
OpenClaw tools are mapped to MeshGuard actions:
171+
172+
| OpenClaw Tool | MeshGuard Action |
173+
|---------------|------------------|
174+
| `exec` | `tool:exec` |
175+
| `read` / `write` | `tool:read`, `tool:write` |
176+
| `web_search` | `tool:web_search` |
177+
| `web_fetch` | `tool:web_fetch` |
178+
| `browser` | `tool:browser` |
179+
| `message` | `tool:message` |
180+
| Custom tools | `tool:<name>` |
181+
182+
## Policy Examples
183+
184+
### Restrict Shell Commands
185+
186+
```yaml
187+
name: shell-governance
188+
rules:
189+
- effect: deny
190+
actions: ["tool:exec"]
191+
conditions:
192+
command_pattern: "rm -rf *"
193+
reason: "Destructive commands blocked"
194+
alert: critical
195+
196+
- effect: deny
197+
actions: ["tool:exec"]
198+
conditions:
199+
command_contains:
200+
- "sudo"
201+
- "chmod 777"
202+
reason: "Privileged commands require approval"
203+
```
204+
205+
### Limit External Communication
206+
207+
```yaml
208+
name: comms-governance
209+
rules:
210+
- effect: allow
211+
actions: ["tool:message"]
212+
conditions:
213+
channel:
214+
in: ["slack", "telegram"]
215+
216+
- effect: deny
217+
actions: ["tool:message"]
218+
reason: "Messaging to other channels requires approval"
219+
```
220+
221+
### Restrict File Access
222+
223+
```yaml
224+
name: file-governance
225+
rules:
226+
- effect: allow
227+
actions: ["tool:read"]
228+
conditions:
229+
path_pattern: "/workspace/*"
230+
231+
- effect: deny
232+
actions: ["tool:write"]
233+
conditions:
234+
path_pattern: "/etc/*"
235+
reason: "System file modification blocked"
236+
```
237+
238+
## Audit Trail
239+
240+
Every tool invocation is logged to MeshGuard's audit trail:
241+
242+
```bash
243+
# View recent audit entries
244+
meshguard audit tail -n 20
245+
246+
# Filter by agent
247+
meshguard audit query --agent my-openclaw-agent
248+
249+
# Export for compliance
250+
meshguard audit export --from 2026-01-01 --format csv
251+
```
252+
253+
### Audit Entry Structure
254+
255+
```json
256+
{
257+
"timestamp": "2026-02-05T12:30:00Z",
258+
"agentId": "agent_xxx",
259+
"agentName": "my-openclaw-agent",
260+
"action": "tool:exec",
261+
"resource": "ls -la /workspace",
262+
"decision": "allow",
263+
"durationMs": 142,
264+
"traceId": "trace_abc123",
265+
"metadata": {
266+
"tool": "exec",
267+
"exitCode": 0
268+
}
269+
}
270+
```
271+
272+
## Alerting
273+
274+
Configure alerts for policy violations:
275+
276+
```json
277+
{
278+
"meshguard": {
279+
"alerting": {
280+
"webhook": {
281+
"url": "https://your-server.com/alerts",
282+
"events": ["deny", "anomaly"]
283+
},
284+
"email": {
285+
"to": ["security@yourcompany.com"],
286+
"events": ["critical"]
287+
}
288+
}
289+
}
290+
}
291+
```
292+
293+
## Security Considerations
294+
295+
- **Sensitive data redaction**: Passwords, tokens, and API keys are automatically redacted from audit logs
296+
- **Local caching**: Policies are cached locally to minimize latency
297+
- **Fail-safe defaults**: Actions are blocked if MeshGuard is unreachable (`failOpen: false`)
298+
299+
## Troubleshooting
300+
301+
### Extension Not Loading
302+
303+
```bash
304+
# Verify installation
305+
npm list meshguard-openclaw
306+
307+
# Check OpenClaw recognizes it
308+
openclaw plugins list
309+
```
310+
311+
### Policy Denials
312+
313+
```bash
314+
# Test policy evaluation
315+
meshguard policy test <agent-id> tool:exec --resource "ls -la"
316+
317+
# Check audit log for details
318+
meshguard audit query --agent <name> --decision deny
319+
```
320+
321+
### Connection Issues
322+
323+
```bash
324+
# Test gateway connectivity
325+
curl https://dashboard.meshguard.app/health
326+
327+
# Verify API key
328+
meshguard agent list
329+
```
330+
331+
## Related
332+
333+
- [Clawdbot Integration](/integrations/clawdbot) — SDK-based integration (works for OpenClaw too)
334+
- [Policies](/guide/policies) — Policy format and syntax
335+
- [Audit Logging](/guide/audit) — Audit log configuration
336+
- [Alerting](/guide/alerting) — Alert rules and notifications
337+
- [API Reference](/api/overview) — Full API documentation

0 commit comments

Comments
 (0)