Deploy native admin UI access

Enable Agent native admin UI access only for a trusted-operator pilot. The feature lets exact Agent administrators open the stock native UI through OCC on an isolated per-Agent browser host using their ordinary OCE console session. For a local installation, use local development below. For an existing cluster, start with production installation and private Agent workspace routing.

Local development

Local setup prepares private routing and the browser endpoint. To opt a selected Agent into native admin access:

1. Create and deploy an Agent in the console, for example with the Standard Codex Preset. Wait for its active version. The account opening the UI needs administer permission on that exact Agent.
2. In the authenticated console session, follow Configure each Agent to obtain the exact data.origin and active revision ID from the status route. Include the returned port; do not construct or reuse another Agent's origin. An unsupported response can include the origin. If OCC cannot select an active revision, resolve that first.
3. Use Create new version → Configuration → Edit Configuration to merge the documented native policy and origin into the existing JSON. Review other Agents that share the Configuration: they use its new values on their next deployment. Preserve existing origins, gateway settings, and Secret references. Resolve explicit opt-outs or conflicting policy before changing them; do not silently replace them. Recheck the active revision before saving; if it changed, refresh and review the current Configuration again.
4. Save the Configuration and select Deploy new version. Once it is active, request status again and expect available with the same origin. Open Native admin UI on the Agent detail page. For stale drafts or uncertain saves, follow the Configuration editor recovery.

The first-Agent command creates a separate Agent with native UI disabled and refuses to reuse it after outside Configuration edits. Create a console-managed Agent for this native admin walkthrough.

Production requirements

• Private workspace routing already works for the target Agents. Helm rejects agentNativeAdmin.enabled: true unless gatewayRouting.enabled: true is also set.
• A public wildcard DNS name and HTTPS certificate route traffic to the OCC API Service, not to Envoy. Use a previously unused agentNativeAdmin.domain for the first pilot rollout; do not reuse a domain from prior native UI experiments because OCC does not evict already registered browser service workers.
• The configured Agent domain is separate from the console host and does not include a wildcard, scheme, port, or path.
• The configured agentNativeAdmin.sharedCookieDomain is the shared OCE session cookie parent domain. The console host and Agent domain must both be inside it on DNS-label boundaries, for example console.oce.example.com, agents.oce.example.com, and cookie domain oce.example.com. All matching subdomains that can receive the OCE session cookie must be trusted OCE ingress endpoints.
• Each pilot Agent uses native trusted-proxy authentication with occ-workspace-files granted operator.admin, native controlUi.enabled: true, the derived Agent origin in controlUi.allowedOrigins, and trusted-proxy admin device auto-approval.
• Operators who use the console have exact Agent administer permission.

Install on an existing cluster

The standard production values enable this feature. Replace their example domains with your reviewed domains and keep these values alongside private gateway routing:

gatewayRouting:  enabled: true agentNativeAdmin:  enabled: true  domain: agents.oce.example.com  sharedCookieDomain: oce.example.com

Expose the API Service through your existing public ingress layer. The chart does not create this route. This example shows the required shape; adapt the Ingress class, certificate, and selectors to your cluster:

apiVersion: networking.k8s.io/v1kind: Ingressmetadata:  name: occ-agent-native-admin  namespace: openclaw-system  annotations:    cert-manager.io/cluster-issuer: public-wildcardspec:  ingressClassName: public  tls:    - hosts:        - "*.agents.oce.example.com"      secretName: occ-agent-native-admin-wildcard-tls  rules:    - host: "*.agents.oce.example.com"      http:        paths:          - path: /            pathType: Prefix            backend:              service:                name: openclaw-enterprise-api                port:                  number: 8080

The API refuses protected requests carrying X-Forwarded-* or X-Real-IP headers, which ingress-nginx adds, unless the sender is a trusted proxy: set api.trustedProxy to preset ingress-nginx with the ingress-nginx Pod CIDR (profile installs: controlPlane.trustedProxy), or strip those headers at the ingress.

Allow ingress only to the API Pods selected for public browser traffic. Keep the Envoy Service private:

apiVersion: networking.k8s.io/v1kind: NetworkPolicymetadata:  name: allow-native-admin-browser-ingress-to-api  namespace: openclaw-systemspec:  podSelector:    matchLabels:      app.kubernetes.io/name: openclaw-enterprise      app.kubernetes.io/component: api  policyTypes: ["Ingress"]  ingress:    - from:        - namespaceSelector:            matchLabels:              kubernetes.io/metadata.name: ingress-nginx          podSelector:            matchLabels:              app.kubernetes.io/name: ingress-nginx      ports:        - protocol: TCP          port: 8080

Verify Helm passes these API environment variables:

OCC_AGENT_NATIVE_ADMIN_ENABLED=trueOCC_AGENT_NATIVE_ADMIN_DOMAIN=agents.oce.example.comOCC_AUTH_COOKIE_DOMAIN=oce.example.com

Verify that the Better Auth session cookie is emitted once at the shared domain with Secure, HttpOnly, and the configured SameSite behavior. On HTTPS, the shared cookie name is __Secure-openclaw_occ_shared.session_token; it cannot use a host-only __Host- prefix because it has a Domain attribute. Sign in again after changing an existing installation to the shared-cookie scope so OCC can clear old host-only openclaw_occ and openclaw_occ_shared session-cookie names before testing Agent hosts. If agentNativeAdmin.enabled is false, OCC ignores the shared cookie-domain value and keeps the legacy host-only openclaw_occ session cookie behavior.

