feat(security): Zero-trust secure gateway with secrets proxy

Summary

Implements a zero-trust architecture for the OpenClaw gateway. In secure mode (--secure), the gateway runs in a Docker container that has no access to any secrets — API keys, tokens, and credentials remain exclusively on the host.

A host-side secrets proxy intercepts all outbound API requests from the container, injects credentials at the network edge, and enforces a domain allowlist to prevent exfiltration. A socat relay container on an isolated Docker network bridges the gap between the air-gapped gateway container and the host proxy.

Architecture

graph TB
  USER["👤 User / Client<br/>(browser, Telegram, WhatsApp, …)"]

  subgraph HOST ["🖥️ Host Machine"]
    CLI["openclaw gateway --secure<br/>(CLI orchestrator)"]
    PROXY["Secrets Proxy<br/>127.0.0.1:8080 / Unix socket<br/>─────────────────<br/>• Holds all API keys<br/>• Domain allowlist<br/>• Placeholder → secret replacement"]
    CLI -->|starts| PROXY
  end

  subgraph NET ["🔒 openclaw-secure-net (internal, no internet)"]
    GW["Gateway Container<br/>openclaw-gateway<br/>─────────────────<br/>• No secrets in env or fs<br/>• PROXY_URL → relay<br/>• secure-fetch wraps fetch()"]
    RELAY["Relay Container<br/>openclaw-relay (socat)<br/>─────────────────<br/>Linux/macOS: TCP → Unix socket<br/>Windows: TCP → host.docker.internal"]
  end

  USER <-->|"WebSocket<br/>(chat messages)"| GW
  GW -->|"outbound API call<br/>X-Target-URL + X-Proxy-Token"| RELAY
  RELAY -->|forwards request| PROXY
  PROXY -->|"request with real credentials"| API["☁️ Allowlisted APIs<br/>LLMs · Channels · Integrations<br/>(Anthropic, Telegram, Notion, …)"]
  API -.->|response| PROXY
  PROXY -.->|response| RELAY
  RELAY -.->|response| GW

Request Flow

sequenceDiagram
  participant USER as User / Client
  participant GW as Gateway Container
  participant RELAY as Relay (socat)
  participant PROXY as Host Secrets Proxy
  participant API as Allowlisted API

  USER->>GW: Chat message (WebSocket)
  Note over GW: Gateway processes message,<br/>needs to call an external API
  GW->>GW: fetch("https://api.example.com/...")
  Note over GW: secure-fetch intercepts
  GW->>RELAY: POST PROXY_URL<br/>X-Target-URL: api.example.com<br/>X-Proxy-Token: <token><br/>Body contains {{API_KEY}}
  RELAY->>PROXY: socat forwards (TCP→socket or TCP→host)
  PROXY->>PROXY: 1. Verify proxy token
  PROXY->>PROXY: 2. Check domain allowlist
  PROXY->>PROXY: 3. Replace {{...}} with real keys
  PROXY->>API: Forward with real credentials
  API-->>PROXY: Response
  PROXY-->>RELAY: Response
  RELAY-->>GW: Response
  GW-->>USER: Reply (WebSocket)

Zero-Trust Model

Traditional setups pass API keys directly to the gateway — if the gateway is compromised via prompt injection or malicious dependencies, your keys leak. This PR implements a zero-trust model:

• Bot container receives only a proxy URL, never real credentials
• Host-side secrets proxy holds all credentials
• All API requests route through the proxy, which injects credentials at the network edge
• Even a fully compromised container cannot extract your API keys

Prerequisites

Docker Installation

Secure mode requires Docker to be installed and running:

# Ubuntu/Debian
sudo apt update && sudo apt install -y docker.io
sudo systemctl enable --now docker

# Add your user to docker group (logout required)
sudo usermod -aG docker $USER

# Verify installation
docker --version

Building the Docker Image

Before first use, build the secure gateway image:

npm run docker:build
# Or manually:
docker build -t openclaw-gateway -f Dockerfile.gateway .

Key Changes

Secrets Proxy (secrets-proxy.ts)

• Runs on host, intercepts all outbound requests from container
• Replaces {{CONFIG:...}}, {{OAUTH:...}}, {{ENV:...}} placeholders with real values
• Enforces domain allowlist to prevent exfiltration
• Per-request auth via X-Proxy-Token header (random per-run secret)

Relay Container (gateway-container.ts)

• socat-based relay bridges the air-gapped internal network to the host proxy
• Linux/macOS (Unix socket mode): mounts the host proxy's Unix socket and relays TCP→UNIX-CONNECT
• Windows (TCP mode): relays TCP→host.docker.internal:hostPort then disconnects from the bridge network for isolation
• Explicit hostProxyPort parameter decouples relay listen port from upstream target port

Config Sanitization (sanitize-secrets.ts)

• Strips all sensitive values from config before mounting into container
• Replaces with placeholders that only the host proxy can resolve

Secure Fetch Wrapper (secure-fetch.ts)

• Intercepts all fetch() calls inside the container
• Routes through host proxy via X-Target-URL header
• Gated on PROXY_URL env var (container-only, no-op on host)

Container Isolation (prepare-sanitized-mounts.ts)

• Mounts sanitized config (read-only)
• Mounts credentials directory for pairing files (read-only)
• Separates session storage between normal and secure modes

