fix: fresh deploy compat fixes (gosu grep, wrangler 4.71 placeholders, docs)

deploy/host/build-openclaw.sh

@@ -87,7 +87,9 @@ HOST_NEEDS_RESTORE=true
 # ── 4. Apply patches ────────────────────────────────────────────────
 
 # 4a. Dockerfile: install Docker + gosu for nested Docker
-if ! grep -q "docker.io" Dockerfile; then
+# Note: grep for "gosu" specifically — the upstream Dockerfile contains "docker.io" in
+# its LABEL metadata (docker.io/library/node:...) which would give a false positive.
+if ! grep -q "gosu" Dockerfile; then
   echo "[build] Patching Dockerfile to install Docker + gosu..."
   sed -i '0,/^USER node/{/^USER node/i RUN apt-get update && apt-get install -y --no-install-recommends docker.io gosu gettext-base && usermod -aG docker node && rm -rf /var/lib/apt/lists/*
 }' Dockerfile

docker-compose.yml.hbs

@@ -112,7 +112,9 @@ services:
     command: tunnel run
     environment:
       - TUNNEL_TOKEN={{stack.cloudflare.tunnel_token}}
-    networks: [openclaw-net]
+    # Host networking so tunnel ingress can reach localhost-bound ports
+    # (openclaw gateway ports are published on 127.0.0.1, not on the bridge network).
+    network_mode: host
     deploy:
       resources:
         limits:

playbooks/01-workers.md

@@ -14,6 +14,21 @@ This playbook deploys:
 - Cloudflare account with Workers enabled
 - Node.js and npm installed locally
 - `wrangler` CLI available (installed as devDependency)
+- A **workers.dev subdomain** registered for your account (one-time setup: Cloudflare Dashboard → Workers & Pages → Overview → claim your `<name>.workers.dev` subdomain)
+
+### Cloudflare API Token
+
+All `wrangler` commands in this playbook read the API token from `CLOUDFLARE_API_TOKEN` in `.env` (exported via `source-config.sh`). The token must have the following permissions:
+
+| Resource | Permission |
+|----------|------------|
+| Account — Cloudflare Tunnel | Edit |
+| Zone — DNS | Edit |
+| Account — Workers Scripts | Edit |
+| Account — Workers KV Storage | Edit |
+| Account — D1 | Edit |
+
+> **Multi-account:** If your Cloudflare API token covers multiple accounts, wrangler's `/memberships` lookup may fail or select the wrong account. Set `CLOUDFLARE_ACCOUNT_ID` in `.env` to your Cloudflare account ID (from `wrangler whoami`) to bypass the lookup. Without it, `wrangler kv namespace create` and `wrangler d1 create` may fail with a 403 even when the token is correct.
 
 ## Variables
 

scripts/cf-tunnel-setup.sh

@@ -21,6 +21,9 @@ set -euo pipefail
 # Environment:
 #   CF_API_TOKEN              Required — Cloudflare API token with Tunnel Edit + DNS Edit
 #   CF_TUNNEL_TOKEN           Optional — used to extract tunnel ID if --tunnel-id not given
+#
+# Local dependencies:
+#   jq                        Required — install with: brew install jq (macOS) / apt install jq (Linux)
 
 # Resolve paths via canonical config helper
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

workers/ai-gateway/wrangler.jsonc.example

@@ -10,7 +10,7 @@
   // Create namespace: wrangler kv namespace create AUTH_KV
   // Then paste the returned ID below.
   "kv_namespaces": [
-    { "binding": "AUTH_KV", "id": "" }
+    { "binding": "AUTH_KV", "id": "00000000000000000000000000000000" }
   ],
 
   // Workers Logs: enables console.log in the worker

workers/log-receiver/wrangler.jsonc.example

@@ -28,7 +28,7 @@
     {
       "binding": "DB",
       "database_name": "openclaw-logs",
-      "database_id": "<run: npx wrangler d1 create>"
+      "database_id": "00000000-0000-0000-0000-000000000000"
     }
   ],