Document OpenClaw proxy as public endpoint

api-reference/agents.mdx

@@ -271,7 +271,7 @@
 DELETE /api/agents/:id
 ```
 
 Stops and removes the agent's local Docker container, deallocates its port, and removes its metadata file. Requires bearer token authentication (backend).
 
 ### Response
 
@@ -301,7 +301,7 @@
 
 <Note>The agent is created immediately with a `provisioning` status and transitions to `running` once the backend deployment endpoint confirms the deployment. If deployment fails, the status changes to `error`.</Note>
 
 <Note>The provisioning endpoint calls `POST /api/deployments` on the backend to deploy the agent as a Railway service. The request includes a 15-second timeout. When the model is set to `claude-opus-4-6`, the AI provider is automatically set to `anthropic`; otherwise it falls back to the provider specified in the agent configuration (default: `openrouter`). The plan sent to the backend defaults to `label` when no tier is specified.</Note>
 
 ### Request body
 
@@ -314,7 +314,7 @@
 
 <Note>The web proxy enforces agent limits based on the subscription tier (`starter`: 1, `pro`: 3, `enterprise`: 100). The backend provisioning route (`POST /api/provision`) enforces its own limits (`solo`: 1, `collective`: 3, `label`: 10, `network`: unlimited). These provisioning limits determine how many agents you can create. The plan middleware enforces separate per-request limits for AI model access and skill usage. The limit cannot be overridden in the request body.</Note>
 
 <Note>The backend also accepts legacy plan aliases for resource allocation: `underground` (2 GB / 1 CPU), `starter` (2 GB / 1 CPU), `pro` (4 GB / 2 CPU), `scale` (8 GB / 4 CPU), `enterprise` (16 GB / 4 CPU), and `white_glove` (32 GB / 8 CPU). These are accepted in addition to the standard plan names (`solo`, `collective`, `label`, `network`) when determining container resource limits.</Note>
 
 ### Admin bypass
 
@@ -403,7 +403,7 @@
 | `version` | string | Clone service version |
 | `protocol` | string | Payment protocol used |
 | `clonePrice` | string | Current price to clone an agent |
 | `chainId` | number | Blockchain chain ID for payments |
 
 ## Preflight checks (deprecated)
 
@@ -757,7 +757,7 @@
 | `backupPath` | string \| null | Path to the pre-update backup archive |
 | `openclawVersion` | string | Current OpenClaw runtime version |
 
 <Note>When the new service fails to start, the endpoint reverts to `previousImage`. The caller still receives a `500` error, but the agent is restored to its prior working state. The pre-update backup remains available at `backupPath` for manual recovery if needed.</Note>
 
 #### Errors
 
@@ -888,7 +888,7 @@
 
 ## Agent verification
 
 Agents can be verified using multiple verification types: `eas` (Ethereum Attestation Service), `coinbase`, `ens`, or `webauthn`.
 
 ### Get verification status
 
@@ -927,7 +927,7 @@
 | `verifierAddress` | string | No | Address of the verifying wallet |
 | `metadata` | object | No | Additional verification metadata |
 
 <Note>The web API always sets `verified: true` on success. When calling the backend directly, you can pass `verified`, `verifierAddress`, and `metadata` explicitly.</Note>
 
 #### Response
 
@@ -988,11 +988,11 @@
 The endpoint provisions agents using a two-path strategy, tried in order:
 
 1. **Backend service** — the request is forwarded to the backend Express service (`BACKEND_API_URL`). If a fallback URL is configured (`BACKEND_API_FALLBACK_URL`), it is tried next if the primary fails. Non-JSON responses (such as HTML error pages from a proxy or load balancer) are detected and treated as failures, avoiding the previous "Unexpected token" parsing errors.
 2. **Railway direct provisioning** — when all backend URLs fail or are not configured, the endpoint falls back to provisioning the agent container directly via the Railway GraphQL API. This path requires `RAILWAY_API_KEY`, `RAILWAY_PROJECT_ID`, and `RAILWAY_ENVIRONMENT_ID` to be set. The Railway path creates a new Railway service, injects environment variables, generates a public domain via the `serviceDomainCreate` mutation, and then triggers a deployment. The domain is generated before the deploy so that the service has a routable public URL immediately.
 
 If both paths fail, the endpoint returns a `502` error.
 
 When the backend path succeeds and `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET` are configured, the backend creates a real Mux live stream via the Mux API with public playback policy. When Mux credentials are not configured, placeholder streaming credentials are returned instead. The Railway direct path does not create Mux streams.
 
 ### Request body
 
@@ -1034,7 +1034,7 @@
 }
 ```
 
 <Note>The backend path returns `success`, `userId`, `subdomain`, `url`, `streamKey`, and `liveStreamId`. The full response shape from the backend provisioning service is shown below.</Note>
 
 #### Railway direct path response
 
