openclaw/docs/gateway/cloud-workers/security-model.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Worker ingress, tool authority, minted credentials, enrollment binding, and credential boundaries"
title: "Cloud worker security model"
read_when: "You are reviewing what a cloud worker can reach and which credentials leave the Gateway."
---

The boundaries that hold when session work runs on a throwaway machine: what the worker may call, which credentials it receives, and which never leave the Gateway.

## Security model

- **Closed worker ingress.** In worker-turn mode, the enrolled node launches the worker child, which dials the Gateway's authenticated public worker route and speaks a dedicated protocol with a closed method allowlist — a worker cannot call operator RPCs.
- **Gateway-owned tool authority.** In worker-turn mode, the Gateway projects current profile, provider, agent, group, sender, sandbox, delegation, inherited, and runtime-cap policy over the worker's fixed coding-tool catalog before every turn. The launch envelope carries only that final closed-vocabulary subset. Explicitly capped scheduled turns reuse their trusted owner-group context without sending that identity to the box or reapplying a fresh sender overlay. Tools outside the worker catalog remain unavailable; an empty result runs with no tools.
- **Minted credentials, hashed at rest.** Each dispatch mints a worker credential; the Gateway stores only its hash. Credential rotation and owner-epoch fencing guarantee at most one live owner per session — a stale worker that reconnects is fenced, never merged.
- **Environment-bound enrollment.** One short-lived node-only setup credential is bound to the durable environment before allocation. Its first authenticated Ed25519 device identity is recorded atomically with setup completion; replay cannot substitute an unrelated node.
- **Explicit Codex node authorization.** Cloud-node and paired-device remote execution require an explicitly allowed `codex.exec-server.stdio.v1` command, an approved pairing surface, and critical node invocation approval. Allow once never grants a later launch. Allow always creates an in-memory standing grant owned by the current Gateway process, with a 30-day maximum lifetime. Gateway restart clears it, and every launch revalidates the exact active placement, node pairing, environment owner, command approval scope, and workspace immediately before dispatch. The managed exec-server starts with a fresh private home and sanitized environment. Its managed workspace is not an OS sandbox: approved execution can access processes and files allowed to the node account, so use a separate least-privilege account when isolation is required.
- **Model and cloud credentials stay off the box.** OpenClaw worker turns proxy inference by `{provider, model}` reference. Codex remote-exec keeps the app-server plus ChatGPT subscription or API-key auth on the Gateway and sends only sandbox operations to the box. Remote-exec requires prepared auth and rejects ambient auth fallback. Crabbox AWS lease metadata is checked authoritatively for an instance role before setup. Keep setup commands credential-free too.
- **Turn-bound GitHub identity.** OpenClaw worker turns receive the Gateway's effective shared GitHub access token through the private launch envelope, refreshed for each turn. The worker materializes it in a private profile inside its throwaway state directory. Each turn gets its own profile directory, and earlier turns' profiles are removed before the next binding, so a process retained from an earlier turn keeps only the token it was launched with. That rotation limits inherited paths, not same-user access: processes running as the worker's operating-system user, including the agent's own background commands from earlier turns, can read worker state, exactly as on the Gateway host. Cloud workers are single-session throwaway machines; run a paired session host under a dedicated least-privilege account when isolation from the agent's earlier commands is required. The sealed worker launcher reads that profile for each `exec` launch and exposes the token only to the child process; it is never logged or journaled. Paired devices' own `gh` logins are not used.
- **Gateway-owned GitHub publication.** Control UI and Codex remote-exec publication use the Gateway broker, with credentials from the selected GitHub profile on the Gateway. Repository sessions publish an accepted Git-normalized checkpoint through GitHub's tree, commit, and compare-and-swap ref APIs. Gateway-worktree sessions use a temporary index, `git commit-tree`, and a command-local credential helper. Both paths disable repository hooks and reject unsafe Git configuration. Neither writes a bearer token to argv, a remote URL, `.git/config`, a publication request, or a transcript.
- **Provider-owned egress.** Gateway-proxied inference removes any OpenClaw need for direct model access, but OpenClaw does not rewrite provider firewalls. Restrict outbound traffic in the worker provider when the task requires it.
- **Durable, exactly-once worker transcripts.** In worker-turn mode, the worker commits transcript batches through a compare-and-swap protocol against the session's leaf; a stale base fail-stops the run instead of duplicating or rebasing paid output. Remote-exec writes through the Gateway's normal local harness path.