--- summary: "Codex on a paired device, either harness on a cloud profile, and per-session operating system and machine class" title: "Placement and machine selection" read_when: "You are choosing where a session runs, or overriding its operating system or machine size." --- Choosing the machine a session runs on: an explicitly authorized paired device, a Crabbox cloud profile for either harness, and per-placement operating-system and machine-class overrides. ## Codex on a paired device Paired-device Codex placement requires the `codex` plugin to be installed and enabled in both the Gateway's configuration and the node's own local configuration. Include `codex` in `plugins.allow` on either machine when that machine uses a plugin allowlist. It also requires a connected session-capable node that advertises `codex.exec-server`, and an explicit `gateway.nodes.commands.allow` entry for `codex.exec-server.stdio.v1`. Approve the node's updated pairing surface if needed. Before each exec-server launch, OpenClaw also requires the normal node invocation approval; denying that request does not start a process. Codex launches its exec-server directly, so paired-device and cloud-node placement do not consume an OpenClaw worker slot and remain eligible when those slots are full. OpenClaw `worker-turn` placement still requires an available worker slot. Approval permits process execution and filesystem access anywhere the node's operating system account allows. The exact placement workspace controls the starting directory and reconciled changes, not OS-level confinement. Trust the paired device, and use a separate least-privilege OS account when isolation is required. Choose the device in the Control UI **Place** picker or dispatch a managed-worktree session with an authorized operator connection: ```bash openclaw gateway call sessions.dispatch \ --timeout 1500000 \ --params '{"key":"agent:main:device-work","deviceId":""}' ``` The Codex app-server, model connection, provider credentials, and transcript remain on the Gateway. The paired node runs the managed Codex exec-server in the transferred workspace and receives only sanitized process, filesystem, capability-discovery, and HTTP operations over the existing node channel. It does not launch an OpenClaw worker child. Credential-bearing HTTP requests are rejected before they reach the paired device; run authenticated requests on the Gateway or use an intentionally credential-free endpoint. Normal Codex turns are supported, but `/btw` side questions are not yet placement-bound and fail visibly. Completed changes return through the same placement workspace reconciliation as worker turns. See [Run Codex on a paired device](/plugins/codex-harness/placement#run-codex-on-a-paired-device) for the exact allowlist configuration and lifecycle. ## Codex or OpenClaw on a cloud profile The same configured Crabbox profile can host either harness. Select its **Cloud · profile** row after choosing an OpenClaw or Codex model; the selected runtime determines whether provisioning prepares a worker child or the managed Codex exec-server. Codex cloud-node execution requires the same explicit Gateway command allowlist and placement-scoped approval as paired-device execution. It never falls back to Gateway-local or SSH execution if the node command is missing, denied, or disconnected. For cloud-profile placement, the equivalent RPC flow is: Create a repository session, dispatch it, then send its first message. Profile dispatch requires `operator.admin` and is available only while at least one worker profile is configured: ```bash openclaw gateway call sessions.create \ --params '{"key":"agent:main:big-refactor","repository":{"url":"https://github.com/example/project.git","ref":"main"}}' openclaw gateway call sessions.dispatch \ --timeout 1500000 \ --params '{"key":"agent:main:big-refactor","profileId":"aws"}' ``` Omit `ref` to use the repository's remote default branch. A branch, tag, or commit must be fetchable from that repository. The first successful preparation pins the exact commit; later dispatches restore that commit and the accepted checkpoint even if the branch moves. Do not combine `repository` with `cwd`, `projectId`, `projectGitUrl`, `worktree`, or worktree naming options, and do not include an initial message in this create request. Sending before active placement is rejected with dispatch guidance. To keep the existing Gateway-source flow, create with `{"worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}` instead. `projectGitUrl` still means a Gateway-managed project clone. Repository preparation pins immutable source metadata before eligible cloud allocation without creating a managed Gateway checkout. Selecting prepared capacity and binding it to a session verify current access and visibility, including when interrupted provisioning resumes after a Gateway restart. Public and private preparation identities remain separate. Private preparation uses authenticated temporary Git objects on the Gateway and transfers only a verified pack to the worker. An already-active session keeps its checkout and saved changes across restart; this does not re-admit prepared capacity or revoke downloaded files when GitHub access changes. Providers without project preparation keep ordinary checkout after enrollment. Public sources can use anonymous access only when no shared or native GitHub identity is configured; an unavailable configured identity remains an error. Repository preparation and prepared checkout adoption do not transfer GitHub credentials to workers. Subsequent OpenClaw worker turns use the effective shared or native GitHub identity through the existing [per-turn credential binding](/gateway/config-tools/github-identity), when one is available. Private repository fetches use the effective shared [`tools.github`](/gateway/config-tools#tools-github) identity. Access through the Control UI repository picker does not by itself authorize that worker identity, and personal publication credentials are never used for the checkout. Repository setup uses the existing executable `.openclaw/worktree-setup.sh` contract on the node. It runs only when creation requested setup as an administrator and the current dispatch caller is also an administrator. An interrupted initial setup requires an administrator to retry dispatch unless the node attests that the admitted setup already completed. Prepared adoption and checkpoint restoration do not rerun setup. There is no local source from which to copy `.worktreeinclude` files. ## Choose an operating system and machine class per session A worker profile's `settings.target` and `settings.class` remain its defaults; an omitted Crabbox target means Linux. In the Control UI, selecting a **Cloud · profile** destination in the Place picker reveals an **Operating system** section when the profile advertises at least two systems, followed by **Machine**. The machine list shows classes for the selected operating system, plus any classes that apply to every system, with reported vCPU and RAM when available and the default marked. Changing the operating system clears a selected class if it is unavailable for that system. The place chip includes the operating system when it differs from the profile default, using `profile · OS · Machine`. To override the operating system or size for one new placement over RPC, pass `os` and/or `machineClass` with `profileId`: ```bash openclaw gateway call sessions.dispatch \ --timeout 1500000 \ --params '{"key":"agent:main:big-refactor","profileId":"aws","os":"linux","machineClass":"tiny"}' ``` The bundled Crabbox provider advertises Linux, Windows (WSL2), native Windows, and macOS when the selected backend reports the matching target. Before reading the catalog or starting a worker, the plugin resolves a supported Crabbox binary, automatically installing its managed copy when the selected binary is outdated or missing. Every target uses the same supported version; an old local CLI no longer hides non-Linux targets. See [Crabbox configuration](/gateway/config-cloud-workers#crabbox-profile) for the managed installation policy. Desktop and warm images remain Linux only. The **Operating system** section appears when a provider advertises more than one target; `environments.list` omits `operatingSystems` for a single target, and each Crabbox machine option identifies its `os`. Select `windows/normal` for native Windows and `windows/wsl2` for the Linux environment inside Windows. Native Windows runs `settings.setup` as PowerShell and requires supported Node.js, npm, and Crabbox's detached-process launcher on the guest. A Bash setup recipe cannot be reused unchanged for that target; see [Worker setup and bundle installation](/gateway/cloud-workers/setup-and-bundle-installation#native-windows-prerequisites). The provider reads `classCatalog.profiles` from `crabbox providers --json` when `classCatalog.disposition` is `mapped`. For each target it prefers amd64 entries when available; targets with only mixed or arm64 entries retain those entries. It marks the configured class as the default separately for each operating system. The catalog includes at most 64 machine options, ordered by enrollable operating system and then by catalog order. A classless profile has no invented default. Reported vCPU and RAM appear independently. RAM follows Crabbox's summary contract: positive integer GB/GiB values are shown; other units, fractional values, and missing dimensions stay unknown. macOS entries with `mixed` architecture and missing dimensions remain selectable. Native type names are never used to guess dimensions. Unmapped, missing, unknown, failed, empty, or unusable catalog metadata produces no machine selector, even if legacy `classes` are present. The cloud profile remains selectable, and dispatch or Move without an override preserves its configuration. Successful catalogs, including valid empty catalogs, are cached for the Gateway lifetime. Failed probes are retried by the next discovery request; a Gateway restart is not needed to recover. Mapped Machine0 classes appear even when Crabbox omits the legacy `classes` summary. These static mappings describe class choices, not current capacity or availability. OpenClaw does not translate provider-native size catalogs into classes. Keep native size selection in Crabbox's configuration: an explicitly configured native size still takes precedence over a class, so the picker cannot override that pin or promise a resize. Acceptance of native server types through `machineClass` is backend-specific, not a universal Crabbox contract. An admitted machine choice remains fixed for that placement and is reused by provisioning retries; catalog changes do not rewrite it. `os` and `machineClass` are valid only with `profileId`, not `deviceId` or `autoDevice`. Omitting either field uses the corresponding profile default.