Skip to content

Commit 72cf925

Browse files
joshavantjoshavant
authored
Gateway: add SecretRef support for gateway.auth.token with auth-mode guardrails (openclaw#35094)
1 parent bc66a8f commit 72cf925

File tree

112 files changed

+5752
-467
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

112 files changed

+5752
-467
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@ Docs: https://docs.openclaw.ai
1818
- Cron/job snapshot persistence: skip backup during normalization persistence in `ensureLoaded` so `jobs.json.bak` keeps the pre-edit snapshot for recovery, while preserving backup creation on explicit user-driven writes. (#35234) Thanks @0xsline.
1919
- TTS/OpenAI-compatible endpoints: add `messages.tts.openai.baseUrl` config support with config-over-env precedence, endpoint-aware directive validation, and OpenAI TTS request routing to the resolved base URL. (#34321) thanks @RealKai42.
2020
- Plugins/before_prompt_build system-context fields: add `prependSystemContext` and `appendSystemContext` so static plugin guidance can be placed in system prompt space for provider caching and lower repeated prompt token cost. (#35177) thanks @maweibin.
21+
- Gateway: add SecretRef support for gateway.auth.token with auth-mode guardrails. (#35094) Thanks @joshavant.
22+
23+
### Breaking
24+
25+
- **BREAKING:** Gateway auth now requires explicit `gateway.auth.mode` when both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs). Set `gateway.auth.mode` to `token` or `password` before upgrade to avoid startup/pairing/TUI failures. (#35094) Thanks @joshavant.
2126

2227
### Fixes
2328

‎docs/cli/configure.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ Notes:
2424

2525
- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
2626
- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
27+
- If you run the daemon install step, token auth requires a token, and `gateway.auth.token` is SecretRef-managed, configure validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
28+
- If token auth requires a token and the configured token SecretRef is unresolved, configure blocks daemon install with actionable remediation guidance.
29+
- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, configure blocks daemon install until mode is set explicitly.
2730

2831
## Examples
2932

‎docs/cli/daemon.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,13 @@ openclaw daemon uninstall
3838
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
3939
- lifecycle (`uninstall|start|stop|restart`): `--json`
4040

41+
Notes:
42+
43+
- `status` resolves configured auth SecretRefs for probe auth when possible.
44+
- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
45+
- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed.
46+
- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
47+
4148
## Prefer
4249

4350
Use [`openclaw gateway`](/cli/gateway) for current docs and examples.

‎docs/cli/dashboard.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,9 @@ Open the Control UI using your current auth.
1414
openclaw dashboard
1515
openclaw dashboard --no-open
1616
```
17+
18+
Notes:
19+
20+
- `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
21+
- For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
22+
- If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.

‎docs/cli/gateway.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,11 @@ Options:
105105
- `--no-probe`: skip the RPC probe (service-only view).
106106
- `--deep`: scan system-level services too.
107107

108+
Notes:
109+
110+
- `gateway status` resolves configured auth SecretRefs for probe auth when possible.
111+
- If a required auth SecretRef is unresolved in this command path, probe auth can fail; pass `--token`/`--password` explicitly or resolve the secret source first.
112+
108113
### `gateway probe`
109114

110115
`gateway probe` is the “debug everything” command. It always probes:
@@ -162,6 +167,10 @@ openclaw gateway uninstall
162167
Notes:
163168

164169
- `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
170+
- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `gateway install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
171+
- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
172+
- In inferred auth mode, shell-only `OPENCLAW_GATEWAY_PASSWORD`/`CLAWDBOT_GATEWAY_PASSWORD` does not relax install token requirements; use durable config (`gateway.auth.password` or config `env`) when installing a managed service.
173+
- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
165174
- Lifecycle commands accept `--json` for scripting.
166175

167176
## Discover gateways (Bonjour)

‎docs/cli/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,7 @@ Options:
359359
- `--gateway-bind <loopback|lan|tailnet|auto|custom>`
360360
- `--gateway-auth <token|password>`
361361
- `--gateway-token <token>`
362+
- `--gateway-token-ref-env <name>` (non-interactive; store `gateway.auth.token` as an env SecretRef; requires that env var to be set; cannot be combined with `--gateway-token`)
362363
- `--gateway-password <password>`
363364
- `--remote-url <url>`
364365
- `--remote-token <token>`

‎docs/cli/onboard.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,28 @@ Non-interactive `ref` mode contract:
6161
- Do not pass inline key flags (for example `--openai-api-key`) unless that env var is also set.
6262
- If an inline key flag is passed without the required env var, onboarding fails fast with guidance.
6363

64+
Gateway token options in non-interactive mode:
65+
66+
- `--gateway-auth token --gateway-token <token>` stores a plaintext token.
67+
- `--gateway-auth token --gateway-token-ref-env <name>` stores `gateway.auth.token` as an env SecretRef.
68+
- `--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
69+
- `--gateway-token-ref-env` requires a non-empty env var in the onboarding process environment.
70+
- With `--install-daemon`, when token auth requires a token, SecretRef-managed gateway tokens are validated but not persisted as resolved plaintext in supervisor service environment metadata.
71+
- With `--install-daemon`, if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
72+
- With `--install-daemon`, if both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, onboarding blocks install until mode is set explicitly.
73+
74+
Example:
75+
76+
```bash
77+
export OPENCLAW_GATEWAY_TOKEN="your-token"
78+
openclaw onboard --non-interactive \
79+
--mode local \
80+
--auth-choice skip \
81+
--gateway-auth token \
82+
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
83+
--accept-risk
84+
```
85+
6486
Interactive onboarding behavior with reference mode:
6587

6688
- Choose **Use secret reference** when prompted.

‎docs/cli/qr.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,10 @@ openclaw qr --url wss://gateway.example/ws --token '<token>'
3535

3636
- `--token` and `--password` are mutually exclusive.
3737
- With `--remote`, if effectively active remote credentials are configured as SecretRefs and you do not pass `--token` or `--password`, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
38-
- Without `--remote`, local `gateway.auth.password` SecretRefs are resolved when password auth can win (explicit `gateway.auth.mode="password"` or inferred password mode with no winning token from auth/env), and no CLI auth override is passed.
38+
- Without `--remote`, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
39+
- `gateway.auth.token` resolves when token auth can win (explicit `gateway.auth.mode="token"` or inferred mode where no password source wins).
40+
- `gateway.auth.password` resolves when password auth can win (explicit `gateway.auth.mode="password"` or inferred mode with no winning token from auth/env).
41+
- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs) and `gateway.auth.mode` is unset, setup-code resolution fails until mode is set explicitly.
3942
- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
4043
- After scanning, approve device pairing with:
4144
- `openclaw devices list`

‎docs/cli/tui.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ Related:
1414

1515
- TUI guide: [TUI](/web/tui)
1616

17+
Notes:
18+
19+
- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
20+
1721
## Examples
1822

1923
```bash

‎docs/gateway/configuration-reference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2431,6 +2431,7 @@ See [Plugins](/tools/plugin).
24312431
- **Legacy bind aliases**: use bind mode values in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), not host aliases (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
24322432
- **Docker note**: the default `loopback` bind listens on `127.0.0.1` inside the container. With Docker bridge networking (`-p 18789:18789`), traffic arrives on `eth0`, so the gateway is unreachable. Use `--network host`, or set `bind: "lan"` (or `bind: "custom"` with `customBindHost: "0.0.0.0"`) to listen on all interfaces.
24332433
- **Auth**: required by default. Non-loopback binds require a shared token/password. Onboarding wizard generates a token by default.
2434+
- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs), set `gateway.auth.mode` explicitly to `token` or `password`. Startup and service install/repair flows fail when both are configured and mode is unset.
24342435
- `gateway.auth.mode: "none"`: explicit no-auth mode. Use only for trusted local loopback setups; this is intentionally not offered by onboarding prompts.
24352436
- `gateway.auth.mode: "trusted-proxy"`: delegate auth to an identity-aware reverse proxy and trust identity headers from `gateway.trustedProxies` (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)).
24362437
- `gateway.auth.allowTailscale`: when `true`, Tailscale Serve identity headers can satisfy Control UI/WebSocket auth (verified via `tailscale whois`); HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Defaults to `true` when `tailscale.mode = "serve"`.

0 commit comments

Comments
 (0)