Agent native admin UI

Agent native admin UI access lets an authorized operator open the selected Agent's native OpenClaw administration UI from the platform console. It is an explicit pilot capability for trusted operators. It exposes the stock native administrator surface for one Agent gateway; it does not create an OCE-managed configuration editor.

The feature is disabled by default. When enabled, the console shows Native admin UI on the Agent detail tabs only for callers with exact Agent administer permission. Opening the Agent host uses the operator's ordinary OCE console session cookie, resolves the exact Agent represented by that host, then serves native HTTP and WebSocket traffic through OCC.

Requirements

• agentNativeAdmin.enabled: true in Helm, which sets OCC_AGENT_NATIVE_ADMIN_ENABLED=true on the API.
• agentNativeAdmin.domain set to the Agent host suffix, such as agents.oce.example.com, without scheme, wildcard, port, or path. Helm passes it as OCC_AGENT_NATIVE_ADMIN_DOMAIN. Use a previously unused DNS suffix for the first pilot rollout; the proxy blocks new service-worker registration but does not evict service workers that a prior experiment registered on the same origin.
• agentNativeAdmin.sharedCookieDomain set to the explicit shared OCE session cookie parent domain, such as oce.example.com. Helm passes it as OCC_AUTH_COOKIE_DOMAIN when agentNativeAdmin.enabled is true. The console host and Agent host suffix must both be inside this parent on DNS-label boundaries. Public suffixes, malformed domains, and DNS-label boundary violations fail closed. The Agent suffix may equal the cookie domain; OCC excludes its configured Console hostname from native proxy routing.
• gatewayRouting.enabled: true. Helm rejects native admin enablement without private gateway routing because the API process must reach each Agent gateway through the private route.
• OCC_AUTH_BASE_URL set to the public OCC origin that serves the console, for example https://console.oce.example.com.
• Better Auth cookie configuration using the shared cookie parent domain while preserving Secure, HttpOnly, appropriate SameSite, CSRF, and trusted-origin protections. A domain-scoped cookie cannot use a host-only __Host- prefix. The shared-domain session uses the openclaw_occ_shared cookie prefix and clears prior host-only openclaw_occ and openclaw_occ_shared session-cookie names during sign-in/sign-out migration. When native admin is disabled, OCC ignores leftover shared-cookie-domain configuration and keeps the legacy host-only openclaw_occ session cookie scope.
• Private Agent gateway routing configured through Gateway routing with Envoy.
• The Agent must be running, have an active revision, and expose a ComputeDriver.getGatewayEndpoint value that can be mapped from private wss: to private https:.
• The native Agent configuration must keep the trusted-proxy occ-workspace-files identity with operator.admin, enable native controlUi, allow the derived Agent origin, and enable trusted-proxy admin device auto-approval. The support check rejects token auth, disabled device auth, and host-header origin fallback.

Authorization and availability

GET /namespaces/:namespaceId/agents/:agentId/native-admin is the console-facing availability check. It is a protected OCC API route with a human session, exact Agent administer authorization, and exact Agent existence. OCC verifies that authorization boundary before returning any feature status, including disabled; Agent read, Agent operate, native device credentials, native tokens, service keys for unrelated principals, and possession of a derived Agent host do not grant this API route.

The response reports:

A stopped Agent with no active revision returns only status: "stopped", including before its first deployment and after stop reconciliation clears its active revision. A stopped Agent with a selectable active revision still includes its target fields. If a desired-running Agent has no active revision, OCC returns unavailable in the success envelope so the console can show a retryable dependency state. Malformed requests, denied IAM access, missing sessions, and failures outside that availability branch use the normal protected-route error envelope.

Agent host identity

OCC derives a stable browser host from the Installation ID, Namespace ID, Agent ID, and configured agentNativeAdmin.domain. The hostname is opaque and must not be reused for another Agent identity. The derived host is separate from the console origin, which gives each Agent UI its own browser origin.

An Agent URL uses the derived host directly:

https://agent-<opaque-hash>.<agentNativeAdmin.domain>/

