ClawShell

ClawShell uses configurable regex patterns in clawshell.toml to detect sensitive data (SSNs, credit cards, emails, etc.) in HTTP request and response bodies.

For each pattern, you can specify an action:

• block: Prevents the request from being forwarded if a match is found.
• redact: Replaces the matched text with redacted content before forwarding.

Note: Streaming (SSE) responses are passed through without scanning.

ClawShell supports OAuth-based authentication as an alternative to static API keys, specifically for services like ChatGPT/Codex.

• Device Code Flow: The clawshell onboard wizard prints a URL and a code. You authorize the connection from any device by visiting the URL and entering the code; no browser is required on the server.
• Automatic Refresh: Access tokens are refreshed automatically before expiration.
• Request Translation: When using Codex OAuth, ClawShell automatically translates OpenAI Chat Completions API requests into the ChatGPT Responses API format.

When selecting OpenClaw during sudo clawshell onboard, ClawShell:

1. Backs up ~/.openclaw/openclaw.json to .bak files (mode 000).
2. Patches OpenClaw configuration using openclaw config set to route requests through ClawShell.
3. Writes a get-email-messages skill bundle to <openclaw_root>/skills/ if email integration is enabled.
4. Optionally runs openclaw models set clawshell and openclaw gateway restart to finalize the setup.

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

1. Agent Selection: You must choose exactly one downstream agent to wire through ClawShell: OpenClaw or Hermes Agent.
2. System Setup: Creates the clawshell system user and secures /etc/clawshell (mode 700) and /var/log/clawshell.
3. Configuration: Walks you through provider selection, API key entry, and virtual key generation, writing the final config to /etc/clawshell/clawshell.toml.
4. Agent Integration: Automatically patches the chosen agent (OpenClaw or Hermes) to route through ClawShell.
5. Daemon: Starts the ClawShell daemon.

Note: You can only configure one agent per run. To switch agents, you must re-run the onboard command.

sudo clawshell onboard

You can install ClawShell using Cargo, NPM, or by building from source. After installation, you must run the onboard wizard with elevated privileges to set up the security boundary (e.g., creating /etc/clawshell and setting file permissions).

Cargo

cargo install clawshell --locked
sudo clawshell onboard

NPM

npm install -g @clawshell/clawshell
sudo clawshell onboard

Build from Source

RUSTFLAGS="--remap-path-prefix=$(pwd)=. --remap-path-prefix=$HOME=/" cargo build --release

When running the ClawShell onboarding wizard, you must specify which downstream LLM client to route through the ClawShell proxy. You can choose between two targets:

1. Openclaw: Patches the OpenClaw configuration file (typically located at ~/.openclaw/openclaw.json).
2. Hermes: Configures the Hermes Agent using the hermes config set command.

Note that you can only select exactly one target per onboarding run.

use std::path::PathBuf;

// Example of selecting the Openclaw target
let target = OnboardTarget::Openclaw {
    config_path: PathBuf::from("~/.openclaw/openclaw.json"),
};

// Example of selecting the Hermes target
let target = OnboardTarget::Hermes;

The DlpScanner uses two primary actions defined in DlpAction to handle sensitive data:

1. Block: These patterns are used to identify high-severity violations. When using scan_and_redact, matching Block patterns are reported in the blocked field of the ScanResult but are not replaced in the redacted output.
2. Redact: These patterns are used for PII masking. When using scan_and_redact, matching Redact patterns are replaced in the output with the string [REDACTED:<name>].

Note on redact_all: When calling redact_all, the distinction between Block and Redact is ignored; all matching patterns are replaced with the redaction string.

By default, ClawShell listens on 127.0.0.1:18790. You can override the bind address and port at runtime using environment variables:

• CLAWSHELL_SERVER_HOST: The host address to bind to.
• CLAWSHELL_SERVER_PORT: The port to listen on.

CLAWSHELL_SERVER_HOST=0.0.0.0 CLAWSHELL_SERVER_PORT=17890 clawshell start --foreground

ClawShell supports two authentication methods during the onboarding process:

• StaticKey (Default): Uses a traditional static API key. When using this method, you must provide a real_api_key which ClawShell will then wrap into a virtual_api_key.
• OAuth: Uses an OAuth provider (e.g., "codex") to supply access tokens at runtime. When using this method, the real_api_key field is left empty.

use std::path::PathBuf;

// Using a static API key
let auth = OnboardAuthMethod::StaticKey;

// Using an OAuth provider
let auth = OnboardAuthMethod::OAuth {
    provider_id: "codex".to_string(),
};