选择启用（Opt-in）的功能，可将 OpenClaw 代理连接到原生 Codex 状态及 Codex 拥有的能力。属于 Codex harness 指南的一部分；每节移往何处 列出了所有章节。¶

与 Codex Desktop 和 CLI 共享线程¶

默认的 appServer.homeScope: "agent" 会将每个 OpenClaw 代理与操作者的原生 Codex 状态隔离。若要允许所有者检查和管理 Codex Desktop 与 Codex CLI 所显示的同一组原生线程，请选择使用用户级 Codex home：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            homeScope: "user",
          },
        },
      },
    },
  },
}

用户级 home 模式支持本地托管的 stdio 进程或共享的 Unix-socket 传输。它使用 $CODEX_HOME（若已设置），否则使用 ~/.codex，其中包含该 home 的原生 Codex 认证、配置、插件和线程存储。OpenClaw 不会将 OpenClaw 认证配置文件注入此 app-server，即使代理的模型路由中存有 OpenAI 配置文件也是如此。原生账户会改为与路由进行双向验证：

• 订阅路由要求原生 home 已登录 ChatGPT。如果某轮对话报告缺少订阅凭据，请在该 home 中运行 codex login。
• Platform（API-key）路由会拒绝已使用 ChatGPT 订阅登录的原生 home，因此按 API 计费的路由绝不会静默消耗订阅方案。请使用 codex login --with-api-key 登录该 home，或者切换到 homeScope: "agent" 并让 OpenClaw 注入其已持有的密钥。

存储的 OpenAI 配置文件可与 homeScope: "user" 共存；OpenClaw 会将其保留用于代理作用域的连接，只是不会把它交给原生 home。可使用 openclaw models auth list --provider openai 查看已存储的配置文件，使用 openclaw models auth logout <profileId> --yes 移除不再需要的配置文件。

所有者的对话轮次会获得 codex_threads 工具：列出、搜索、读取、分叉（fork）、重命名、归档和恢复原生线程。分叉某个线程以在 OpenClaw 中继续；该分叉会挂接到当前 OpenClaw 会话，并且仍可通过 ID 从其他原生 Codex 客户端读取。它会在第一次用户轮次后出现在原生线程列表中。归档需要明确确认该线程已在其他地方关闭。当同时启用 supervision 时，转录字段和变更操作需要相应的 supervision.allowRawTranscripts 或 supervision.allowWriteControls 选择启用项。

不要通过独立的托管 stdio App Server 并发恢复或写入同一线程。Codex 在单个 App Server 内部协调活动写入方，而不会跨多个独立进程进行协调。对于普通用户级 home 的 stdio 会话，分叉是安全的共存方式。

appServer.homeScope: "user" 本身并不能控制 fleet 目录。当插件处于启用状态时，原生会话发现功能会开启；设置 sessionCatalog.enabled: false 可将其从 OpenClaw 侧边栏移除，而无需禁用 Codex。该目录使用单独的 supervision 连接；如果没有显式的 appServer 连接设置，该连接默认使用托管的用户级 home stdio，而普通 harness 仍保持代理作用域。显式的 appServer 设置对两条路径均生效。当普通 harness 也应共享原生状态时，请像上文一样显式设置 homeScope: "user"。

使用现有的本地 config.toml¶

连接到同一个本地 Codex App Server，即可复用你现有的 $CODEX_HOME/config.toml（默认是 ~/.codex/config.toml）、登录状态和原生线程。加载该文件、受信任的项目配置以及其正常的配置优先级，均由 Codex 负责。你无需将 TOML 复制到 OpenClaw，也无需通过 OpenClaw 重新登录。

在 macOS 或 Linux 上，请保持现有的 Codex daemon 运行。如果你使用的是 Codex 的独立托管安装，且其 daemon 未运行，请通过以下命令启动它：

codex app-server daemon start

该命令是幂等的，并会在其 JSON 响应中报告控制套接字（control socket）。对于其他安装方式，请使用现有本地 App Server 的 Unix 套接字；不要针对已被另一个进程拥有的线程再启动另一个 App Server。

将以下插件设置合并到你的 OpenClaw 配置中：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "unix",
            homeScope: "user",
          },
          supervision: {
            enabled: true,
          },
        },
      },
    },
  },
}

在不带 url 的情况下，OpenClaw 会连接到 $CODEX_HOME/app-server-control/app-server-control.sock。Gateway 和原生 daemon 必须解析到同一个 Codex home。若要使用自定义套接字，请将 appServer.url 设置为 "unix:///absolute/path/to/codex.sock"。OpenClaw 连接到正在运行的服务器；它不会启动或停止该 daemon。

若要允许原生 Codex 选择模型和提供方（provider），请从 Codex 侧边栏打开一个已存储或空闲的会话，并在其会话查看器中发送一条消息。由此产生的模型锁定 Chat 在初始选择时使用原生配置，并在后续轮次中保持原生所有权。请在该 Chat 中检查 /codex binding 以查看实际选择。普通的 OpenClaw Chat 仍然使用其 OpenClaw 模型路由；仅凭 homeScope: "user" 并不会让每个 Chat 都继承 TOML 中的模型。请参见 分支行为。

