mirror of
https://github.com/moltbot/moltbot.git
synced 2026-04-26 07:57:40 +00:00
docs: refresh gateway auth overview refs
This commit is contained in:
Peter Steinberger
@@ -74,7 +74,10 @@ After the first successful load, the running process serves the active in-memory
|
||||
- HTTP APIs, OpenAI compatible (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
|
||||
- Control UI and hooks
|
||||
- Default bind mode: `loopback`.
|
||||
- Auth is required by default (`gateway.auth.token` / `gateway.auth.password`, or `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`).
|
||||
- Auth is required by default. Shared-secret setups use
|
||||
`gateway.auth.token` / `gateway.auth.password` (or
|
||||
`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), and non-loopback
|
||||
reverse-proxy setups can use `gateway.auth.mode: "trusted-proxy"`.
|
||||
|
||||
## OpenAI-compatible endpoints
|
||||
|
||||
@@ -142,7 +145,9 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||
Then connect clients to `ws://127.0.0.1:18789` locally.
|
||||
|
||||
<Warning>
|
||||
If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.
|
||||
SSH tunnels do not bypass gateway auth. For shared-secret auth, clients still
|
||||
must send `token`/`password` even over the tunnel. For identity-bearing modes,
|
||||
the request still has to satisfy that auth path.
|
||||
</Warning>
|
||||
|
||||
See: [Remote Gateway](/gateway/remote), [Authentication](/gateway/authentication), [Tailscale](/gateway/tailscale).
|
||||
|
||||
@@ -15,7 +15,7 @@ process that owns channel connections and the WebSocket control plane.
|
||||
## Core rules
|
||||
|
||||
- One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session. For rescue bots or strict isolation, run multiple gateways with isolated profiles and ports. See [Multiple gateways](/gateway/multiple-gateways).
|
||||
- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard generates a gateway token by default, even for loopback. For tailnet access, run `openclaw gateway --bind tailnet --token ...` because tokens are required for non-loopback binds.
|
||||
- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard generates a gateway token by default, even for loopback. For non-loopback access, use a valid gateway auth path: shared-secret token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment. Tailnet/mobile setups usually work best through Tailscale Serve or another `wss://` endpoint instead of raw tailnet `ws://`.
|
||||
- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The legacy TCP bridge is deprecated.
|
||||
- Canvas host is served by the Gateway HTTP server on the **same port** as the Gateway (default `18789`):
|
||||
- `/__openclaw__/canvas/`
|
||||
|
||||
@@ -156,19 +156,21 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
||||
The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How do I authenticate the dashboard (token) on localhost vs remote?">
|
||||
<Accordion title="How do I authenticate the dashboard on localhost vs remote?">
|
||||
**Localhost (same machine):**
|
||||
|
||||
- Open `http://127.0.0.1:18789/`.
|
||||
- If it asks for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings.
|
||||
- Retrieve it from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`).
|
||||
- If it asks for shared-secret auth, paste the configured token or password into Control UI settings.
|
||||
- Token source: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
|
||||
- Password source: `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
|
||||
- If no shared secret is configured yet, generate a token with `openclaw doctor --generate-gateway-token`.
|
||||
|
||||
**Not on localhost:**
|
||||
|
||||
- **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https://<magicdns>/`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no token, assumes trusted gateway host); HTTP APIs still require token/password.
|
||||
- **Tailnet bind**: run `openclaw gateway --bind tailnet --token "<token>"`, open `http://<tailscale-ip>:18789/`, paste token in dashboard settings.
|
||||
- **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https://<magicdns>/`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no pasted shared secret, assumes trusted gateway host); HTTP APIs still require shared-secret auth unless you deliberately use private-ingress `none` or trusted-proxy HTTP auth.
|
||||
- **Tailnet bind**: run `openclaw gateway --bind tailnet --token "<token>"` (or configure password auth), open `http://<tailscale-ip>:18789/`, then paste the matching shared secret in dashboard settings.
|
||||
- **Identity-aware reverse proxy**: keep the Gateway behind a non-loopback trusted proxy, configure `gateway.auth.mode: "trusted-proxy"`, then open the proxy URL.
|
||||
- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/` and paste the token in Control UI settings.
|
||||
- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`. Shared-secret auth still applies over the tunnel; paste the configured token or password if prompted.
|
||||
|
||||
See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.
|
||||
|
||||
|
||||
@@ -39,15 +39,37 @@ Prefer localhost, Tailscale Serve, or an SSH tunnel.
|
||||
|
||||
- After onboarding, the CLI auto-opens the dashboard and prints a clean (non-tokenized) link.
|
||||
- Re-open anytime: `openclaw dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
|
||||
- If the UI prompts for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings.
|
||||
- If the UI prompts for shared-secret auth, paste the configured token or
|
||||
password into Control UI settings.
|
||||
|
||||
## Token basics (local vs remote)
|
||||
## Auth basics (local vs remote)
|
||||
|
||||
- **Localhost**: open `http://127.0.0.1:18789/`.
|
||||
- **Token source**: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` can pass it via URL fragment for one-time bootstrap, and the Control UI keeps it in sessionStorage for the current browser tab session and selected gateway URL instead of localStorage.
|
||||
- If `gateway.auth.token` is SecretRef-managed, `openclaw dashboard` prints/copies/opens a non-tokenized URL by design. This avoids exposing externally managed tokens in shell logs, clipboard history, or browser-launch arguments.
|
||||
- If `gateway.auth.token` is configured as a SecretRef and is unresolved in your current shell, `openclaw dashboard` still prints a non-tokenized URL plus actionable auth setup guidance.
|
||||
- **Not localhost**: use Tailscale Serve (tokenless for Control UI/WebSocket if `gateway.auth.allowTailscale: true`, assumes trusted gateway host; HTTP APIs still need token/password), a non-loopback bind with token/password auth, an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. See [Web surfaces](/web).
|
||||
- **Shared-secret token source**: `gateway.auth.token` (or
|
||||
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` can pass it via URL fragment
|
||||
for one-time bootstrap, and the Control UI keeps it in sessionStorage for the
|
||||
current browser tab session and selected gateway URL instead of localStorage.
|
||||
- If `gateway.auth.token` is SecretRef-managed, `openclaw dashboard`
|
||||
prints/copies/opens a non-tokenized URL by design. This avoids exposing
|
||||
externally managed tokens in shell logs, clipboard history, or browser-launch
|
||||
arguments.
|
||||
- If `gateway.auth.token` is configured as a SecretRef and is unresolved in your
|
||||
current shell, `openclaw dashboard` still prints a non-tokenized URL plus
|
||||
actionable auth setup guidance.
|
||||
- **Shared-secret password**: use the configured `gateway.auth.password` (or
|
||||
`OPENCLAW_GATEWAY_PASSWORD`). The dashboard does not persist passwords across
|
||||
reloads.
|
||||
- **Identity-bearing modes**: Tailscale Serve can satisfy Control UI/WebSocket
|
||||
auth via identity headers when `gateway.auth.allowTailscale: true`, and a
|
||||
non-loopback identity-aware reverse proxy can satisfy
|
||||
`gateway.auth.mode: "trusted-proxy"`. In those modes the dashboard does not
|
||||
need a pasted shared secret for the WebSocket.
|
||||
- **Not localhost**: use Tailscale Serve, a non-loopback shared-secret bind, a
|
||||
non-loopback identity-aware reverse proxy with
|
||||
`gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. HTTP APIs still use
|
||||
shared-secret auth unless you intentionally run private-ingress
|
||||
`gateway.auth.mode: "none"` or trusted-proxy HTTP auth. See
|
||||
[Web surfaces](/web).
|
||||
|
||||
<a id="if-you-see-unauthorized-1008"></a>
|
||||
|
||||
@@ -56,8 +78,12 @@ Prefer localhost, Tailscale Serve, or an SSH tunnel.
|
||||
- Ensure the gateway is reachable (local: `openclaw status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`).
|
||||
- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints. If auth still fails after that retry, resolve token drift manually.
|
||||
- For token drift repair steps, follow [Token drift recovery checklist](/cli/devices#token-drift-recovery-checklist).
|
||||
- Retrieve or supply the token from the gateway host:
|
||||
- Plaintext config: `openclaw config get gateway.auth.token`
|
||||
- SecretRef-managed config: resolve the external secret provider or export `OPENCLAW_GATEWAY_TOKEN` in this shell, then rerun `openclaw dashboard`
|
||||
- No token configured: `openclaw doctor --generate-gateway-token`
|
||||
- In the dashboard settings, paste the token into the auth field, then connect.
|
||||
- Retrieve or supply the shared secret from the gateway host:
|
||||
- Token: `openclaw config get gateway.auth.token`
|
||||
- Password: resolve the configured `gateway.auth.password` or
|
||||
`OPENCLAW_GATEWAY_PASSWORD`
|
||||
- SecretRef-managed token: resolve the external secret provider or export
|
||||
`OPENCLAW_GATEWAY_TOKEN` in this shell, then rerun `openclaw dashboard`
|
||||
- No shared secret configured: `openclaw doctor --generate-gateway-token`
|
||||
- In the dashboard settings, paste the token or password into the auth field,
|
||||
then connect.
|
||||
|
||||
Reference in New Issue
Block a user