跳转至

原生状态和功能

将 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",
          },
        },
      },
    },
  },
}

用户主目录模式支持本地托管的 stdio 进程或共享的 Unix 套接字传输。当设置了 $CODEX_HOME 时使用它,否则使用 ~/.codex,包括该主目录中原生的 Codex 身份验证、配置、插件和线程存储。OpenClaw 不会将 OpenClaw 身份验证配置文件注入此 app-server,即使代理的模型路由存储了 OpenAI 配置文件。相反,原生账户会与该路由进行双向验证:

  • 订阅路由要求原生主目录已登录 ChatGPT。如果某个回合报告缺少订阅凭据,请在该主目录中运行 codex login。
  • Platform(API 密钥)路由会拒绝已使用 ChatGPT 订阅登录的原生主目录,因此按 API 计费的路由绝不会静默消耗订阅方案。请使用 codex login --with-api-key 登录该主目录,或切换到 homeScope: "agent",让 OpenClaw 注入它已持有的密钥。

存储的 OpenAI 配置文件可以与 homeScope: "user" 共存;OpenClaw 会将其保留给代理范围内的连接,只是不会把它交给原生主目录。使用 openclaw models auth list --provider openai 查看已存储的配置文件,使用 openclaw models auth logout <profileId> --yes 移除你不再需要的配置文件。

所有者回合会获得 codex_threads 工具:列出、搜索、读取、派生、重命名、归档和恢复原生线程。派生一个线程以在 OpenClaw 中继续它;该派生会附加到当前 OpenClaw 会话,并且其他原生 Codex 客户端仍可通过 ID 读取它。在首次用户回合后,它会出现在原生线程列表中。归档需要明确确认该线程已在其他地方关闭。当监督(supervision)也启用时,转录字段和变更操作需要相应的 supervision.allowRawTranscripts 或 supervision.allowWriteControls 可选功能。

不要通过独立的托管 stdio App Server 同时恢复或写入同一线程。Codex 会在同一个 App Server 内协调活动写入者,而不会跨独立进程协调。对于普通的用户主目录 stdio 会话,派生是安全的共存方式。

仅设置 appServer.homeScope: "user" 本身并不能控制 fleet 目录。当插件处于活动状态时,原生会话发现功能会启用;设置 sessionCatalog.enabled: false 可在不禁用 Codex 的情况下将其从 OpenClaw 侧边栏中移除。该目录使用独立的监督连接;如果没有显式的 appServer 连接设置,该连接将默认为托管的用户主目录 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 守护进程运行。如果你使用的是 Codex 的独立托管安装,且其守护进程未在运行,请用以下命令启动它:

codex app-server daemon start

该命令是幂等的,并在其 JSON 响应中报告控制套接字。对于其他安装方式,请使用现有本地 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 和原生守护进程必须解析到同一个 Codex 主目录。对于自定义套接字,请将 appServer.url 设置为 "unix:///absolute/path/to/codex.sock"。OpenClaw 连接的是正在运行的服务器;它不会启动或停止该守护进程。

要让原生 Codex 选择模型和提供商,请从 Codex 侧边栏打开一个已存储或空闲的会话,并在其会话查看器中发送一条消息。生成的模型锁定 Chat 会在初始选择时使用原生配置,并在后续回合中保留原生所有权。在该 Chat 中检查 /codex binding,以查看实际选择。普通的 OpenClaw 聊天仍使用它们自己的 OpenClaw 模型路由;仅 homeScope: "user" 本身不会让每个聊天都继承 TOML 模型。请参阅 分支行为。

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

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

凭据与账户所有权

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

方面 共享原生守护进程:Unix 传输与用户主目录 OpenClaw 管理的 OAuth:受管理的 stdio 与 agent 主目录
登录来源 所选 CODEX_HOME 中的原生 Codex 账户。无需再次进行 OpenClaw 登录。 所选的 OpenClaw OAuth 配置文件。
交接给 Codex OpenClaw 进行附加时不会向 account/login/start 发送 OpenClaw 配置文件,也不会替换守护进程的登录。 OpenClaw 通过 account/login/start 发送访问令牌、ChatGPT 账户 ID 和套餐类型。它不会发送刷新令牌。
凭据存储 Codex 保留其配置的原生凭据存储,例如文件或 keyring。 OpenClaw 将持久凭据保存在其凭据存储中。Codex 将交接的令牌保存在内存中,而不是 auth.json。该 agent 的 Codex 配置和线程仍然持久保留。
令牌刷新 Codex 刷新其原生 ChatGPT 登录。附加不会在 OpenClaw 中创建另一个刷新所有者。 Codex 从 OpenClaw 请求新的访问令牌。OpenClaw 刷新原始配置文件;刷新令牌仍归该所有者持有。
后续轮次 后续轮次继续使用原生认证。保留线程订阅不会复制或固定 OpenClaw 凭据。 复用的客户端会保留其原始配置文件和刷新所有者。在配置文件下更换账户会选择新客户端,而不是将旧客户端的刷新请求重定向。
Gateway 环境 附加不会改变已在运行的守护进程的环境。其自身的启动环境和原生配置仍然适用。 准备好的受管理启动会清除 CODEX_API_KEY、OPENAI_API_KEY 和 CODEX_ACCESS_TOKEN,以免继承的值替换所选的交接。
CLI 与桌面端登录 该连接使用原生认证,不会将该主目录登录到 OpenClaw 选定的账户。 默认的 <agentDir>/codex-home 与原生主目录是分开的;交接不会覆盖 CLI 或桌面端登录。

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

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