Kubernetes Compute renders baseline gateway trust from Installation settings. Native admin availability still checks the explicit Agent policy below; keep its matching identity fields and opt-in settings in the saved Configuration.

Configure each Agent

Configure each pilot Agent after the API feature and wildcard route are enabled. Native admin availability requires the Agent's native configuration to trust the exact derived Agent origin. In an existing authenticated console browser session, open the status URL before the final compatible redeploy:

https://occ.example.com/namespaces/<namespaceId>/agents/<agentId>/native-admin

For browser devtools, the same check is:

await fetch("/namespaces/<namespaceId>/agents/<agentId>/native-admin", {  credentials: "include",}).then((response) => response.json());

A 200 response with data.status: "unsupported" can still include data.host, data.origin, data.activeRevisionId, and data.url. Copy the exact returned data.origin, including any port. In the console Configuration editor, merge the following JSON fields into the selected Agent's existing Configuration:

{  "gateway": {    "auth": {      "mode": "trusted-proxy",      "trustedProxy": {        "userHeader": "x-occ-identity",        "allowUsers": ["occ-workspace-files"],        "deviceAutoApprove": {          "enabled": true,          "scopes": ["operator.admin"]        }      },      "identityScopes": {        "occ-workspace-files": ["operator.admin"]      }    },    "controlUi": {      "enabled": true,      "allowedOrigins": ["https://agent-<opaque-hash>.agents.oce.example.com"]    }  }}

Keep existing model, Harness, channel, gateway, Secret reference, and allowed origin settings. Add the exact origin to any existing allowed origins. Review any other Agents sharing this Configuration before saving; they use its new values on their next deployment. Resolve explicitly disabled UI or device approval and conflicting authentication policy with the Configuration owner instead of silently overwriting them. The editor preserves Secret bindings, but its freshness check cannot prevent a concurrent write racing with the save.

Do not set unsupported gateway authentication fields, controlUi.dangerouslyDisableDeviceAuth, or controlUi.dangerouslyAllowHostHeaderOriginFallback. Deploy the updated Agent revision, then call the status route again and expect data.status: "available" with the same data.origin. A stopped Agent with no active revision returns only data.status: "stopped"; deploy it if native admin access is intended. If the response is data.status: "unavailable", check active revision selection before saving the native configuration; OCC cannot derive the Agent origin until it can select the active revision.

Keep durable configuration changes in OCE. For compatible Kubernetes gateways, native edits affect a Pod-local copy and are discarded when the Pod is replaced or the Agent is redeployed; persistent workspace and gateway data remain. See Kubernetes managed native configuration for the exact opt-in conditions and storage lifecycle.

Enable HTML previews

HTML previews use the runtime's separate sandbox listener. Exposing the native admin UI alone does not expose this listener: without sandbox routing, the browser may try the Agent hostname on port 8081 and report a refused connection.

Provision a wildcard HTTPS certificate and DNS for a separate preview domain, for example *.previews.example.net. This domain must be outside agentNativeAdmin.sharedCookieDomain; it must not receive OCE session cookies. Store the wildcard certificate in a TLS Secret in the Helm release namespace. Enable a separate Envoy listener with explicit public ingress peers:

gatewayRouting:  sandbox:    enabled: true    domain: previews.example.net    tlsSecretName: preview-wildcard    listenerPort: 8443    ingressPeers:      - namespaceSelector:          matchLabels:            kubernetes.io/metadata.name: ingress-nginx        podSelector:          matchLabels:            app.kubernetes.io/name: ingress-nginx

Route the preview wildcard through your ingress to the Envoy Service's sandbox port, preserving the requested hostname and TLS server name. Keep the private administrative listener restricted. listenerPort is also the Envoy Pod port; it must be at least 1024 and differ from the private Envoy HTTPS target port. For local testing, a loopback port-forward to that Service port can provide the same TLS endpoint; normal certificate validation must succeed.

In the Installation's drivers.compute.configuration.gatewayRouting, add:

sandbox:  domain: previews.example.net  publicPort: 443

The domain must match Helm. publicPort is the browser-facing HTTPS port and may differ from Envoy's listener port; it defaults to 443. Restart the API and worker after changing startup configuration, then deploy the Agent normally. Compute derives each Agent's hostname, renders mcp.apps.sandboxOrigin and sandboxPort, and creates its Service and route. New Agents need no manual hostname mapping. Remove conflicting tenant overrides of those two native fields rather than redirecting the sandbox to the admin origin.

Open a generated HTML file from the native chat. Verify it renders on the preview domain, the request carries no OCE session cookie, and the preview host cannot serve /console/, Gateway RPCs or workspace data. A successful shell request alone does not prove the file rendered. After replacing the Gateway Pod, reopen the same file and verify its contents are retained.

Tests

Open the console, choose a running Agent with an active revision, open Workspace files, and verify Native admin UI reports available for an administrator. Open the tab and confirm the Agent host loads without native-admin exchange, bootstrap, callback, or Agent-specific session-cookie requests.

Full runtime proof still requires a real browser test that loads native assets through OCC, reconnects native WebSocket traffic, verifies the OCE session cookie never reaches the native gateway, and performs a reversible native admin edit against a disposable Agent.

Troubleshooting

Related

• Agent native admin UI
• Gateway routing with Envoy
• Workspace routing deployment
• Agent native admin UI flow