Secrets Registry (secrets-registry.ts)

• Host-side credential store that resolves placeholders to real values
• Supports config keys, OAuth tokens, and environment variables
• Provides the data layer for the secrets proxy

Security Auditing (audit.ts, audit-extra.ts, audit-fs.ts)

• Pre-launch audit of the container environment
• Verifies no secrets leaked into env vars, filesystem, or config
• Blocks container start if secrets are detected

Security Enhancements

Backwards Compatibility

This is an opt-in security feature. Without --secure, the gateway runs exactly as before:

• No Docker required
• Direct access to secrets
• No performance overhead

Users can adopt secure mode when ready, with no changes to their existing setup.

Usage

# Start gateway in zero-trust secure mode
openclaw gateway --secure

# Manage allowed domains
openclaw gateway allowlist list
openclaw gateway allowlist add api.example.com
openclaw gateway allowlist remove api.example.com

# Get/set the secrets proxy port
openclaw gateway allowlist port          # show current port
openclaw gateway allowlist port 9090     # set a custom port

CLI Commands

Testing

• Telegram polling works in secure mode
• DM authorization works with pairing files mounted
• LLM API calls succeed with placeholder replacement
• Allowlist blocks unauthorized domains
• Normal mode (without --secure) continues to work unchanged
• Relay container isolated from bridge network (TCP mode)
• Unix socket relay works on Linux/macOS

AI Assistance 🤖

This PR was developed with AI assistance (Gemini/Claude).

• Testing level: Fully tested with Telegram in secure mode
• Understanding: I understand the code and have reviewed all changes

Greptile Overview

Greptile Summary

This PR implements a production-grade zero-trust architecture for the OpenClaw gateway. The core design successfully isolates secrets from the container runtime using a host-side proxy with placeholder-based credential injection.

Architecture Overview

The implementation uses three key components:

1. Gateway Container - Runs on an --internal Docker network (no internet access), contains zero secrets
2. Socat Relay - Bridges the internal network to the host proxy via Unix socket (Linux/macOS) or TCP (Windows)
3. Secrets Proxy - Host-side HTTP proxy that intercepts API requests, validates against an allowlist, and injects real credentials by replacing placeholders like {{CONFIG:channels.telegram.botToken}}

Security Model

The threat model assumes the gateway container is fully compromised (e.g., via prompt injection or malicious dependencies). Protection mechanisms:

• All API keys, OAuth tokens, and credentials remain exclusively on the host
• Container filesystem contains only placeholder strings
• Network-level isolation blocks direct internet access
• Domain allowlist prevents exfiltration to unauthorized endpoints
• Per-session proxy authentication token prevents unauthorized local processes from using the proxy

Key Implementation Strengths

1. Placeholder System - Comprehensive coverage of CONFIG, OAUTH, OAUTH_REFRESH, APIKEY, TOKEN, and ENV patterns with DoS limits
2. OAuth Refresh Handling - Refresh tokens are correctly resolved from the live authStore.profiles (not the startup snapshot) to handle token rotation
3. Binary Body Preservation - Content-Type detection ensures non-text payloads aren't corrupted during placeholder replacement
4. Platform-Specific Networking - Unix sockets on Linux/macOS (zero TCP exposure) vs. localhost TCP on Windows (Docker Desktop constraint)
5. Sanitization Logic - Config and auth-profiles files are pre-sanitized before mounting into the container
6. Loopback Detection - Proper handling of localhost, ::1, and the full 127.0.0.0/8 range to bypass proxy for local services

Recent Fixes Confirmed

From the previous review thread, the following critical issues have been resolved:

• Request body forwarding now converts ReadableStream to ArrayBuffer for Node/undici compatibility (secure-fetch.ts:102)
• Proxy auth token (PROXY_AUTH_TOKEN) is correctly passed to container and normalized as string | string[] before comparison (secrets-proxy.ts:263)
• OAuth refresh is properly gated on PROXY_URL instead of OPENCLAW_SECURE_MODE to avoid breaking host-side proxy (oauth.ts:43)
• Allowlist caching uses mtime-based reload instead of per-request disk reads (secrets-proxy.ts:21-33)
• Redirect handling clarified - undici doesn't follow by default, and any follow-up requests route back through the proxy for re-validation
• Gateway container now binds to loopback instead of lan to minimize exposure (gateway-container.ts:236)
• Unix socket permissions set to 0600 to prevent other local users from connecting (secrets-proxy.ts:452)
• Credentials directory mount excludes oauth.json legacy file and only mounts safe pairing files (prepare-sanitized-mounts.ts:233-242)

Backwards Compatibility

Secure mode is entirely opt-in via --secure flag. Without it, the gateway runs exactly as before with no Docker requirement.

Confidence Score: 4/5

• This PR is safe to merge with minor caveats around edge case handling
• Score reflects thorough security architecture with comprehensive testing, but the complexity of the Docker networking, placeholder resolution, and multi-platform support introduces surface area for edge cases. The core threat model (container compromise) is well-defended, but operational scenarios (port conflicts, network configuration, legacy OAuth files) require careful deployment documentation.
• Pay attention to src/security/secrets-proxy.ts (credential injection logic), src/security/gateway-container.ts (network isolation), and src/config/prepare-sanitized-mounts.ts (mount sanitization) during deployment and monitoring