放置和机器选择

选择会话运行所在的机器：可以是显式授权的配对设备、可承载任一执行器（harness）的 Crabbox 云配置文件，以及按放置位置的操作系统和机器类别覆盖设置。

在配对设备上运行 Codex¶

配对设备上的 Codex 放置要求 codex 插件已在 Gateway 配置和节点自身本地配置中安装并启用。当任一台机器使用插件允许列表时，请在该机器的 plugins.allow 中包含 codex。此外，还需要一个已连接、支持会话且通告 codex.exec-server 的节点，以及 gateway.nodes.commands.allow 中针对 codex.exec-server.stdio.v1 的显式条目。如有需要，请批准节点更新后的配对接口。在每次 exec-server 启动前，OpenClaw 还要求常规的节点调用批准；拒绝该请求则不会启动进程。

Codex 直接启动其 exec-server，因此配对设备和云节点放置不会占用 OpenClaw worker 槽位，并且在这些槽位已满时仍符合使用条件。OpenClaw 的 worker-turn 放置仍然需要可用的 worker 槽位。

批准允许在节点操作系统账户允许的任何位置执行进程和访问文件系统。具体的放置工作区控制的是起始目录和已协调的更改，而非 OS 级隔离。请信任配对设备，并在需要隔离时使用独立的、最小权限的 OS 账户。

在 Control UI 的 Place 选择器中选择设备，或使用已授权的操作员连接分派一个受管理工作树会话：

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

Codex 应用服务器、模型连接、提供方凭据和转录记录均保留在 Gateway 上。配对节点在传输后的工作区中运行受管理的 Codex exec-server，并且仅通过现有节点通道接收经过清理的进程、文件系统、能力发现和 HTTP 操作。它不会启动 OpenClaw worker 子进程。携带凭据的 HTTP 请求在到达配对设备之前就会被拒绝；请在 Gateway 上运行已认证的请求，或使用特意不携带凭据的端点。支持常规 Codex 轮次，但 /btw 侧问题尚不能绑定到放置位置，会明显失败。完成的更改会通过与 worker 轮次相同的放置工作区协调机制返回。有关确切的允许列表配置和生命周期，请参阅在配对设备上运行 Codex。

在云配置文件上运行 Codex 或 OpenClaw¶

同一个已配置的 Crabbox 配置文件可以承载任一执行器（harness）。在选择 OpenClaw 或 Codex 模型后，于 Cloud 下选择对应的配置文件行；所选运行时会决定预配准备的是 worker 子进程还是受管理的 Codex exec-server。Codex 云节点执行需要与配对设备执行相同的显式 Gateway 命令允许列表和放置范围批准。如果节点命令缺失、被拒绝，或节点断开连接，它绝不会回退到 Gateway 本地或 SSH 执行。

对于云配置文件放置，等效的 RPC 流程如下：

创建一个仓库会话，分派它，然后发送其第一条消息。配置文件分派需要 operator.admin，并且仅在至少配置了一个 worker 配置文件时可用：

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"}'

省略 ref 以使用仓库的远程默认分支。分支、标签或提交必须可从该仓库获取。首次成功的预配会固定确切的提交；即使分支已移动，后续分派也会恢复该提交和已接受的检查点。不要将 repository 与 cwd、projectId、projectGitUrl、worktree 或工作树命名选项组合使用，并且不要在此创建请求中包含初始消息。在活跃放置之前发送会被拒绝，并会给出分派指引。

若要保留现有的 Gateway 源流程，请改为使用 {"worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"} 进行创建。projectGitUrl 仍表示由 Gateway 管理的项目克隆。

仓库预配会在符合条件的云分配之前固定不可变的源元数据，而不会创建受管理的 Gateway 检出。选择已预配容量并将其绑定到会话，可验证当前的访问权限和可见性，包括在 Gateway 重启后中断的预配恢复时也是如此。公共和私有预配身份保持分离。私有预配在 Gateway 上使用经过身份验证的临时 Git 对象，并且只向 worker 传输一个经过验证的包。已活跃的会话会在重启后保留其检出和已保存的更改；当 GitHub 访问权限发生变化时，这不会重新接纳已预配的容量，也不会撤销已下载的文件。未启用项目预配的提供方在接入后保持普通检出。仅当没有配置共享或原生 GitHub 身份时，公共源才能使用匿名访问；配置的身份不可用仍会报错。

仓库预配以及已预配检出的采用均不会将 GitHub 凭据传输给 worker。后续的 OpenClaw worker 轮次在可用时，会通过现有的按轮次凭据绑定使用有效的共享或原生 GitHub 身份。

私有仓库获取使用有效的共享 tools.github 身份。通过 Control UI 的仓库选择器进行访问本身并不会授权该 worker 身份，而且个人发布凭据绝不会用于检出。

仓库设置使用节点上现有的可执行 .openclaw/worktree-setup.sh 契约。仅当创建请求以管理员身份请求设置，并且当前分派调用者也是管理员时，它才会运行。中断的初始设置需要管理员重试分派，除非节点证明已获准入的设置已经完成。预配采用和检查点恢复不会重新运行设置。没有可用于复制 .worktreeinclude 文件的本地源。

选择器中的提供商身份¶

