ClawShell 🛡️

Powered by Runta. The essential safety harness for OpenClaw's PII & Sensitive Credentials.

📖 Introduction

ClawShell is a security-privileged process for the OpenClaw ecosystem. It sits between OpenClaw and upstream LLM API providers (OpenAI, Anthropic, OpenRouter), performing virtual-to-real API key mapping and DLP (Data Loss Prevention) scanning on request and response bodies. It can also expose an Email read endpoint with sender allowlist/denylist filtering.

OpenClaw never holds real API keys, only virtual keys that ClawShell swaps for real ones before forwarding requests upstream. Real keys are stored in a privileged config directory (/etc/clawshell) protected by Unix file system permissions.

Key Features

1. API Token Secure Binding

ClawShell maps virtual API keys to real provider keys so that OpenClaw never has direct access to real credentials.

• Key Isolation: Real API keys are stored in /etc/clawshell/clawshell.toml, readable only by the clawshell system user. OpenClaw holds only virtual keys.
• Multi-Provider Support: Maps keys to OpenAI or Anthropic, injecting the correct authentication header format (Authorization: Bearer for OpenAI, x-api-key for Anthropic).

2. PII Safety Net (DLP)

ClawShell scans HTTP request and response bodies for sensitive data using configurable regex patterns.

• Request Scanning: Detects PII (SSNs, credit card numbers, emails, etc.) in outbound requests. Patterns can be configured to either block the request or redact the matched text before forwarding.
• Response Scanning: Optionally scans upstream responses and redacts detected PII before returning to OpenClaw. Streaming (SSE) responses are passed through without scanning.
• Custom Patterns: Define sensitive data patterns using regex in the TOML config, each with a block or redact action.

3. Sensitive Email Isolation

ClawShell supports sender-based email filtering so each virtual key only sees mailbox content based on sender rules.

• Sender Filtering: Filter emails by sender.
• Key Isolation: IMAP credentials are stored in /etc/clawshell/clawshell.toml, readable only by the clawshell system user. OpenClaw holds only virtual keys.
• Provider Support: Built-in Gmail and Outlook presets, with manual IMAP setup for other providers.

4. OAuth Authentication (Codex / ChatGPT)

ClawShell supports OAuth-based authentication as an alternative to static API keys.

• Device Code Flow: Log in via a one-time code — no browser required on the server. The onboard wizard prints a URL and code; authorize from any device.
• Automatic Token Refresh: Access tokens are refreshed transparently before they expire.
• Request Translation: Automatically translates OpenAI Chat Completions API requests to the ChatGPT Responses API format when using Codex OAuth.

5. Seamless Integration

• Drop-in Sidecar: Deploys alongside OpenClaw without requiring re-install — the clawshell onboard command automatically configures OpenClaw to point at ClawShell's address and forwards all requests upstream.
• No External Dependencies: Uses Unix file system permissions to protect secrets. No IdP, Vault, or external key management service required.

6. Ultra Lightweight and Scalable

• Runs in under 10MB of memory.
• Written in Rust with Tokio.

Architecture

                               ║ security boundary (Unix File System Permissions)
                               ║
                               ║  ┌───────────────────────────┐
                               ║  │  /etc/clawshell           │
                               ║  │  ┄ real API keys          │
                               ║  │  ┄ DLP patterns           │
                               ║  │  ┄ email sender rules     │
                               ║  │  ┄ IMAP account creds     │
                               ║  └──────────┬────────────────┘
                               ║       reads │
                               ║  ┌──────────┴────────────────┐
  ┌──────────────┐  REQUEST    ║  │                           │   REQUEST       ┌────────────┐
  │              ├──(virtual───╫─►│       ClawShell           ├──-(real key,───►│            │
  │   OpenClaw   │   key)      ║  │                           │   PII redacted) │  OpenAI /  │
  │              │             ║  │  DLP scan                 │                 │ Anthropic/ │
  │ holds only   │  RESPONSE   ║  │  real-key mapping         │   RESPONSE      │ OpenRouter │
  │ virtual keys │◄────────────║◄─┤  email sender filtering   │◄────────────────┤            │
  │              │             ║  │                           │                 └────────────┘
  │              │  EMAIL GET  ║  │                           │   IMAP fetch    ┌────────────┐
  │              ├───(virtual──║  |                           |───(real key)───►|            |
  │              │    key)     ║  │                           │                 │ IMAP       │
  │              │             ║  │                           │                 | Provider   │
  │              │             ║  │                           │    RESPONSE     │ Gmail /    │
  │              │  filtered   ║  │                           │◄────────────────│ Outlook /  │
  │              │◄────────────║◄─|                           |                 │ custom     │
  └──────────────┘             ║  |                           |                 └────────────┘
                               ║  └───────────────────────────┘