当你需要独立的账户所有权时,请使用普通的 agent 作用域会话,并显式选择 OpenClaw 账户。仅靠 agent 作用域并不意味着每个人一个登录:共享配置文件仍然共享,并且默认情况下 OAuth 刷新凭据不会在 agent 之间复制。参见 认证凭据语义 和 个人模型账户。

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

监督 Codex 会话

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

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

原生 Codex 插件

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

codexPlugins 仅影响选择原生 Codex harness 的会话。它不会影响内置 harness 运行、常规 OpenAI provider 运行、ACP 会话绑定或其他 harness。

最小迁移配置:

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

线程 app 配置在 OpenClaw 建立 Codex harness 会话或替换过期的 Codex 线程绑定时计算,不会在每次回合时重新计算。更改 codexPlugins 后,使用 /new、/reset 或重启 gateway,以便将来的 Codex harness 会话以更新后的 app 集合启动。

有关迁移资格、app 清单、破坏性操作策略、征询和原生插件诊断,请参阅原生 Codex 插件。

OpenAI 侧的 app 和插件访问由已登录的 Codex 账户控制,对于 Business 和 Enterprise/Edu 工作区,还受工作区 app 控制。有关 OpenAI 的账户和工作区控制概览,请参阅将 Codex 与你的 ChatGPT 套餐配合使用。

Computer Use

Computer Use 有其自己的设置指南:Codex Computer Use。

简要说明:OpenClaw 不捆绑桌面控制 app,也不会自行执行桌面操作。它准备 Codex app-server,验证 computer-use MCP 服务器可用,然后在 Codex 模式回合期间让 Codex 全权处理原生 MCP 工具调用。

富 MCP 表单

OpenClaw 接受 Codex 针对 openai/elicitation/create 扩展的 openaiForm 征询变体,并保留旧版 openai/form 变体。普通 MCP 表单和 URL 请求保持其自身的协议语义;打开 URL 并不表示该步骤已完成。

Codex 在转发表单之前应用其原生审批策略。对于 OpenClaw 创建的线程中的手动 Apps,当工具需要交互式输入时,请使用提示式权限模式,例如 Guarded 或 Workspace。完全访问映射到原生 never 审批策略,该策略可能会在 OpenClaw 收到这些表单之前拒绝它们。OpenClaw 不会为了绕过该策略而打开第二个 MCP 连接。

Control UI 显示选项描述和 base64 图片缩略图,包括当仅有部分选项有图片时的备用图块。HTTPS 缩略图使用显式的外部图片链接,而不是自动的私有网络浏览器抓取。字符串建议允许自定义答案。字符串数组接受建议选项,并且每行可包含一个自定义条目;相同的字符串、模式、长度、唯一性和基数约束会应用于每个提交的值。不安全或不支持的模式会被拒绝,而不是在无限制的情况下被评估。

显式资源选择返回提供的 URI,而不是其显示标题。单资源和多资源字段都接受已弃用的 type: "file" 别名。默认值必须引用提供的资源并作为初始选择出现;清除可选默认值不会静默地将其恢复。

资源预览和上传需要绑定到待处理表单及其来源 MCP 运行时的能力。拥有该能力后,显式选择会选取提供的资源,隐式选择会从提交的集合中移除资源,文件/目录上传控件仅返回主机接受的 URI。预览操作读取关联的 MCP 资源,或打开来源服务器的 MCP App 工具。不支持上传的 Web MCP App 界面不得宣传该能力。需要不可用操作的表单会被整体拒绝,并附有说明;它绝不会被部分显示或替换为不限范围的 URI 文本框。

富表单限制为 12 个字段、每字段 64 个选项和 16 个自定义数组条目。普通问题保留其四个选项的限制。选项和语义输入不会被截断。无效、不支持或超限的字段会在发布任何问题之前拒绝整个表单。答案保留来源请求的回合关联、取消和实时执行权限。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw