OpenClaw Gateway Auth Tokens: Create, Store, and Rotate Them Safely

Published June 7, 2026 · OpenClawBlog Team

An auth token can pass the first setup test and still be badly handled. It may be stored in the wrong file, sent to the wrong endpoint, or left active on a device that no longer belongs to the operator.

The official OpenClaw documentation gives you the configuration fields and commands. It also gives a more important warning: a shared Gateway bearer token is an operator credential. It is not a small permission slip for one feature. This article turns that detail into a routine for creating, storing, checking, and replacing the token.

Decide what the token is allowed to mean

Start with the trust boundary. OpenClaw documents one trusted boundary per Gateway: a single operator or a team whose members trust one another. A token authenticates callers to Gateway APIs, but it does not create separate tenants inside the Gateway. The official trust model also describes sessionKey as a routing selector, not an authorization token.

That matters because the same credential may reach sessions, tools, plugins, and other operator functions. The network-exposure documentation describes shared-secret bearer authentication as an all-or-nothing operator path for the listed HTTP APIs. Do not give the token to an untrusted user and expect a later tool policy to turn it into a read-only credential. Use a separate Gateway when the people using it do not share a trust boundary.

Before creating the token, write down:

• Which Gateway process and configuration file are involved.
• Whether clients connect locally, through a private network, or from the public internet.
• Which clients need access, including remote scripts and scheduled jobs.
• Who owns the credential and who can replace it.

Checks before creation

Choose the authentication path

OpenClaw supports token, password, and trusted-proxy authentication modes. The network-exposure guide describes token mode as a shared bearer token and recommends it for most setups. Non-loopback binds need a valid authentication path. The Gateway configuration reference also says that if both a token and password are configured, the auth mode should be explicit.

Do not confuse the two token locations. gateway.auth.token protects the Gateway. gateway.remote.token is a client-side credential used when a client connects to a remote Gateway; it does not enable local Gateway authentication by itself. A client can therefore have a token in its remote configuration while the server is still misconfigured.

Check the installed version and config path

OpenClaw uses a JSON5 configuration file, normally ~/.openclaw/openclaw.json. Use the configuration tools from the installed version instead of copying an old blog example. A useful read-only starting point is:

openclaw config schema
openclaw config get gateway.auth.mode
openclaw config get gateway.bind

The configuration documentation says that unknown keys and invalid values can prevent the Gateway from starting. The troubleshooting guide specifically warns that an old key such as gateway.token does not replace gateway.auth.token.

Generate a real random secret

Use the documented setup flow or openclaw doctor --generate-gateway-token. The network-exposure page also gives openssl rand -hex 32 as an example of generating a real secret. Do not base the value on a hostname, project name, date, or memorable phrase.

OpenClaw rejects blank values, the literal strings undefined and null, and published example placeholders at startup. Its security audit warns when the selected token or password is shorter than 24 characters. That threshold is an audit warning, not proof that a deployment is secure. A random value, a narrow network path, and a replacement procedure still matter.

Store it close to the process that needs it

Every copy is part of the credential's attack surface. OpenClaw's secrets and storage guidance says to assume that files under ~/.openclaw/, or under $OPENCLAW_STATE_DIR, may contain secrets or private data. It names openclaw.json as a file that can contain Gateway and remote-Gateway tokens.

For a local file-based setup, check the permissions after creation. The documented hardening values are 700 for the state directory and 600 for openclaw.json. The same page recommends full-disk encryption and a dedicated operating-system user when the host is shared.

For a service or deployment, OpenClaw supports environment substitution such as ${OPENCLAW_GATEWAY_TOKEN} and SecretRef sources based on environment, file, exec, or store providers. The environment and secrets reference says that unresolved values on active surfaces fail closed. That is useful for avoiding a silent fallback to an empty credential.

A SecretRef does not remove the need for host protection. OpenClaw resolves active secret references into an in-memory snapshot, so the Gateway process still becomes a place where the value can be used. Ask who can read the process environment, secret provider, service diagnostics, backups, and deployment logs. That is an operational inference from the documented storage model, not a claim that every supervisor exposes secrets in the same way.

Keep the token out of source control, screenshots, screen recordings, URLs, shared documents, and raw diagnostic bundles. The storage documentation says that session transcripts can contain pasted secrets, file contents, command output, and links. Redaction is enabled, but the same guidance still recommends pruning old logs and transcripts and adding custom redaction patterns for local tokens and internal URLs.

Validate the connection without leaking the secret

The commands below are documentation-derived. No live Gateway test is claimed here. The useful distinction is between a test an operator should perform and a result that has actually been observed.

Before widening access, the Gateway exposure runbook asks operators to record the host, state directory, bind mode, auth source, enabled channels, reachable agents, tool policy, external credentials, and backup location. Run the documented baseline checks:

openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw health

Resolve critical findings first. The runbook also gives an explicit probe shape:

openclaw gateway probe --url ws://127.0.0.1:18789 --token $OPENCLAW_GATEWAY_TOKEN

Use an environment reference or protected secret source rather than placing the token directly in the command. The runbook warns that an explicit URL does not automatically reuse stored credentials, which explains some confusing authentication failures.

Then perform these proposed tests in a disposable setup or controlled maintenance window:

1. Connect with the intended client and record the endpoint, client identity, and low-impact result. Do not record the token.
2. Try a deliberately incorrect token and confirm that the connection is rejected. This tests enforcement for that route; it does not prove that every proxy, plugin route, or alternate listener is protected.
3. Inspect the bind address, firewall, tunnel, and reverse-proxy route. A successful local connection does not prove that the Gateway is unreachable from unintended networks.
4. Check logs and shared diagnostics for the token. The exposure runbook specifically asks operators to confirm that logs redact secrets after an exposure change.

