ClawShield Installation Guide

Complete step-by-step guide for setting up ClawShield + OpenClaw from scratch.

Prerequisites

The setup wizard checks these automatically (Step 0), but here's what you need and where to get each one.

1. Git

What: Version control. Needed if installing OpenClaw from the SleuthCo fork.

Platform	Install
Windows	`winget install Git.Git`
Linux	`sudo apt install -y git`
macOS	`brew install git`

Download: https://git-scm.com/downloads

2. Node.js (v22+)

What: JavaScript runtime. OpenClaw is a Node.js application.

Platform	Install
Windows	`winget install OpenJS.NodeJS.LTS`
Linux	`sudo apt install -y nodejs` (or use nvm)
macOS	`brew install node@22`

Download: https://nodejs.org/en/download/

Verify: node --version should show v22.x.x or higher.

npm ships with Node.js — no separate install needed.

3. pnpm

What: Fast package manager. Required for building OpenClaw from source (fork install).

Platform	Install
All	`npm install -g pnpm`

Verify: pnpm --version

4. Go (v1.24+)

What: Go compiler. ClawShield proxy and audit binaries are written in Go.

Platform	Install
Windows	`winget install GoLang.Go`
Linux	`sudo apt install -y golang` (or download from go.dev)
macOS	`brew install go`

Download: https://go.dev/dl/

Verify: go version should show go1.24.x or higher.

5. GCC (C compiler)

What: C compiler. Required by CGO for SQLite support in the audit database.

Platform	Install
Windows	`winget install BrechtSanders.WinLibs.POSIX.UCRT`
Linux	`sudo apt install -y build-essential`
macOS	`xcode-select --install`

Download (Windows): https://winlibs.com/

Windows note: After WinLibs installs via winget, gcc.exe may not be in PATH. The wizard scans common WinGet package locations automatically. If it still can't find GCC, add the mingw64/bin/ directory to your PATH manually.

Verify: gcc --version

Required Information

The wizard asks for these in Steps 1-7. Gather them beforehand to avoid interruptions.

Step 1: Your Information

Field	Example	Where to get it
Display name	`Your Name`	Your name as you want it to appear in agent interactions
Email	`you@example.com`	Your email address

Step 2: Installation Directories

Field	Default (Windows)	Default (Linux)
OpenClaw config dir	`~/.openclaw`	`~/.openclaw`
ClawShield data dir	`~/.clawshield`	`/etc/clawshield`

If installing from the SleuthCo fork, you'll also need:

Fork path: Local clone of https://github.com/SleuthCo/openclaw (default: ~/openclaw)

Step 3: Anthropic API Key

What: API key for Claude models. This is the only required secret.

How to get it:

Go to https://console.anthropic.com/
Sign in or create an account
Navigate to API Keys in the left sidebar
Click Create Key
Copy the key (starts with sk-ant-)

Cost: Pay-per-use. See https://www.anthropic.com/pricing for current rates.

Environment variable: You can also set ANTHROPIC_API_KEY before running the wizard and it will auto-detect it.

Step 4: Agents

Field	Default	Notes
Agent names	`apple,banana,cherry,orange,pineapple`	Comma-separated list of agent personas
Default model	`anthropic/claude-sonnet-4-5`	Any Anthropic model ID

Optional — LM Studio (local inference): If you want to run models locally alongside Claude:

Download LM Studio from https://lmstudio.ai/
Start a local server (default: http://localhost:1234/v1)
Load a model (e.g., qwen_qwen3-next-80b-a3b-instruct)
The wizard will ask for the URL and model ID

Step 5: Slack Integration (optional)

What: Lets agents interact in Slack channels.

How to create a Slack app:

Go to https://api.slack.com/apps
Click Create New App > From scratch
Name it (e.g., "ClawShield Agents"), pick your workspace
Under OAuth & Permissions, add these Bot Token Scopes:
- chat:write — send messages
- app_mentions:read — respond to @mentions
- channels:read — see channel list
- channels:history — read channel messages
- im:read — read DMs
- im:history — read DM history
- im:write — send DMs
Under Socket Mode, enable it
Create an App-Level Token with scope connections:write — this gives you the xapp-... token
Under Install App, install to your workspace
Copy the Bot User OAuth Token (xoxb-...) from the OAuth & Permissions page
Under Event Subscriptions, enable events and subscribe to:
- message.channels
- message.im
- app_mention

Tokens needed by the wizard:

Token	Prefix	Where
Bot token	`xoxb-`	OAuth & Permissions > Bot User OAuth Token
App token	`xapp-`	Basic Information > App-Level Tokens

Environment variables: SLACK_BOT_TOKEN, SLACK_APP_TOKEN

Step 6: Telegram Integration (optional)

What: Lets agents interact in Telegram chats.

How to create a Telegram bot:

Open Telegram and message @BotFather
Send /newbot
Choose a name (e.g., "Friday Agent")
Choose a username (must end in bot, e.g., friday_agent_bot)
BotFather gives you a token like 1234567890:ABCdefGHIjklmNOPqrsTUVwxyz
Copy this token

Per-agent bots (optional): You can create a separate Telegram bot for each agent. The wizard will ask for each agent's token individually. Agents without a dedicated bot use the default token.

Environment variable: TELEGRAM_BOT_TOKEN (for the default bot)

Step 7: Security Policy

Field	Default	Notes
Policy	Auto-generated	Default enables all 3 scanners (vuln, prompt injection, malware)
Gateway port	`18790`	Internal, loopback only. OpenClaw gateway listens here.
Proxy port	`18789`	Public-facing. ClawShield proxy listens here.

If you have an existing policy YAML, provide its path. Otherwise the wizard generates a comprehensive default.

Running the Wizard

Quick start

# Clone the repo
git clone https://github.com/SleuthCo/clawshield
cd clawshield

# Build the setup wizard
go build ./proxy/cmd/clawshield-setup/

# Run it
./clawshield-setup        # Linux/macOS
clawshield-setup.exe      # Windows

What happens

Step 0: Checks all 6 dependencies, offers to auto-install missing ones
Steps 1-7: Collects your information, API keys, channel tokens, policy config
Step 8: Installs OpenClaw, builds ClawShield binaries, writes config files and start scripts

Resume after failure

The wizard saves progress after each step to ~/.clawshield/.setup-state.json. If the wizard fails or you kill it mid-way:

# Just re-run — it detects saved progress and asks to resume
./clawshield-setup

State expires after 24 hours. Secrets are base64-encoded (not encrypted — treat the state file as sensitive).

Non-interactive mode (Docker/CI)

clawshield-setup \
  --non-interactive \
  --anthropic-key "$ANTHROPIC_API_KEY" \
  --display-name "CI Bot" \
  --email "ci@example.com" \
  --agents "apple,cherry" \
  --with-slack \
  --slack-bot-token "$SLACK_BOT_TOKEN" \
  --slack-app-token "$SLACK_APP_TOKEN"

Install from SleuthCo fork (security patches)

# Clone the fork first
git clone https://github.com/SleuthCo/openclaw ~/openclaw

# Run wizard with --from-fork
clawshield-setup --from-fork --fork-path ~/openclaw

This includes security patches:

#13777 — redact secrets in CLI config output
#13779 — Aliyun/Qwen developer role mapping fix
#13780 — trust binding agentId (prevents multi-agent misdirection)

After Installation

Start ClawShield

Windows (use the generated start script):

%USERPROFILE%\.clawshield\clawshield-start.bat

PowerShell:

powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.clawshield\clawshield-start.ps1"

Linux (systemd):

sudo systemctl daemon-reload
sudo systemctl start clawshield-gateway clawshield-proxy
sudo systemctl enable clawshield-gateway clawshield-proxy

Manual (two terminals):

# Terminal 1: OpenClaw gateway
cd ~/.openclaw && ANTHROPIC_API_KEY=sk-ant-... openclaw gateway

# Terminal 2: ClawShield proxy
~/.clawshield/bin/clawshield-proxy \
  --policy ~/.clawshield/policy.yaml \
  --gateway-url http://127.0.0.1:18790 \
  --gateway-token <your-token> \
  --listen :18789

Build the Control UI (web dashboard)

The OpenClaw gateway serves a web dashboard at http://localhost:18790, but the UI assets must be built first. If you skip this step, the gateway runs fine but shows "Control UI assets not found" and the dashboard returns a text error instead of the UI.

# From the OpenClaw repo (fork or npm-installed source)
cd ~/openclaw    # or wherever your OpenClaw source is
npm run ui:build

This builds the Vite SPA into dist/control-ui/. The gateway detects UI assets once at startup and caches the result — so if you build the UI after starting the gateway, you must restart the gateway for it to pick up the new assets.

Important: The gateway caches whether UI assets exist at startup. If it starts without them, it will keep returning "assets not found" even after you build them. Always build the UI before starting the gateway, or restart after building.

If installed from fork (npm install -g .): The global npm package is symlinked to your local repo, so npm run ui:build in the repo puts assets where the gateway expects them automatically.

Dashboard auth: If your gateway has token auth enabled (default), the dashboard will show "unauthorized: gateway token missing" on first load. Go to the Overview tab and paste your gateway token into the Token field. Your token is in ~/.openclaw/openclaw.json under gateway.auth.token.

Verify it's working

# Check proxy is listening
curl http://127.0.0.1:18789/health

# Check gateway is running
curl http://127.0.0.1:18790/health

# Check Control UI is serving (should return HTML, not an error message)
curl -s http://127.0.0.1:18790/ | head -1
# Expected: <!doctype html>

Generated files

File	Purpose
`~/.openclaw/openclaw.json`	Full OpenClaw config (agents, bindings, channels, models)
`~/.openclaw/.env`	Anthropic API key
`~/.openclaw/agents/*/`	Agent directories (knowledge, sessions, vectorstore)
`~/.clawshield/policy.yaml`	Security policy (tool allowlist, scanners, domain allowlist)
`~/.clawshield/bin/clawshield-proxy`	Proxy binary
`~/.clawshield/bin/clawshield-audit`	Audit query tool
`~/.clawshield/clawshield-start.bat`	Windows start script
`~/.clawshield/clawshield-start.ps1`	PowerShell start script

Troubleshooting

"pnpm not found" after installing Node.js

Close and reopen your terminal, then run npm install -g pnpm.

GCC not found on Windows

WinLibs installs GCC deep in AppData. The wizard tries to find it automatically. If it fails:

Open File Explorer
Navigate to %LOCALAPPDATA%\Microsoft\WinGet\Packages\
Find the BrechtSanders.WinLibs.POSIX.UCRT_* folder
Add its mingw64\bin\ directory to your PATH

"clawshield-proxy not recognized" when running start script

This means the wizard couldn't build the proxy binary (GCC was likely missing). Fix:

Install GCC (see Prerequisites above)
Re-run the wizard — it will resume from where it left off and build the binary

Control UI shows "assets not found" or blank page

The gateway caches UI asset detection at startup. If it started before the UI was built:

Build the UI: cd ~/openclaw && npm run ui:build
Verify dist/control-ui/index.html exists
Restart the gateway — it won't detect new assets without a restart

If you see "unauthorized: gateway token missing" in the dashboard, go to the Overview tab (not Chat) and paste your token from ~/.openclaw/openclaw.json → gateway.auth.token.

WSL bash interferes with pnpm

On Windows, if pnpm's script-shell is set to /bin/bash (WSL), builds fail with execvpe(/bin/bash) failed. The wizard auto-fixes this by pointing pnpm to Git Bash instead. Manual fix:

pnpm config set script-shell "C:\Program Files\Git\bin\bash.exe"

eBPF Monitor (Layer 3)

The eBPF monitor is now a Go binary (replacing the previous Python/BCC implementation).

Requirements

Full eBPF mode:

Linux kernel 5.0+
BTF support (/sys/kernel/btf/vmlinux must exist)
Root or CAP_BPF capability

Fallback procfs mode:

Any Linux system with /proc filesystem
No special capabilities required

Running

# Build
go build -o clawshield-ebpf ./ebpf/cmd/clawshield-ebpf/

# Run (auto-detects best backend)
./clawshield-ebpf

The monitor automatically detects system capabilities and falls back to procfs polling if eBPF is unavailable.

Navigation Menu

Repository navigation

install-guide.md

install-guide.md

ClawShield Installation Guide

Prerequisites

1. Git

2. Node.js (v22+)

3. pnpm

4. Go (v1.24+)

5. GCC (C compiler)

Required Information

Step 1: Your Information

Step 2: Installation Directories

Step 3: Anthropic API Key

Step 4: Agents

Step 5: Slack Integration (optional)

Step 6: Telegram Integration (optional)

Step 7: Security Policy

Running the Wizard

Quick start

What happens

Resume after failure

Non-interactive mode (Docker/CI)

Install from SleuthCo fork (security patches)

After Installation

Start ClawShield

Build the Control UI (web dashboard)

Verify it's working

Generated files

Troubleshooting

"pnpm not found" after installing Node.js

GCC not found on Windows

"clawshield-proxy not recognized" when running start script

Control UI shows "assets not found" or blank page

WSL bash interferes with pnpm

eBPF Monitor (Layer 3)

Requirements

Running

FilesExpand file tree

install-guide.md

Latest commit

History

install-guide.md

File metadata and controls

ClawShield Installation Guide

Prerequisites

1. Git

2. Node.js (v22+)

3. pnpm

4. Go (v1.24+)

5. GCC (C compiler)

Required Information

Step 1: Your Information

Step 2: Installation Directories

Step 3: Anthropic API Key

Step 4: Agents

Step 5: Slack Integration (optional)

Step 6: Telegram Integration (optional)

Step 7: Security Policy

Running the Wizard

Quick start

What happens

Resume after failure

Non-interactive mode (Docker/CI)

Install from SleuthCo fork (security patches)

After Installation

Start ClawShield

Build the Control UI (web dashboard)

Verify it's working

Generated files

Troubleshooting

"pnpm not found" after installing Node.js

GCC not found on Windows

"clawshield-proxy not recognized" when running start script

Control UI shows "assets not found" or blank page

WSL bash interferes with pnpm

eBPF Monitor (Layer 3)

Requirements

Running