<!-- source: https://deepwiki.com/openclaw/openclaw/2.2-authentication-and-authorization -->

# Authentication & Authorization

- docs/automation/hooks.md
- docs/reference/AGENTS.default.md
- docs/reference/templates/AGENTS.md
- extensions/feishu/src/app-registration.test.ts
- extensions/feishu/src/app-registration.ts
- extensions/memory-core/cli-metadata.ts
- extensions/memory-core/cli.ts
- extensions/telegram/src/bot.create-telegram-bot.test.ts
- extensions/whatsapp/src/auth-store.ts
- extensions/whatsapp/src/creds-files.ts
- extensions/whatsapp/src/creds-persistence.test.ts
- extensions/whatsapp/src/creds-persistence.ts
- extensions/whatsapp/src/login.coverage.test.ts
- extensions/whatsapp/src/login.ts
- extensions/whatsapp/src/session.test.ts
- extensions/whatsapp/src/session.ts
- scripts/repro/cli-web-search-secret-refs-live-proof.mjs
- skills/model-usage/SKILL.md
- src/acp/client-helpers.ts
- src/acp/client.test.ts
- src/agents/model-auth-env-vars.ts
- src/agents/models-config.providers.moonshot.test.ts
- src/agents/models-config.providers.nvidia.test.ts
- src/agents/models-config.runtime-source-snapshot.test.ts
- src/cli/capability-cli.test.ts
- src/cli/capability-cli.ts
- src/cli/command-config-resolution.test.ts
- src/cli/command-config-resolution.ts
- src/cli/command-secret-gateway.test.ts
- src/cli/command-secret-gateway.ts
- src/cli/command-secret-resolution.coverage.test.ts
- src/cli/command-secret-targets.import.test.ts
- src/cli/command-secret-targets.test.ts
- src/cli/command-secret-targets.ts
- src/cli/gateway-cli/lifecycle.runtime.ts
- src/cli/gateway-cli/run-loop.test.ts
- src/cli/gateway-cli/run-loop.ts
- src/cli/qr-cli.ts
- src/commands/models/load-config.test.ts
- src/commands/models/load-config.ts
- src/gateway/method-scopes.test.ts
- src/gateway/method-scopes.ts
- src/gateway/methods/core-descriptors.ts
- src/gateway/methods/descriptor.ts
- src/gateway/methods/registry.test.ts
- src/gateway/methods/registry.ts
- src/gateway/server-aux-handlers.ts
- src/gateway/server-close.test.ts
- src/gateway/server-close.ts
- src/gateway/server-methods-list.test.ts
- src/gateway/server-methods-list.ts
- src/gateway/server-methods.ts
- src/gateway/server-methods/models-auth-status.test.ts
- src/gateway/server-methods/models-auth-status.ts
- src/gateway/server-methods/secrets.ts
- src/gateway/server-reload-handlers.test.ts
- src/gateway/server-reload-handlers.ts
- src/gateway/server-startup-post-attach.test.ts
- src/gateway/server-startup-post-attach.ts
- src/gateway/server.device-token-rotate-authz.test.ts
- src/gateway/server.impl.ts
- src/gateway/server.node-pairing-authz.test.ts
- src/infra/fs-safe.ts
- src/infra/infra-runtime.test.ts
- src/infra/restart.deferral-timeout.test.ts
- src/infra/restart.ts
- src/infra/transport-ready.test.ts
- src/infra/transport-ready.ts
- src/media/qr-terminal.render.test.ts
- src/media/qr-terminal.test.ts
- src/media/qr-terminal.ts
- src/plugin-sdk/channel-test-helpers.ts
- src/plugin-sdk/security-runtime.ts
- src/secrets/runtime-command-secrets.test.ts
- src/secrets/runtime-command-secrets.ts
- src/types/qrcode.d.ts

This page explains how the OpenClaw Gateway authenticates clients and authorizes access to RPC methods and HTTP surfaces. The system implements a multi-layered security model centered around a single trusted operator managing a personal AI assistant infrastructure.

## Overview

OpenClaw security guidance assumes a **personal assistant** deployment: one trusted operator boundary, potentially many agents. It assumes a single trusted operator who may manage multiple agents and devices.

1. Transport Authentication : Proving identity to the Gateway (token, password, or none) at the connection level src/gateway/auth.ts 15-30
2. Protocol Handshake : Validating client identity and requested scopes during the connection exchange.
3. Method Authorization : Controlling RPC access via granular scopes (READ, WRITE, ADMIN, PAIRING, APPROVALS) src/gateway/auth.ts 133-145
4. Rate Limiting : Protecting the control plane via auth throttling and budget management src/gateway/auth-rate-limit.ts 55-56
5. Sensitive Data Redaction : Automatic scrubbing of identifiers and secrets from logs src/agents/openai-transport-stream.ts 27-28