The host hash is not reversible, so native-host admission resolves the host to the exact Agent using existing platform state. Unknown hosts, wrong suffixes, deleted Agents, and hosts that do not map to exactly one Agent fail closed. This lookup does not require a persistent registry or cache.

The private upstream base remains the Compute Driver's existing gateway endpoint:

wss://<private-host>/namespaces/<namespaceId>/agents/<agentId>

For browser proxying, OCC maps that value to the same authority and Agent path over https:. Workspace-file access continues to use the original wss: endpoint. Native admin HTTP requests and WebSocket upgrades both pass through the OCC API process before reaching the private gateway. The HTTP proxy blocks native service-worker script requests and appends worker-src 'none' to proxied Content Security Policy so Agent content cannot register a browser service worker on the isolated Agent origin.

Shared session boundary

The console and Agent hosts share the ordinary OCE session cookie through the configured cookie parent domain. That expands the cookie trust boundary: every host under the console and Agent subdomains that can receive the cookie must be a trusted OCE ingress endpoint. Public Agent hosts route to OCC, not Envoy or tenant gateway Services. OCC strips browser cookies, Authorization, API keys, forwarded identity, scope headers, and native Set-Cookie before forwarding upstream, so the native gateway never receives the OCE session cookie.

Native chat or other activity in the Agent tab does not renew the console session. Session expiry, logout, session revocation, permission removal, pilot disablement, Agent unavailability, or a revision change closes active WebSockets during the authorization lease. Reconnecting uses the same stable Agent host and the current active revision when the shared OCE session, exact Agent permission, and native configuration remain valid.

Native authority and drift

The native admin UI runs with the same shared native trusted-proxy identity used by workspace files: occ-workspace-files with operator.admin. OCC attributes availability, proxy admission, and socket closure checks to the human session and exact Agent IAM decision. The native gateway sees the shared service identity, not a per-human native account.

Native admin changes affect gateway-local state outside OCE Configurations and immutable AgentRevisions. Manage durable configuration through OCE. In the Kubernetes pilot, native configuration edits affect a Pod-local copy that resets from the managed snapshot when the Pod is recreated or the Agent is redeployed. See Kubernetes managed native configuration for the opt-in predicate, mounts, and copy lifecycle.

Redeployment does not imply a factory reset of native files, conversations, device state, plugins, or other persistent gateway data.

Failure behavior

• Helm rendering fails when agentNativeAdmin.enabled is true without gatewayRouting.enabled.
• Startup fails with AGENT_NATIVE_ADMIN_INVALID when enablement, Agent domain, shared cookie domain, public origin, Better Auth cookie scope, or cookie-secret requirements are invalid.
• Availability returns stopped for a stopped Agent with no active revision; unavailable means OCC could not resolve the active revision or a dependency during selection. Gateway routing, unsupported native configuration, or a selected Compute Driver without a clean endpoint returns unsupported after OCC has an active revision and derived Agent origin.
• The console hides the panel for disabled and denied states, shows operator-readable stopped, unsupported, or unavailable messages, and opens the returned url in a new tab when available.
• Attributable IAM denials remain audit events for status checks, native-host proxy admission, and recurring WebSocket lease renewal. Those denial paths preserve the human IAM principal and exact Agent target instead of collapsing into unaudited dependency failures.
• Proxied HTTP and WebSocket requests strip browser credentials, service keys, forwarded headers, native identity/scope headers, and native Set-Cookie before responding through OCC. WebSocket upgrades require a non-null exact Agent Origin; accepted 101 connections audit websocket.connect with connectionId and websocket.close with the same connectionId plus closeReason, refresh authorization every 25 seconds, close when a lease check fails or takes more than 5 seconds, set closeReason to distinguish lifecycle, revocation, dependency, client, upstream, and shutdown paths, and are destroyed during API preClose.

Related

• Platform console
• Agents
• Authentication
• Gateway routing with Envoy
• Deploy native admin UI access
• Agent native admin UI flow