OpenClaw only holds virtual keys and cannot access the real API keys stored in the privileged config.

ClawShell swaps virtual keys for real ones and scans for PII before forwarding requests upstream.

ClawShell also enforces sender-based filtering before returning email data.

Installation

Cargo

cargo install clawshell --locked

# Requires privilege to set up the security boundary
sudo clawshell onboard

NPM

npm install -g @clawshell/clawshell

# Requires privilege to set up the security boundary
sudo clawshell onboard

Build from Source

cargo build --release
ls -al target/release/clawshell

Cross-compile on Linux/arm64

wget https://musl.cc/x86_64-linux-musl-cross.tgz -O /tmp/musl-cross.tgz
tar -xzf /tmp/musl-cross.tgz -C /tmp
CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER="/tmp/x86_64-linux-musl-cross/bin/x86_64-linux-musl-gcc" \
cargo build --release --target x86_64-unknown-linux-musl

Advanced Usage

Onboarding

The onboard command is an interactive setup wizard that must be run with sudo. It:

1. Creates the clawshell system user.
2. Creates and secures /etc/clawshell (mode 700) and /var/log/clawshell.
3. Walks you through provider selection, API key entry, and virtual key generation.
4. Writes the ClawShell config to /etc/clawshell/clawshell.toml.
5. Updates your OpenClaw configuration to route through ClawShell.
6. Starts the ClawShell daemon.

sudo clawshell onboard

More Commands

# Start (daemonizes by default)
sudo clawshell start

# Start in the foreground
sudo clawshell start --foreground

# Start with a custom config file
sudo clawshell start -c /path/to/clawshell.toml

# Check status
clawshell status

# View logs
clawshell logs
clawshell logs --level error
clawshell logs --follow

# Restart / Stop
sudo clawshell restart
sudo clawshell stop

# Migrate config schema to current version
sudo clawshell migrate-config

By default ClawShell listens on 127.0.0.1:18790.

You can override the bind address at runtime with environment variables:

CLAWSHELL_SERVER_HOST=0.0.0.0 CLAWSHELL_SERVER_PORT=17890 clawshell start --foreground

Customized Configuration

ClawShell reads its config from /etc/clawshell/clawshell.toml. You can view or edit it with:

sudo clawshell config          # print current config
sudo clawshell config --edit   # open in $EDITOR

A minimal config looks like this:

version = "0.1.1"
log_level = "info"

[server]
host = "127.0.0.1"
port = 18790

[upstream]
openai_base_url = "https://api.openai.com"
anthropic_base_url = "https://api.anthropic.com"

# Virtual-to-real API key mappings
[[keys]]
virtual_key = "vk-alice-001"
real_key = "sk-your-real-openai-key-here"
provider = "openai"

[[keys]]
virtual_key = "vk-claude-001"
real_key = "sk-ant-your-real-anthropic-key-here"
provider = "anthropic"

# Data Loss Prevention (DLP)
# action = "block"  -> reject the request with 400
# action = "redact" -> replace matches with [REDACTED:<name>] and forward
[dlp]
scan_responses = false
patterns = [
    { name = "ssn",       regex = '\b\d{3}-\d{2}-\d{4}\b',          action = "redact" },
    { name = "visa_card", regex = '\b4[0-9]{12}(?:[0-9]{3})?\b',    action = "redact" },
    { name = "amex_card", regex = '\b3[47][0-9]{13}\b',             action = "redact" },
]

# Email secure endpoint
[email]
enabled = true
mode = "allowlist"
allow_senders = ["alice@example.com", "@trusted.org"]
deny_senders = []
default_max_results = 50

[[email.accounts]]
virtual_key = "vk-email-001"
email = "bot@gmail.com"
app_password = "abcd efgh ijkl mnop"
imap_host = "imap.gmail.com"
imap_port = 993
# Outlook preset example:
# imap_host = "imap-mail.outlook.com"

OAuth Authentication (Codex / ChatGPT)

Instead of a static API key, you can authenticate via OAuth using your ChatGPT