If the Gateway uses Tailscale Serve, check which surface you are testing. OpenClaw documents Tailscale identity-header authentication for the managed Control UI and WebSocket path, while HTTP API endpoints such as /v1/* and /tools/invoke follow the configured HTTP auth mode. A green browser login is therefore not evidence that every API route accepts the same identity path.

Rotate the token as an operation

A rotation is complete only when the replacement works and the old value no longer works. OpenClaw's documented rotation checklist is short: generate and set a new Gateway secret, update remote clients, and verify that old credentials fail.

Use this order:

1. Inventory every consumer, including local CLI profiles, Control UI settings, containers, launch agents, scheduled jobs, scripts, tunnels, and backup copies.
2. Choose a maintenance window if those consumers cannot be updated together.
3. Generate the replacement and place it in the approved config or SecretRef source.
4. Update clients that use gateway.remote.token or another remote-client credential field.
5. Confirm one low-impact connection with the new value before removing the old value.
6. Apply the reload or restart required by the auth path. Token changes can hot-apply when the effective auth mode stays the same. Auth-mode changes require a Gateway restart. Changes to process-environment credentials also need the supervising service or app to restart; check the hot-reload behavior for the installed version.
7. Test the old token and confirm rejection. Search for clients still trying to use it.
8. Record the date, affected clients, owner, and any dependency that failed during the cutover.

Because a shared token is held by multiple clients, one rotation affects every copy. If the deployment needs individual revocation or user-level identity, a single shared bearer token is the wrong boundary. Consider device or identity-aware authentication, or separate Gateway cells, rather than distributing more copies of the same secret.

If the token may have leaked

Do not wait for the next scheduled rotation. Treat a token in a public issue, shared screenshot, unredacted log, compromised device, or unknown backup as compromised until you can establish otherwise.

The operator incident-response guide gives a practical sequence: stop the Gateway or supervising app, close exposure by returning to loopback or disabling the relevant Tailscale route, freeze risky DMs and wildcard allow entries, rotate Gateway and remote-client secrets, then rotate provider and channel credentials that the agent could reach.

After containment, review redacted logs, session transcripts, recent changes to gateway.bind and gateway.auth, channel policies, elevated tools, and plugin state. Re-run openclaw security audit --deep and keep the incident record separate from the secret itself. Deleting one visible copy does not prove that backups, caches, exports, or process diagnostics do not contain another.

Failure paths that waste time

Unauthorized, even though the Gateway is running

Check the URL, profile, active config, auth mode, and token source. The troubleshooting guide distinguishes a wrong URL from an unauthorized response: the latter usually means the endpoint answered but the supplied auth was wrong. An explicit URL may not use the credentials stored for another target.

It works locally but not remotely

Check gateway.bind first. Loopback is intentionally local. A LAN, tailnet, or custom bind expands the listening surface and still needs Gateway authentication plus network controls. Do not make the Gateway public to solve a private routing problem. The exposure runbook prefers loopback with SSH or Tailscale Serve, and it warns against direct public port forwarding.

The new value is in the file but the service still rejects it

Check whether the service is using the same config path and state directory as the CLI. Then check whether a restart is required because the auth mode or process environment changed. If a SecretRef is unresolved, the documented behavior is fail-closed activation rather than a silent remote fallback.

Trusted-proxy mode is also configured

Do not leave a shared Gateway token beside gateway.auth.mode: trusted-proxy without reading the proxy rules. OpenClaw's trusted-proxy documentation treats the shared token and proxy identity as mutually exclusive paths in a proxy-only cell. A proxy must also be the only network path to the Gateway and must overwrite forwarded identity headers.

Completion checklist

Before calling the token setup complete, an operator should be able to answer yes to these questions:

• Is the token random, unique to this Gateway, and generated through a trusted path?
• Is the selected auth mode explicit and compatible with the bind mode?
• Does every remote client have a recorded credential source?
• Are the state directory, config file, secret provider, backups, logs, and transcripts included in the storage review?
• Are directory and file permissions set to the documented baseline where file storage is used?
• Has an authorized low-impact connection been checked?
• Has rejection of a wrong token been proposed and scheduled as a controlled test?
• Is the replacement order written down, including restart behavior?
• Would a suspected leak trigger immediate containment, rotation, and an access review?

The useful standard is modest: know what the token can reach, know where it can appear, know which clients depend on it, and be able to show that the old value stopped working. That makes the credential manageable even though the Gateway itself still needs host, network, tool, and trust-boundary controls.

Sources

• OpenClaw security trust model for Gateway trust boundaries and the distinction between routing selectors and authorization.
• OpenClaw network exposure for token auth, generation, minimum-length warnings, rotation, Tailscale behavior, and API exposure.
• OpenClaw Gateway configuration reference for auth modes, bind modes, remote-client credentials, and reload behavior.
• OpenClaw environment, secrets, and includes reference for environment substitution, SecretRef providers, and fail-closed resolution.
• OpenClaw secrets, storage, and logs for state-directory contents, permissions, transcript exposure, and redaction guidance.
• OpenClaw Gateway exposure runbook for pre-flight inventory, probes, baseline checks, and post-change validation.
• OpenClaw operator incident response for containment, credential rotation, audit, and evidence collection.
• OpenClaw troubleshooting for URL, profile, auth, config-path, and restart failure paths.