#11915: Docs: Docker + reverse proxy deployment notes and pairing pitfalls

## Summary This PR adds **complementary documentation** for running OpenClaw in Docker behind a reverse proxy (e.g. Traefik + Cloudflare), based on a real-world deployment that surfaced several *implicit assumptions* not currently documented. The intent is **not to override or replace existing work**, but to **connect and clarify** how OpenClaw behaves today in containerized + reverse-proxy environments, and to help users avoid common dead ends. This PR is documentation-only and does not change runtime behavior. --- ## Context / Related Work This PR complements existing discussions and issues around: - Reverse proxy behavior and device pairing (e.g. issues like #1679) - Token auth vs device pairing confusion - Gateway service vs foreground execution Rather than proposing code changes, this PR documents **what works**, **what fails**, and **why**, when OpenClaw is deployed in Docker behind a proxy. --- ## Problem Statement When deploying OpenClaw in Docker behind a reverse proxy, users commonly encounter: - `systemctl --user unavailable` errors - Restart loops when using `gateway start` or daemon/service paths - Unsupported CLI flags such as `--host` - Unstable device pairing (`unknown requestId`) - Web UI repeatedly disconnecting - Skills appearing “blocked” with little context - Traefik routing appearing broken when the root cause is binding or proxy trust None of these are bugs in isolation, but together they create a steep learning curve for self-hosted users. The current documentation does not clearly state: - Which gateway invocation modes are container-safe - That binding is config-driven (not CLI-driven) - That reverse proxies must be explicitly trusted - That pairing instability can be caused by proxy trust - That the gateway primarily exposes WebSocket rather than a traditional HTTP UI --- ## What This PR Adds ### 1. New documentation (additive only) **`docs/deployment/docker-reverse-proxy.md`** Documents: - Running OpenClaw in Docker without systemd - Why `gateway start` / service modes fail in containers - Correct foreground gateway invocation - Config-based binding (`gateway.bind = lan`) - Reverse proxy considerations (Traefik / Cloudflare) - Required `trustedProxies` configuration - WebSocket vs HTTP expectations **`docs/operations/pairing-and-permissions.md`** Documents: - Pairing vs permissions vs scopes - Why skills are blocked by default - Approval flow and common “nothing happens” cases - Pairing instability behind reverse proxies - How `trustedProxies` affects pairing behavior These files are **additive** and do not modify existing documentation. --- ### 2. Explicit “do not do this” guidance The docs include clear examples to prevent common dead ends: ```bash # ❌ Not container-safe (systemd-dependent) openclaw gateway start openclaw daemon openclaw service # ❌ Unsupported CLI flag openclaw gateway --host 0.0.0.0 # ✅ Container-safe, foreground execution node /app/openclaw.mjs gateway --port 18789 . Reverse proxy trust clarification Documents that behind Traefik / Cloudflare the gateway must trust proxy IP ranges, e.g.: "gateway": { "trustedProxies": ["172.29.0.0/16", "127.0.0.1", "::1"] } Without this, pairing and approvals can be unstable behind reverse proxies. This directly complements existing pairing-related issues without changing semantics. Scope and Non-Goals In scope Documentation Clarification of current behavior Reducing repeated setup dead ends Out of scope Runtime behavior changes Pairing logic changes New CLI flags Security model changes Why This Is Useful This documentation: Reflects how OpenClaw behaves in real infrastructure Explains why certain things fail, not just that they do Reduces duplicate support issues Makes OpenClaw easier to self-host and recommend It turns several days of trial-and-error into a predictable setup path. Testing / Validation The guidance is based on a working deployment using: Docker Traefik reverse proxy Cloudflare TLS External Docker network Web UI + CLI pairing Token auth, approvals, and skills All described configurations were verified in practice. Notes to Maintainers This PR is intentionally conservative: Documentation-only No assumptions about future architecture Focused on preventing user confusion Happy to adjust placement, tone, or structure to better fit the existing docs layout. Thank you for maintaining OpenClaw. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> Adds a new documentation file (`Technical changes.md`) capturing non-standard deployment notes for running OpenClaw in Docker behind a reverse proxy (Traefik + Cloudflare). The doc focuses on container-safe gateway invocation, config-driven binding, trusted proxy configuration, and observed pairing/skills behavior in proxied environments. <h3>Confidence Score: 3/5</h3> - This PR is low risk functionally (docs-only) but needs Markdown fixes to avoid publishing broken examples. - Only a single new documentation file is added, so there’s no runtime risk. However, the file currently includes incorrect escaping that will render poorly and makes the included JSON example invalid, plus an obvious truncation typo; both should be fixed to keep the docs trustworthy. - Technical changes.md <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} **Context used:** - Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8)) - Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13)) <!-- /greptile_comment -->