@@ -1056,15 +1056,15 @@
 | `url` | string | The Railway service URL for the agent. This URL is generated by Railway via the `serviceDomainCreate` API and may not follow a predictable pattern. If domain generation fails, the URL falls back to `https://agentbot-agent-{agentId}.up.railway.app`. |
 | `status` | string | Always `deploying` for the Railway path. The agent service is created and the deployment is triggered, but it may not be ready to receive traffic immediately. |
 
 <Note>The Railway path does not return `subdomain`, `streamKey`, or `liveStreamId`. These fields are only available when the backend Express service handles the request. The `status` field is `deploying` (not `active`) because the Railway service is created asynchronously.</Note>
 
 <Note>On a successful provision through either path, the proxy persists the `openclawUrl` and `openclawInstanceId` to the user record in the database. You can retrieve these values later using [`GET /api/user/openclaw`](#get-user-openclaw-instance).</Note>
 
 ### Full backend response
 
 When calling the backend provisioning service directly, the response includes additional fields. The backend returns `200 OK` on success (not `201 Created`).
 
 <Warning>Channel tokens (`telegramToken`, `discordBotToken`, `whatsappToken`) are no longer included in the provision response. Tokens are write-only secrets — they are stored server-side but never returned to the caller.</Warning>
 
 ```json
 {
@@ -1140,7 +1140,7 @@
 | 402 | Agent limit reached for your plan. The response body includes a `code` field set to `AGENT_LIMIT_REACHED`, along with `current` (current agent count) and `limit` (maximum allowed) fields. Provisioning limits: `solo` 1, `collective` 3, `label` 10, `network` unlimited. |
 | 500 | Internal server error |
 | 502 | Provisioning service unavailable. All backend URLs failed or returned non-JSON/error responses, and Railway direct provisioning also failed or is not configured. The error message from the last attempted path is included in the response. |
 | 503 | Provisioning is temporarily disabled (kill switch active) or provisioning service misconfigured. |
 
 ### AI provider defaults
 
@@ -1174,7 +1174,7 @@
 
 Each provider includes a fallback model in the service config that is used automatically when the primary model is unavailable or returns an error.
 
 <Note>`minimax` is available as a fallback in the provider configuration map but is not currently accepted as a value for the `aiProvider` request parameter. Passing `minimax` as `aiProvider` returns a `400` validation error. This provider may be enabled in a future release.</Note>
 
 ## Channel configuration
 
@@ -1209,7 +1209,7 @@
 |---------|-------|-------------|
 | `dmPolicy` | `allowlist` or `pairing` | `allowlist` when owner IDs are provided, `pairing` otherwise |
 | `dm.enabled` | `true` | Accept direct messages |
 | `dm.groupEnabled` | `false` | Group DMs are disabled |
 | `historyLimit` | `20` | Number of messages retained in context |
 | `streaming` | `partial` | Enable partial message streaming |
 | `retry.attempts` | `3` | Maximum retry attempts |
@@ -1289,6 +1289,32 @@
 | 401 | Unauthorized |
 | 500 | Deployment failed. When the Railway API is not reachable, the error message indicates that provisioning is unavailable. Check the [backend health endpoint](/api-reference/health#backend-health-check) to verify Railway API availability before deploying. |
 
+## OpenClaw proxy (backend)
+
+```http
+ALL /api/openclaw/proxy/:agentId/*
+```
+
+Transparently proxies HTTP and WebSocket requests to an agent's OpenClaw Control UI running on the internal network. The proxy forwards requests to the agent's internal address and rewrites the path so the OpenClaw UI receives requests at its expected root.
+
+**No bearer token authentication is required.** This route is exempt from the backend API key middleware. OpenClaw handles its own token and password authentication on the proxied service, so users can access the Control UI directly.
+
+WebSocket connections to this path are also proxied, allowing real-time communication with the OpenClaw instance.
+
+### Path parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agentId` | string | Agent identifier (alphanumeric, hyphens, and underscores only) |
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 502 | The OpenClaw instance is unreachable |
+
+<Note>The `agentId` parameter is sanitized to alphanumeric characters, hyphens, and underscores. Any other characters are stripped before the proxy target is resolved.</Note>
+
 ## OpenClaw version (backend)
 
 ```http
@@ -1307,7 +1333,7 @@
 }
 ```
 
 <Note>`deployedAt` returns the current server time when the request is made, not the actual deployment time of the OpenClaw runtime.</Note>
 
 ## List instances (backend)
 
@@ -1340,7 +1366,7 @@
 }
 ```
 
 <Note>The `metadata` object contains the full agent metadata from the on-disk JSON file and may include additional fields beyond those shown (for example, `aiProvider`, `port`, `subdomain`, `url`, `status`, and `config`).</Note>
 
 ### Errors
 
@@ -1596,7 +1622,7 @@
 |-------|------|----------|-------------|
 | `action` | string | Yes | `set-credential` |
 | `key` | string | Yes | Credential key (for example, `anthropic`, `telegram`) |
 | `value` | string | No | Credential value. When omitted, the credential is marked as unconfigured. |
 
 ```json
 {

api-reference/auth.mdx

@@ -5,7 +5,7 @@
 
 # Authentication API
 
 Manage user authentication, password resets, wallet sign-in, Farcaster identity, and token gating.
 
 ## Auth middleware
 
@@ -15,6 +15,8 @@
 
 Endpoints such as `/api/deployments`, `/api/openclaw/instances`, and per-agent lifecycle routes require a shared API key passed as a bearer token. The key is compared against the configured `INTERNAL_API_KEY` using a timing-safe comparison.
 
+<Note>The `/api/openclaw/proxy/*` route is exempt from bearer token authentication. OpenClaw's own token and password authentication handles access control on the proxied service. See the [OpenClaw proxy](/api-reference/agents#openclaw-proxy-backend) endpoint for details.</Note>
+
 ```bash
 curl -X GET https://backend.example.com/api/openclaw/instances \
   -H "Authorization: Bearer YOUR_INTERNAL_API_KEY"
@@ -241,7 +243,7 @@
 
 On success the endpoint:
 1. Exchanges the authorization code for an access token.
 2. Fetches the user's email and name from the Google userinfo API.
 3. Creates a new user if no account with that email exists (automatic account linking applies when a matching email is found).
 4. Links a Google `Account` record to the user for dual-auth compatibility. If the user already has a linked Google account, this step is skipped. The Account record stores the OAuth access token, refresh token, and token metadata so the user can sign in with either email/password or Google.
 5. Creates a session and sets the `agentbot-session` cookie.
@@ -266,7 +268,7 @@
 POST /api/security/risc
 ```
 
 Receives security event tokens from Google via the [Cross-Account Protection (RISC)](https://developers.google.com/identity/protocols/risc) protocol. This is the primary receiver for Google security events. It validates the SET JWT, deduplicates events, and takes targeted action depending on the event type.
 
 <Warning>This endpoint is intended to be called by Google's RISC infrastructure, not by application clients. You do not need to call it directly.</Warning>
 
@@ -278,8 +280,8 @@
 |-------|------|-------------|
 | `iss` | string | Issuer — must be `https://accounts.google.com/` |
 | `aud` | string | Audience — must match a configured `GOOGLE_CLIENT_ID` |
 | `jti` | string | Unique event identifier used for deduplication |
 | `events` | object | Map of event URIs to event data. Each event may include `subject.sub` (Google subject ID), `subject.email`, and `reason`. |
 
 ### Token validation
 
@@ -289,13 +291,13 @@
 2. Checks the audience matches one of the configured Google client IDs
 3. Fetches Google's signing keys from the JWKS endpoint discovered via `https://accounts.google.com/.well-known/risc-configuration` (keys are cached for 24 hours)
 4. Matches the signing key by the `kid` header claim
 5. Verifies the RS256 signature using the Web Crypto API (`crypto.subtle`) with the matched RSA public key
 
 If validation fails, the endpoint returns `400`.
 
 ### Event deduplication
 
 Events are deduplicated using the `jti` claim. Each processed event is stored in the `risc_events` table. If an event with the same `jti` has already been processed, it is acknowledged but not acted on again.
 
 ### Supported event types
 
@@ -353,7 +355,7 @@
 POST /api/auth/google/risc
 ```
 
 Receives security event notifications from Google via the [RISC (Risk Incident Sharing and Collaboration)](https://developers.google.com/identity/protocols/risc) protocol. This is the legacy endpoint — new integrations should use [`POST /api/security/risc`](#cross-account-protection-receiver) instead, which adds token validation, event deduplication, and more granular event handling.
 
 <Warning>This endpoint is intended to be called by Google's RISC infrastructure, not by application clients. You do not need to call it directly.</Warning>
 
@@ -365,7 +367,7 @@
 |-------|------|-------------|
 | `iss` | string | Issuer (Google) |
 | `sub` | string | Subject identifier — the user's email address |
 | `events` | object | Map of event URIs to event data |
 
 ### Supported event types
 
@@ -402,7 +404,7 @@
 POST /api/wallet-auth
 ```
 
 Sign in using an Ethereum wallet via [Sign-In with Ethereum (SIWE)](https://eips.ethereum.org/EIPS/eip-4361). This flow is designed for Coinbase Smart Wallets on Base and supports ERC-6492 signature verification for pre-deployed wallets.
 
 <Note>This endpoint replaced the previous NextAuth wallet callback (`/api/auth/callback/wallet`). If you are migrating from an older integration, update your wallet sign-in requests to use `/api/wallet-auth`.</Note>
 
@@ -411,9 +413,9 @@
 ### How it works
 
 1. The client requests a nonce from [`GET /api/auth/nonce`](#get-nonce).
 2. The client opens the Base Account SDK popup and requests a SIWE signature on Base Mainnet.
 3. The wallet address, SIWE message, and signature are sent to `POST /api/wallet-auth`.
 4. The server verifies the signature using viem (which handles ERC-6492 for smart wallets).
 5. If no account exists for the wallet address, a new user is created automatically.
 6. If an account with the same wallet-derived email already exists, the wallet is linked to the existing account.
 
@@ -421,7 +423,7 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `address` | string | Yes | Ethereum wallet address (0x-prefixed) |
 | `message` | string | Yes | The full SIWE message string |
 | `signature` | string | Yes | The wallet signature of the SIWE message (0x-prefixed) |
 
@@ -646,9 +648,9 @@
 | 404 | User not found |
 | 429 | Too many requests |
 
 ## Farcaster authentication
 
 ### Verify Farcaster identity
 
 ```http
 POST /api/auth/farcaster/verify
@@ -658,14 +660,14 @@
 GET /api/auth/farcaster/verify
 ```
 
 The `GET` method returns endpoint metadata. The `POST` method verifies a Farcaster ID token and optionally checks `$RAVE` token gating on Base.
 
 #### Request body
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `fidToken` | string | Yes | Farcaster ID token |
 | `address` | string | No | Ethereum address for token gating check |
 
 #### Response
 
@@ -684,8 +686,8 @@
 
 | Claim | Type | Description |
 |-------|------|-------------|
 | `fidToken` | string | Farcaster ID token (truncated to 64 characters) |
 | `address` | string | Ethereum address from the request |
 | `verified` | boolean | Always `true` on success |
 | `iat` | number | Issued-at timestamp (Unix seconds) |
 | `exp` | number | Expiry timestamp (24 hours after issuance) |
@@ -698,11 +700,11 @@
 
 | Code | Description |
 |------|-------------|
 | 401 | Missing Farcaster ID token |
 | 403 | Token gating failed (insufficient `$RAVE` balance). Response includes `required`, `minBalance` fields |
 | 500 | Verification failed |
 
 ### Refresh Farcaster token
 
 ```http
 POST /api/auth/farcaster/refresh
@@ -747,14 +749,14 @@
 POST /api/auth/token-gating/verify
 ```
 
 Checks whether a wallet holds sufficient `$RAVE` tokens on Base mainnet.
 
 #### Request body
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `fid` | string | Yes | Farcaster ID |
 | `address` | string | Yes | Ethereum address (0x-prefixed, 42 characters) |
 
 #### Response
 
@@ -776,7 +778,7 @@
 
 | Code | Description |
 |------|-------------|
 | 400 | Missing fid or address, or invalid Ethereum address |
 | 500 | Verification failed |
 
 ### Verify token access (GET)
@@ -789,7 +791,7 @@
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `address` | string | Yes | Ethereum address (0x-prefixed, 42 characters) |
 
 #### Response
 

api-reference/overview.mdx

@@ -1,11 +1,11 @@
 ---
 title: API reference
 description: "Complete API reference for Agentbot"
 ---
 
 # API reference
 
 Complete API reference for Agentbot.
 
 ## Base URL
 
@@ -15,7 +15,7 @@
 
 ## Authentication
 
 Agentbot supports multiple authentication methods depending on the endpoint.
 
 ### Session authentication
 
@@ -214,8 +214,8 @@
 | `/api/auth/reset-password` | POST | Reset password |
 | `/api/security/risc` | GET | Cross-Account Protection endpoint health check |
 | `/api/security/risc` | POST | Receive Google Cross-Account Protection (RISC) security events |
 | `/api/auth/farcaster/verify` | GET, POST | Verify Farcaster identity (GET returns endpoint metadata) |
 | `/api/auth/farcaster/refresh` | GET, POST | Refresh Farcaster token (GET returns endpoint metadata) |
 | `/api/auth/token-gating/verify` | GET, POST | Verify token gating access |
 | `/api/dashboard/cost` | GET | Get aggregated cost dashboard data (by agent, model, and day) |
 | `/api/billing` | GET | Get billing info |
@@ -226,8 +226,8 @@
 | `/api/scheduled-tasks` | PUT | Update a scheduled task |
 | `/api/scheduled-tasks` | DELETE | Delete a scheduled task |
 | `/api/checkout/verify` | GET | Verify a Stripe checkout session and activate subscription |
 | `/api/stripe/checkout` | GET | Redirect to Stripe checkout (accepts `plan` query param: `solo`, `collective`, `label`, `network`). Prices are in GBP. |
 | `/api/stripe/credits` | GET | Redirect to Stripe credit purchase (accepts `price` query param) |
 | `/api/stripe/storage-upgrade` | POST | Upgrade storage plan |
 | `/api/metrics/:userId/historical` | GET | Get historical time-series metrics (backend only) |
 | `/api/metrics/:userId/performance` | GET | Get current performance metrics (backend only) |
@@ -249,15 +249,16 @@
 | `/api/openclaw/version` | GET | Get OpenClaw runtime version (backend only) |
 | `/api/openclaw/instances` | GET | List running agent instances (backend only, requires auth) |
 | `/api/openclaw/instances/:id/stats` | GET | Get instance container stats (backend only, requires auth) |
+| `/api/openclaw/proxy/:agentId/*` | ALL | Proxy to an agent's OpenClaw Control UI (backend only, no auth — OpenClaw handles its own authentication) |
 | `/api/deployments` | POST | Deploy an agent container (backend only, requires auth) |
 | `/api/models` | GET | List available OpenRouter AI models |
 | `/api/coinbase` | GET | Get Coinbase CDP configuration and supported features |
 | `/api/coinbase` | POST | Coinbase CDP wallet actions (create_wallet, get_balance, create_payment, onramp) |
 | `/api/basename` | GET | Resolve a Base Name (.base.eth) for a wallet address |
 | `/api/basefm/live` | GET | List active Mux live streams |
 | `/api/basefm/streams` | POST | Create a Mux live stream (RAVE token-gated) |
 | `/api/generate-video` | POST | Generate and upload a video (requires session) |
 | `/api/webhooks/mux` | POST | Mux webhook receiver (signature-verified) |
 | `/api/webhooks/resend` | POST | Resend email webhook — inbound email processing and outbound event tracking (sent, delivered, bounced, opened, clicked, complained) |
 | `/api/webhooks/railway-status` | POST | Railway platform status and deployment webhook receiver (persists to Redis) |
 | `/api/webhooks/railway-status` | GET | Poll last-known Railway status from Redis |
@@ -297,7 +298,7 @@
 | `/api/summarize` | POST | Summarize a URL — returns title, description, headings, paragraphs, word count (web summarizer service) |
 | `/api/extract` | POST | Extract links, images, and Open Graph metadata from a URL (web summarizer service) |
 | `/api/clawmerchants` | GET | List available ClawMerchants data feeds, or fetch a specific feed by `feed` query parameter |
 | `/api/debug` | POST | Execute an allowlisted diagnostic command against an agent |
 | `/api/config` | GET | Get current agent configuration and backup list |
 | `/api/config` | POST | Save a new agent configuration (auto-backs up the previous config) |
 | `/api/config` | PUT | Restore a previous configuration from a backup |
@@ -306,14 +307,14 @@
 | `/api/market-intel` | GET | Live competitive landscape, infrastructure signals, and market opportunities |
 | `/v1/models` | GET | List all available models (OpenAI-compatible, no auth required) |
 | `/v1/models/:model` | GET | Get a single model by ID (OpenAI-compatible, no auth required) |
 | `/v1/embeddings` | POST | Generate embeddings (OpenAI-compatible, proxied to OpenRouter, requires auth) |
 | `/health` | GET | Backend health check (no auth required) |
 | `/install` | GET | Download the Home mode installation shell script |
 | `/link` | GET | Download the Link mode installation shell script |
 
 ## SDK
 
 Use the Agentbot SDK:
 
 ```bash
 npm install @agentbot/sdk