OpenClaw 仍会应用其会话工具、指令和执行策略，而不会重写你的 TOML。一旦该策略建立，普通的后续操作就会继续复用它。初始附加或策略变更可能要求 Codex 先卸载一个空闲线程。如果某轮对话报告会话策略交接失败，请先完成原生工作并关闭该特定线程的其他视图，然后重新连接并重试。其他线程和 daemon 可以保持运行。

更新后，现有的受监督（supervised）对话会保留其已记录的原生搜索策略。如果在创建对话时原生搜索已禁用，那么新宣传的提供方支持也不会在该线程中启用它。请从 Codex 侧边栏打开另一个已存储或空闲的原生会话，并发送一条消息，以使用当前的原生搜索能力和 OpenClaw 工具策略创建新分支。

凭据与账户所有权¶

连接到共享守护进程会复用其原生登录；它不会将该登录导入到 OpenClaw 身份验证配置文件中。对于 ChatGPT 登录，以下两条路径都使用 OAuth 和 Codex App Server。区别在于谁拥有凭据。

已存储的 OpenClaw 配置文件可以与原生登录共存，但它不是受监督原生 Chat 的回退凭据。原生身份验证失败必须在原生连接中解决；OpenClaw 不会借用其普通配置文件或 API 密钥回退来更改该 Chat 的账户。

模型锁定的 Chat 不是账户锁定的 Chat。 同一原生守护进程的使用者共享其身份验证边界。更改其登录可能会影响使用该守护进程的其他线程和原生客户端；OpenClaw 不会为每个受监督的 Chat 创建单独的 OpenAI 账户。在账户更改后发送更多工作之前，请验证预期的原生账户。不要假设退出 OpenClaw 配置文件会退出原生 Codex，反之亦然。

当需要独立的账户所有权时，请使用带有显式 OpenClaw 账户选择的普通代理作用域会话。仅代理作用域并不意味着每人一个登录：共享配置文件仍然共享，OAuth 刷新凭据默认不会在代理之间复制。参见 身份验证凭据语义 和 每人模型账户。

这些规则描述的是 Codex 连接的身份验证，而不是 shell 子进程或单独配置的 OpenClaw 工具所使用的凭据。对于这些边界、刷新失败处理以及显式凭据导入，请参见 Codex 身份验证与环境隔离。

监督 Codex 会话¶

相同的 codex 插件可以列出来自 Gateway 计算机和已选择加入的配对节点的未归档 Codex 会话。已存储或空闲的 Gateway 本地会话可以创建一个模型锁定的 Chat，该 Chat 镜像其有界的持久化用户和助手历史。其私有绑定使用监督连接用于原生快照、规范分支和后续轮次，而普通 Codex 会话仍保持代理作用域。首次规范启动精确使用 Codex 为快照分叉返回的模型和提供商。后续恢复将选择权留给 Codex 的原生配置；外层 OpenClaw 模型和回退链永远不会替换它。已存储和空闲的本地行可以在明确的无其他运行器确认后归档。活动源不能创建分支或归档；现有受监督的 Chat 仍可以打开。配对节点会话公开有界的分页转录。符合条件的已存储或空闲配对节点行还支持 operator.admin 的继续操作，前提是节点通告并允许所需的目录和 CLI 恢复命令。该流程在节点上恢复确切的本地原生线程，而不是创建 Gateway 本地分支；配对节点归档仍不可用。

有关设置、分支规则、配对节点限制、元数据暴露和故障排除，请参阅 监督 Codex 会话。

原生 Codex 插件¶

原生 Codex 插件支持会在与 OpenClaw 框架回合相同的 Codex 线程中，使用 Codex app-server 自身的应用和插件功能。OpenClaw 不会将 Codex 插件转换为合成的 codex_plugin_* OpenClaw 动态工具。

codexPlugins 仅影响选择原生 Codex 框架的会话。它对内置框架运行、常规 OpenAI 提供商运行、ACP 会话绑定或其他框架没有影响。

最小迁移配置：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
              },
            },
          },
        },
      },
    },
  },
}

线程应用配置在 OpenClaw 建立 Codex 框架会话或替换过期的 Codex 线程绑定时计算；它不会在每个回合重新计算。修改 codexPlugins 后，请使用 /new、/reset 或重启网关，以便未来的 Codex 框架会话使用更新后的应用集启动。

有关迁移资格、应用清单、破坏性操作策略、提示和原生插件诊断，请参阅 原生 Codex 插件。

OpenAI 端的应用和插件访问权限由已登录的 Codex 账户控制；对于 Business 和 Enterprise/Edu 工作区，还受工作区应用控制。有关 OpenAI 的账户和工作区控制概述，请参阅 使用 ChatGPT 套餐使用 Codex。

计算机使用¶

计算机使用有独立的设置指南：Codex 计算机使用。

简而言之：OpenClaw 不会捆绑桌面控制应用，也不会自行执行桌面操作。它会准备 Codex app-server，验证 computer-use MCP 服务器是否可用，然后让 Codex 在 Codex 模式回合中负责原生 MCP 工具调用。