**Sources**: [src/gateway/auth.ts15-145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L15-L145) [src/agents/openai-transport-stream.ts27-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.ts#L27-L28) [src/gateway/auth-rate-limit.ts55-56](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth-rate-limit.ts#L55-L56)

## Authentication Modes

The Gateway supports several authentication modes resolved by `resolveGatewayAuth` from the configuration [src/gateway/auth.ts15](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L15-L15)

### Authentication Resolution

The Gateway determines the authentication state by evaluating configuration against the environment. For automated installations, the system handles the logic of finding existing tokens or auto-generating new ones if missing.

**Gateway Connection Auth Flow**

```

```

**Sources**: [src/gateway/auth.ts15-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L15-L30) [docs/gateway/openai-http-api.md32-34](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/openai-http-api.md?plain=1#L32-L34)

## Authorization Scopes

OpenClaw enforces scope-based access control for Gateway RPC methods. Scopes define the granular permissions required to execute specific operations.

### Scope Enforcement

The system uses a hierarchy where `ADMIN_SCOPE` effectively grants all other permissions [src/gateway/auth.ts133](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L133-L133) Core gateway methods are classified in `CORE_GATEWAY_METHOD_SPECS` with their required scopes [src/gateway/methods/core-descriptors.ts20-134](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L20-L134) For example, `config.set` requires `operator.admin` [src/gateway/methods/core-descriptors.ts48](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L48-L48) while `health` only requires `operator.read` [src/gateway/methods/core-descriptors.ts21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L21-L21)

For the OpenAI-compatible HTTP surface, the Gateway applies specific logic:

- If using token or password auth, it restores the full operator default scope set, ignoring narrower x-openclaw-scopes headers docs/gateway/openai-http-api.md 66-72
- Trusted identity modes (like trusted-proxy ) honor the x-openclaw-scopes header when present docs/gateway/openai-http-api.md 73-77

**Authorization Entity Mapping**

```

```

**Sources**: [src/gateway/auth.ts130-145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L130-L145) [src/gateway/methods/core-descriptors.ts20-134](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L20-L134) [docs/gateway/openai-http-api.md66-77](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/openai-http-api.md?plain=1#L66-L77)

## Device Pairing and Token Rotation

### Device Pairing

Remote nodes establish trust through pairing. This process is governed by the `operator.pairing` scope [src/gateway/auth.ts136](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L136-L136) Mobile clients are encouraged to use the device-pairing flow so they do not need to store shared HTTP tokens [docs/gateway/openai-http-api.md86-87](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/openai-http-api.md?plain=1#L86-L87) The `node` scope is also used for specific node-to-gateway operations like `skills.bins` [src/gateway/methods/core-descriptors.ts116](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L116-L116)

### Shared Auth Generation

The Gateway manages `SharedGatewaySessionGenerationState` to handle client session validity across configuration reloads [src/gateway/server-shared-auth-generation.ts93-98](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-shared-auth-generation.ts#L93-L98) When configuration changes, `disconnectStaleSharedGatewayAuthClients` ensures that clients using outdated credentials are forced to re-authenticate [src/gateway/server-reload-handlers.ts50-54](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-reload-handlers.ts#L50-L54) The generation is updated via `setCurrentSharedGatewaySessionGeneration` during config writes [src/gateway/server-shared-auth-generation.ts51](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-shared-auth-generation.ts#L51-L51)

### Internal Handoffs

For sensitive operations like bash tool execution approvals, the system uses internal runtime handoff tokens. Followup results register elevated defaults behind internal tokens to maintain the security boundary [src/agents/bash-tools.exec-host-shared.test.ts133-150](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-shared.test.ts#L133-L150)

**Sources**: [src/gateway/auth.ts136](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth.ts#L136-L136) [src/gateway/server-shared-auth-generation.ts93-98](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-shared-auth-generation.ts#L93-L98) [src/gateway/server-reload-handlers.ts50-54](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-reload-handlers.ts#L50-L54) [src/gateway/methods/core-descriptors.ts116](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L116-L116)

## Provider Authentication Warming

The Gateway performs "warming" of model provider authentication states to ensure high performance during model listing and selection. This avoids expensive external CLI probing or plugin discovery on the request hot path.

- Warming Process : Triggered at startup src/gateway/server-startup-post-attach.ts 179-186 and during hot reloads src/gateway/server-reload-handlers.ts 93-97
- Implementation : warmCurrentProviderAuthState populates a PreparedProviderAuthState map src/agents/model-provider-auth.ts 85-89
- Worker Isolation : Large-scale auth discovery can be offloaded to a worker thread via warmCurrentProviderAuthStateOffMainThread to prevent blocking the event loop src/agents/model-provider-auth.ts 70-78
- Fingerprinting : Cached states are tied to a configFingerprint to ensure they are invalidated if the OpenClawConfig changes src/agents/model-provider-auth.ts 131-142

**Auth Warming Data Flow**

```

```

**Sources**: [src/agents/model-provider-auth.ts30-48](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L30-L48) [src/agents/model-provider-auth.ts85-156](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L85-L156) [src/gateway/server-startup-post-attach.ts179-186](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L179-L186) [src/gateway/server-reload-handlers.ts93-97](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-reload-handlers.ts#L93-L97)

## Rate Limiting & Safety Guards

The Gateway implements several layers of protection:

1. Auth Rate Limiter : The AuthRateLimiter class tracks authentication attempts to prevent brute-force attacks src/gateway/auth-rate-limit.ts 56 If gateway.auth.rateLimit is configured, too many failures result in a 429 Too Many Requests response docs/gateway/openai-http-api.md 49
2. Secret Redaction : Transport payloads are scrubbed using redaction utilities to prevent leaking API keys or internal request IDs in logs src/agents/openai-transport-stream.ts 27-28
3. SSRF Protection : Outbound requests from the agent runtime are wrapped in buildGuardedModelFetch to prevent Server-Side Request Forgery src/agents/openai-transport-stream.ts 67-68
4. Event Loop Health : The createGatewayEventLoopHealthMonitor ensures the Gateway remains responsive under load, which is critical for maintaining auth verification performance src/gateway/server.impl.ts 99

**Sources**: [src/gateway/auth-rate-limit.ts56](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/auth-rate-limit.ts#L56-L56) [docs/gateway/openai-http-api.md49](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/openai-http-api.md?plain=1#L49-L49) [src/agents/openai-transport-stream.ts27-68](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openai-transport-stream.ts#L27-L68) [src/gateway/server.impl.ts99](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L99-L99)
