diff --git a/packages/openclaw-plugin/README.md b/packages/openclaw-plugin/README.md index 9efc6ddd4..c4eeb5738 100644 --- a/packages/openclaw-plugin/README.md +++ b/packages/openclaw-plugin/README.md @@ -113,7 +113,7 @@ A correctly-exposed deployment returns `401 invalid signature` (the plugin's HMA **Known gotcha — `clawdbot-railway-template` on Railway.** The Railway deploy template `clawdbot-railway-template` ships a wrapper process that forwards **WebSocket upgrades only** to `127.0.0.1:18789`. Plain HTTP requests are dropped with `503` at the Railway edge, so webhook deliveries cannot reach the gateway. Teams running this template must either replace the wrapper with one that also forwards HTTP, bypass it with a direct reverse proxy to the gateway port, or host the plugin on a platform that exposes the gateway HTTP listener normally (InstaClaw is known to work). Deployments confirmed working: InstaClaw with a reverse proxy pointing at `127.0.0.1:18789`. -**Known gotcha — `arjunkomath/openclaw-railway-template` on Railway.** This template's Node wrapper mounts `express.json()` globally ([`src/server.js`](https://github.com/arjunkomath/openclaw-railway-template/blob/main/src/server.js)), which consumes JSON request bodies before `http-proxy` forwards them to the gateway. Webhook POSTs therefore reach the plugin with an empty body, and HMAC verification fails with `401 invalid signature` even when the URL, secret, and transport are all configured correctly — the wrapper's `proxyReq` handler only sets auth headers, it does not re-emit `req.body`. Separately, after any OpenClaw `SIGUSR1` self-restart (triggered by config changes), the wrapper loses track of its `gatewayProc` child handle via the "gateway still reachable; assuming OpenClaw restarted itself" branch, and starts serving `503` with the loading splash HTML on every HTTP request even though the gateway process is still running — WebSocket upgrades keep working because the upgrade path skips the readiness check, so the dashboard looks fine while webhook delivery is broken. Both bugs live in the template, not the plugin; file upstream or fork before relying on this template for webhook delivery. +**Recommended Railway template.** Deploy [`indexnetwork/openclaw-railway-template`](https://github.com/indexnetwork/openclaw-railway-template) with Railway's one-click deploy: [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/pZ1Gfl). This fork of `arjunkomath/openclaw-railway-template` includes three Railway-specific fixes: (1) `express.json()` is scoped to `/setup/api` so proxied request bodies reach the gateway intact, (2) the wrapper tracks `gatewayExternallyHealthy` so `SIGUSR1` self-restarts by OpenClaw don't strand the wrapper serving `503`s on every HTTP request, and (3) redirects `/openclaw/favicon.svg` to `/favicon.svg` because the OpenClaw gateway serves the favicon at the root path but the HTML references it under `/openclaw/`. After Railway creates the project, finish OpenClaw onboarding at `/setup`, then confirm `https:///index-network/webhook` returns `401 invalid signature`. ## License