{"id":45053641,"url":"https://github.com/clawshell/clawshell","last_synced_at":"2026-02-20T10:00:53.939Z","repository":{"id":338312277,"uuid":"1157400044","full_name":"clawshell/clawshell","owner":"clawshell","description":"The Security Layer for OpenClaw, the essential safety harness for PII \u0026 sensitive credentials protection.","archived":false,"fork":false,"pushed_at":"2026-02-19T07:16:56.000Z","size":24728,"stargazers_count":36,"open_issues_count":6,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-19T12:52:35.221Z","etag":null,"topics":["ai","credentials","harness","moltbot","openclaw","pii","rust","secuirty"],"latest_commit_sha":null,"homepage":"https://clawshell.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clawshell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T19:19:42.000Z","updated_at":"2026-02-19T12:30:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clawshell/clawshell","commit_stats":null,"previous_names":["clawshell/clawshell"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/clawshell/clawshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawshell%2Fclawshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawshell%2Fclawshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawshell%2Fclawshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawshell%2Fclawshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clawshell","download_url":"https://codeload.github.com/clawshell/clawshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawshell%2Fclawshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29647768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T09:27:29.698Z","status":"ssl_error","status_checked_at":"2026-02-20T09:26:12.373Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","credentials","harness","moltbot","openclaw","pii","rust","secuirty"],"created_at":"2026-02-19T09:19:07.839Z","updated_at":"2026-02-20T10:00:53.919Z","avatar_url":"https://github.com/clawshell.png","language":"Rust","readme":"# ClawShell 🛡️\n\n![ClawShell Banner](docs/images/banner.png)\n\n\u003e **Powered by Runta. The essential safety harness for OpenClaw's PII \u0026 Sensitive Credentials.**\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/clawshell/clawshell/rust.yml)](https://github.com/clawshell/clawshell/actions)\n[![NPM Version](https://img.shields.io/npm/v/%40clawshell%2Fclawshell)](https://www.npmjs.com/package/@clawshell/clawshell)\n[![Crates.io Version](https://img.shields.io/crates/v/clawshell)](https://crates.io/crates/clawshell)\n\n\n## 📖 Introduction\n\n**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.\n\nOpenClaw 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.\n\n## Key Features\n\n### 1. API Token Secure Binding\n\nClawShell maps virtual API keys to real provider keys so that OpenClaw never has direct access to real credentials.\n\n- **Key Isolation**: Real API keys are stored in `/etc/clawshell/clawshell.toml`, readable only by the `clawshell` system user. OpenClaw holds only virtual keys.\n- **Multi-Provider Support**: Maps keys to OpenAI or Anthropic, injecting the correct authentication header format (`Authorization: Bearer` for OpenAI, `x-api-key` for Anthropic).\n\n### 2. PII Safety Net (DLP)\n\nClawShell scans HTTP request and response bodies for sensitive data using configurable regex patterns.\n\n- **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.\n- **Response Scanning**: Optionally scans upstream responses and redacts detected PII before returning to OpenClaw. Streaming (SSE) responses are passed through without scanning.\n- **Custom Patterns**: Define sensitive data patterns using regex in the TOML config, each with a `block` or `redact` action.\n\n### 3. Sensitive Email Isolation\n\nClawShell supports sender-based email filtering so each virtual key only sees mailbox content based on sender rules.\n\n- **Sender Filtering**: Filter emails by sender.\n- **Key Isolation**: IMAP credentials are stored in `/etc/clawshell/clawshell.toml`, readable only by the `clawshell` system user. OpenClaw holds only virtual keys.\n- **Provider Support**: Built-in Gmail and Outlook presets, with manual IMAP setup for other providers.\n\n### 4. Seamless Integration\n\n- **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.\n- **No External Dependencies**: Uses Unix file system permissions to protect secrets. No IdP, Vault, or external key management service required.\n\n### 5. Ultra Lightweight and Scalable\n\n- Runs in under 10MB of memory.\n- Written in Rust with Tokio.\n\n## Architecture\n\n```\n                               ║ security boundary (Unix File System Permissions)\n                               ║\n                               ║  ┌───────────────────────────┐\n                               ║  │  /etc/clawshell           │\n                               ║  │  ┄ real API keys          │\n                               ║  │  ┄ DLP patterns           │\n                               ║  │  ┄ email sender rules     │\n                               ║  │  ┄ IMAP account creds     │\n                               ║  └──────────┬────────────────┘\n                               ║       reads │\n                               ║  ┌──────────┴────────────────┐\n  ┌──────────────┐  REQUEST    ║  │                           │   REQUEST       ┌────────────┐\n  │              ├──(virtual───╫─►│       ClawShell           ├──-(real key,───►│            │\n  │   OpenClaw   │   key)      ║  │                           │   PII redacted) │  OpenAI /  │\n  │              │             ║  │  DLP scan                 │                 │ Anthropic/ │\n  │ holds only   │  RESPONSE   ║  │  real-key mapping         │   RESPONSE      │ OpenRouter │\n  │ virtual keys │◄────────────║◄─┤  email sender filtering   │◄────────────────┤            │\n  │              │             ║  │                           │                 └────────────┘\n  │              │  EMAIL GET  ║  │                           │   IMAP fetch    ┌────────────┐\n  │              ├───(virtual──║  |                           |───(real key)───►|            |\n  │              │    key)     ║  │                           │                 │ IMAP       │\n  │              │             ║  │                           │                 | Provider   │\n  │              │             ║  │                           │    RESPONSE     │ Gmail /    │\n  │              │  filtered   ║  │                           │◄────────────────│ Outlook /  │\n  │              │◄────────────║◄─|                           |                 │ custom     │\n  └──────────────┘             ║  |                           |                 └────────────┘\n                               ║  └───────────────────────────┘\n```\n\nOpenClaw only holds virtual keys and cannot access the real API keys stored in the privileged config.\n\nClawShell swaps virtual keys for real ones and scans for PII before forwarding requests upstream.\n\nClawShell also enforces sender-based filtering before returning email data.\n\n## Installation\n\n### Cargo\n\n```bash\ncargo install clawshell --locked\n\n# Requires privilege to set up the security boundary\nsudo clawshell onboard\n```\n\n### NPM\n\n```bash\nnpm install -g @clawshell/clawshell\n\n# Requires privilege to set up the security boundary\nsudo clawshell onboard\n```\n\n### Build from Source\n\n```bash\ncargo build --release\nls -al target/release/clawshell\n```\n\n#### Cross-compile on Linux/arm64\n\n```bash\nwget https://musl.cc/x86_64-linux-musl-cross.tgz -O /tmp/musl-cross.tgz\ntar -xzf /tmp/musl-cross.tgz -C /tmp\nCARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=\"/tmp/x86_64-linux-musl-cross/bin/x86_64-linux-musl-gcc\" \\\ncargo build --release --target x86_64-unknown-linux-musl\n```\n\n\n## Advanced Usage\n\n### Onboarding\n\nThe `onboard` command is an interactive setup wizard that must be run with `sudo`. It:\n\n1. Creates the `clawshell` system user.\n2. Creates and secures `/etc/clawshell` (mode 700) and `/var/log/clawshell`.\n3. Walks you through provider selection, API key entry, and virtual key generation.\n4. Writes the ClawShell config to `/etc/clawshell/clawshell.toml`.\n5. Updates your OpenClaw configuration to route through ClawShell.\n6. Starts the ClawShell daemon.\n\n```bash\nsudo clawshell onboard\n```\n\n### More Commands\n\n```bash\n# Start (daemonizes by default)\nsudo clawshell start\n\n# Start in the foreground\nsudo clawshell start --foreground\n\n# Start with a custom config file\nsudo clawshell start -c /path/to/clawshell.toml\n\n# Check status\nclawshell status\n\n# View logs\nclawshell logs\nclawshell logs --level error\nclawshell logs --follow\n\n# Restart / Stop\nsudo clawshell restart\nsudo clawshell stop\n\n# Migrate config schema to current version\nsudo clawshell migrate-config\n```\n\nBy default ClawShell listens on `127.0.0.1:18790`.\n\n### Customized Configuration\n\nClawShell reads its config from `/etc/clawshell/clawshell.toml`. You can view or edit it with:\n\n```bash\nsudo clawshell config          # print current config\nsudo clawshell config --edit   # open in $EDITOR\n```\n\nA minimal config looks like this:\n\n```toml\nversion = \"0.1.1\"\nlog_level = \"info\"\n\n[server]\nhost = \"127.0.0.1\"\nport = 18790\n\n[upstream]\nopenai_base_url = \"https://api.openai.com\"\nanthropic_base_url = \"https://api.anthropic.com\"\n\n# Virtual-to-real API key mappings\n[[keys]]\nvirtual_key = \"vk-alice-001\"\nreal_key = \"sk-your-real-openai-key-here\"\nprovider = \"openai\"\n\n[[keys]]\nvirtual_key = \"vk-claude-001\"\nreal_key = \"sk-ant-your-real-anthropic-key-here\"\nprovider = \"anthropic\"\n\n# Data Loss Prevention (DLP)\n# action = \"block\"  -\u003e reject the request with 400\n# action = \"redact\" -\u003e replace matches with [REDACTED:\u003cname\u003e] and forward\n[dlp]\nscan_responses = false\npatterns = [\n    { name = \"ssn\",       regex = '\\b\\d{3}-\\d{2}-\\d{4}\\b',          action = \"redact\" },\n    { name = \"visa_card\", regex = '\\b4[0-9]{12}(?:[0-9]{3})?\\b',    action = \"redact\" },\n    { name = \"amex_card\", regex = '\\b3[47][0-9]{13}\\b',             action = \"redact\" },\n]\n\n# Email secure endpoint\n[email]\nenabled = true\nmode = \"allowlist\"\nallow_senders = [\"alice@example.com\", \"@trusted.org\"]\ndeny_senders = []\ndefault_max_results = 50\n\n[[email.accounts]]\nvirtual_key = \"vk-email-001\"\nemail = \"bot@gmail.com\"\napp_password = \"abcd efgh ijkl mnop\"\nimap_host = \"imap.gmail.com\"\nimap_port = 993\n# Outlook preset example:\n# imap_host = \"imap-mail.outlook.com\"\n```\n\nIf `start`, `restart`, `stop`, `config --edit`, `onboard`, or `uninstall` reports that migration is required, run:\n\n```bash\nsudo clawshell migrate-config --config /etc/clawshell/clawshell.toml\n```\n\nSee [`clawshell.example.toml`](clawshell.example.toml) for a full example.\n\n### Uninstall\n\n```bash\nsudo clawshell uninstall\n```\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n","funding_links":[],"categories":["Secrets Management \u0026 Isolation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclawshell%2Fclawshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclawshell%2Fclawshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclawshell%2Fclawshell/lists"}