云配置文件行和已选择的 Place 标签会显示已配置的后端，包括 AWS、Azure、Daytona、Google Cloud 和 Hetzner。Machine0 和 Incus 使用服务器图标；本地容器使用方框；其他后端使用云图标。配置文件名称保持不变，即使配置文件名为 production，可访问性标签也会包含后端。重命名配置文件永远不会更改其提供商标记。

在“新建会话”和“移动”中，已识别的云提供商配置文件会显示在本地容器、Incus 基础设施以及自定义或未知后端之前。每个组仍按配置文件名称字母顺序排列。Machine0 属于云提供商组，即使它使用服务器图标；配置文件名称永远不会决定分组。Gateway 和配对设备部分保持现有顺序。

在手机上，新建会话的环境和工作区控件垂直堆叠，并最多扩展到可用行宽度的 90%。较长的已选名称保持在一行内，并在末尾淡出，而不是换行。操作系统和机器摘要位于环境名称下方，前面没有分隔符。桌面控件保持水平排列。

提供商可以通过其展示钩子提供此可选的只读身份。如果不可用，选择器会保留通用图标。显示 ID 不会更改路由、分配、权限或操作系统和机器选择。

为每个会话选择操作系统和机器类别¶

工作器配置文件中的 settings.target 和 settings.class 仍为其默认值；省略 Crabbox 目标表示 Linux。在控制 UI 的新建会话选择器中，将鼠标悬停在 云 下可配置的配置文件上或聚焦该配置文件，以打开其 操作系统 和 机器 选项。仅显示可用的操作系统。在配置文件被选择之前，虚线轮廓会标识其默认值。选择任意选项都会选择该配置文件，并激活另一设置的默认值。机器列表会显示所选操作系统的类别，以及适用于所有系统的任何类别，并在可用时显示报告的 vCPU 和 RAM，同时标记默认值。更改操作系统时，如果所选类别在该系统上不可用，则会清除已选类别。

已选择的配置文件行和已关闭的选择器会在配置文件名称旁以弱化文本显示操作系统和机器，使用所选值或配置文件默认值。仅显示提供商报告的元数据。要通过 RPC 覆盖一次新放置的操作系统或大小，请随 profileId 传递 os 和/或 machineClass：

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws","os":"linux","machineClass":"tiny"}'

捆绑的 Crabbox 提供商会在所选后端报告匹配目标时，声明支持 Linux、Windows（WSL2）、原生 Windows 和 macOS。在读取目录或启动工作器之前，插件会解析受支持的 Crabbox 二进制文件，并在所选二进制文件过时或缺失时自动安装其受管副本。每个目标都使用相同的受支持版本；旧的本地 CLI 不再隐藏非 Linux 目标。有关受管安装策略，请参阅 Crabbox 配置。桌面支持 Linux、原生 Windows 和已准备的 macOS 镜像；不支持 WSL2 桌面。预热镜像仍仅限 Linux。请参阅 桌面先决条件。当目录包含可用的操作系统选项时，会显示 操作系统 部分；Crabbox 会报告可用目标，并且每个 Crabbox 机器选项都会标识其 os。

选择 windows/normal 表示原生 Windows，选择 windows/wsl2 表示 Windows 内部的 Linux 环境。原生 Windows 会以 PowerShell 运行 settings.setup，并要求来宾上存在受支持的 Node.js 和 npm。无头 Windows 工作器还需要 Crabbox 的分离进程启动器。Bash 设置配方不能原样复用于该目标；请参阅 工作器设置和捆绑安装。

当 classCatalog.disposition 为 mapped 时，提供商会从 crabbox providers --json 读取 classCatalog.profiles。对于每个目标，如果可用，它会优先选择 amd64 条目；仅包含 mixed 或 arm64 条目的目标会保留这些条目。它会为每个操作系统分别将已配置的类别标记为默认值。目录最多包含 64 个机器选项，按可注册的操作系统排序，然后按目录顺序排序。无类别的配置文件没有虚构的默认值。报告的 vCPU 和 RAM 独立显示。RAM 遵循 Crabbox 的摘要约定：显示正整数 GB/GiB 值；其他单位、小数和缺失维度保持未知。具有 mixed 架构且缺失维度的 macOS 条目仍可选择。绝不使用原生类型名称来猜测维度。未映射、缺失、未知、失败、空或不可用的目录元数据不会产生机器选择器，即使存在旧版 classes。云配置文件仍可选择，并且在不覆盖的情况下进行分发或移动会保留其配置。

成功的目录（包括有效的空目录）会缓存整个 Gateway 生命周期。失败的探测会由下一次发现请求重试；无需重启 Gateway 即可恢复。

即使 Crabbox 省略旧版 classes 摘要，已映射的 Machine0 类别也会显示。这些静态映射描述类别选择，而不是当前容量或可用性。OpenClaw 不会将提供商原生大小目录转换为类别。请在 Crabbox 的配置中保留原生大小选择：显式配置的原生大小仍优先于类别，因此选择器无法覆盖该固定值或承诺调整大小。通过 machineClass 接受原生服务器类型是后端特定的，而不是通用的 Crabbox 约定。已接受的机器选择对于该放置保持固定，并在配置重试中复用；目录更改不会重写它。os 和 machineClass 仅与 profileId 一起有效，而不是 deviceId 或 autoDevice。省略任一字段会使用相应的配置文件默认值。