Run Codex on another machine

How Codex sessions place native execution off the Gateway while the app-server, model connection, and transcript stay Gateway-owned. Part of the Codex harness guide; Where each section moved lists every section.

Run Codex on a paired device

Codex sessions can place native command, filesystem, capability-discovery, and HTTP execution on an eligible paired device while the Codex app-server, model inference, provider authentication, and session transcript stay on the Gateway. This is session-wide remote-exec placement, not node_exec or tools.exec.host: "node".

Install and enable the Codex plugin in both the Gateway's configuration and the paired node's own local configuration. If either machine uses plugins.allow, include codex in that machine's allowlist. On the Gateway, explicitly allow the high-risk node command:

{  gateway: {    nodes: {      commands: {        allow: ["codex.exec-server.stdio.v1"],      },    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

The paired node must enable session hosting and advertise the codex.exec-server capability and codex.exec-server.stdio.v1 command. If enabling the plugin changes an existing node's command surface, reconnect the node, inspect openclaw nodes pending, and approve the updated pairing with openclaw nodes approve <requestId>. The persistent command allowlist does not replace launch authorization. The critical prompt offers two approval scopes:

• Allow once authorizes one exec-server launch.
• Allow always authorizes later launches only while that exact session placement remains active on the same node, pairing generation, environment, owner epoch, placement generation, command risk, and working directory.

The Gateway keeps the standing placement grant only in its current process and revalidates it immediately before every node transport dispatch. Restarting the Gateway therefore returns to the normal prompt without migrating or reloading approval state. Moving or reclaiming the session, replacing the environment, reconnecting under a new pairing, changing the workspace, or reaching the 30-day maximum lifetime also invalidates reuse. If the Gateway cannot derive the exact placement authority, it offers only Allow once. Deny starts no process.

Explicitly selected session Full access can substitute for the prompt only during the exact admitted turn and placement, and only when the node's own tools.exec policy and exec-approvals floors both allow full/off execution. Node-local deny always blocks. Local ask or allowlist restrictions require a human decision; Full access does not erase them. If a Full launch is refused by local policy, use an ordinary session permission mode to request approval, or deliberately change the node's local policy and reconnect it. Policy tightening during launch preparation refuses the stale launch.

Codex launches its node exec-server directly rather than starting an OpenClaw worker, so a paired host remains eligible when all worker slots are occupied. The command must still be effectively invocable: declaring it without the approved pairing surface and Gateway allowlist is insufficient.

Approval grants access to any process or file available to the node's operating system account. The verified placement workspace sets the working directory and reconciliation scope; it does not sandbox or confine that access. Pair only trusted devices, and run the node under a separate least-privilege OS account when isolation is required.

Choose the paired device in the Control UI Place picker, or dispatch an existing managed-worktree session explicitly:

openclaw gateway call sessions.dispatch \  --params '{"key":"agent:main:device-work","deviceId":"<paired-device-id>"}'

The node starts the same managed, pinned Codex binary with codex exec-server --listen stdio in the placement workspace. The node waits for the native process to start listening before announcing execution readiness, so cold disk startup does not consume Codex's initialize-handshake budget. Startup remains cancellable through the existing attempt lifecycle. The Gateway relays complete Codex JSON-RPC messages through the existing authenticated, approval-gated duplex node channel, with a 64 MiB limit per message. It does not start an OpenClaw worker child, open a reverse tunnel, or copy provider, cloud, or GitHub credentials to the device. Authenticated remote HTTP is unavailable: the Gateway rejects requests containing bearer/OAuth authorization, cookies, API keys, or other sensitive authentication headers before sending them to the node. Run authenticated HTTP on the Gateway, or use an intentionally credential-free endpoint. The node process uses a fresh private HOME and CODEX_HOME that are removed after the attempt, and both its launch environment and requested child-process environments are sanitized. Completed filesystem changes reconcile into the Gateway-owned managed worktree or, for repository-only sessions, an immutable checkpoint retained by the Gateway.

Native task processes inherit the exec-server's startup RUST_LOG filter under Codex's default environment policy. Set RUST_LOG explicitly in a command when that program needs a different log level.

Disconnecting the node, closing the app-server connection, cancelling the turn, or retiring the plugin ends that Codex attempt visibly and terminates its remote exec-server process. Each paired-device attempt owns an isolated Gateway app-server client, preventing remote environment registrations from accumulating across attempts. Reconnecting the same paired device permits a fresh attempt; it never resumes the disconnected stdio connection or its processes. Normal Codex turns are supported, but /btw side questions are not yet bound to paired-device placement and fail with an actionable explanation. See Cloud workers and paired-device placement and Node command policy.

Run Codex on a cloud worker

The bundled Crabbox provider supports both OpenClaw worker-turn and Codex remote-exec, so one configured cloud-worker profile is selectable for either harness. Choose the same Cloud · profile destination in New Session or Move Session after selecting a Codex model. Profile placement requires operator.admin. Start from a GitHub repository URL and optional ref without a Gateway checkout, or place an existing Gateway managed-worktree session. Repository-only sessions fetch and pin their source on the selected node. Repository sessions require a managed node; SSH-only providers cannot create them.

Enable a trusted Codex plugin installation and explicitly allow codex.exec-server.stdio.v1 on the Gateway, as shown in Run Codex on a paired device. Crabbox automatically bootstraps the cloud node from the running Gateway's built installation, including the Codex plugin and its pinned native dependency. Bootstrap installs dependencies for the cloud machine's operating system and CPU, then enables the plugin in the node's isolated state. Keep profile setup focused on machine prerequisites and project tools, including a supported Node.js release and npm. See Bundle installation for build and registry access requirements.

The Gateway checks the cloud node's current pairing and effectively invocable command before starting a Codex process. The same placement-scoped approval or explicitly selected Full access rules apply, including the cloud node's local exec policy and approvals floors.

Codex runs its managed exec-server over the enrolled node's authenticated outbound connection without starting an OpenClaw worker child or consuming a worker slot. Its app-server, model connection, provider authentication, and transcript remain Gateway-owned. Process and filesystem access still have the node operating-system account's permissions, and only credential-free HTTP is forwarded. Workspace changes reconcile to the Gateway-owned worktree or an immutable repository checkpoint. A failed or disconnected attempt is terminal and requires a fresh attempt; it never resumes the remote process or falls back to Gateway-local or SSH execution.

See Cloud workers for profile configuration, placement lifecycle, and cleanup.