跳转至

认证和隔离

认证与环境隔离

Codex 回合使用哪个凭据，以及 app-server 子进程继承了什么。本文属于 Codex harness 参考；各节移往何处 列出了每一节。

在默认的每个 agent 的 home 目录中，stdio 启动使用 Codex 的临时凭据存储，包括由 appServer.command 或 OPENCLAW_CODEX_APP_SERVER_BIN 选择的自定义命令。命令包装器必须转发 Codex 的 -c 配置参数。对于带有显式 app-server 子命令的 stdio 启动，OpenClaw 会将该子命令之前的 -c / --config 覆盖项分组，保持其顺序，并保留包装器前缀和其他参数。这可以防止当标志出现在 app-server 两侧时，Codex 丢弃较早的覆盖项。当 OpenClaw 拥有认证时，OpenClaw 的临时凭据存储覆盖项保持在最后；原生用户 home 目录认证保持不变。

工作区写入回合也会从这些参数中保留显式的 sandbox_workspace_write 临时根排除项，包括附带的 -ckey=value 标志以及布尔值后的 TOML 注释。最后一个显式值生效。显式的回合沙箱策略和网络代理权限配置文件保持其现有的优先级。

OpenClaw 按以下顺序提供认证：

  1. 为该 agent 显式指定或按顺序排列的 OpenClaw 认证配置文件。
  2. 仅对于 API 密钥路由，使用来自 CODEX_API_KEY 的预备密钥或本地 stdio 回退，然后是 OPENAI_API_KEY。

在此模式下，app-server 不会读取现有的 codex-home/auth.json。请按下文所述显式导入该文件。只有在 app-server 应改为拥有并使用操作员原生 Codex 账户时，才设置 appServer.homeScope: "user"。

有关交接内容、由谁刷新，以及共享原生账户如何影响受监督的 Chat 的并排说明，请参阅凭据与账户所有权。

在此模式下，无论是在哪种 home 模式下，都不会写入凭据文件。订阅配置文件以 chatgptAuthTokens 类型的 account/login/start 请求移交，Codex 将其安装为内存中的外部认证，而不会持久化；临时凭据存储覆盖 API 密钥登录，否则该登录会写入 CODEX_HOME/auth.json。

令牌刷新采用反向处理，因此长期有效的机密永远不会离开 OpenClaw。Codex 只持有短期访问令牌，当收到未授权响应时，它会通过同一连接向 OpenClaw 发送 account/chatgptAuthTokens/refresh 请求。OpenClaw 会针对自己的认证配置文件存储进行刷新，并返回新的访问令牌，因此刷新令牌保留在 SQLite 中。如果在 app-server 的超时时间内未应答刷新，则该回合失败，而不会回退到其他凭据。刷新失败会使共享客户端停止复用；现有租约耗尽后，下一个请求将启动新的客户端。如果工作区已更改，请重试该请求。如果凭据无法刷新，请使用 openclaw models auth login --provider openai 重新登录，并选择该配置文件。共享客户端在复用前会重新检查所选配置文件，因此在同一配置文件 ID 下切换账户也会选择新的客户端。

当 OpenClaw 检测到 ChatGPT 订阅风格的 Codex 认证配置文件（OAuth 或令牌凭据类型）时，它会从生成的 Codex 子进程中移除 CODEX_API_KEY 和 OPENAI_API_KEY。这样可使 Gateway 级别的 API 密钥仍可用于嵌入或直接 OpenAI 模型，而不会意外让原生 Codex app-server 回合通过 API 计费。

显式的 Codex API 密钥配置文件和本地 stdio 环境密钥回退使用 app-server 登录，而不是继承子进程环境。WebSocket app-server 连接不会收到 Gateway 环境 API 密钥回退；请使用显式认证配置文件或远程 app-server 自身的账户。

默认情况下，stdio app-server 启动会继承 OpenClaw 的进程环境。OpenClaw 拥有 Codex app-server 账户桥接，并将 CODEX_HOME 设置为该 agent 的 OpenClaw 状态下的 per-agent 目录。这样可使 Codex 配置、账户、插件缓存/数据以及线程状态限定在 OpenClaw agent 范围内，而不会从操作员的个人 ~/.codex home 目录中泄漏进来。

设置 appServer.homeScope: "user" 可与 Codex Desktop 和 CLI 共享原生 Codex 状态。此本地用户 home 模式支持受管理的 stdio 和显式 Unix 传输。当设置 $CODEX_HOME 时使用它，否则使用 ~/.codex，包括原生认证、配置、插件和线程。OpenClaw 会跳过其针对 app-server 的认证配置文件桥接。经验证的所有者回合可以使用 codex_threads 列出（可附带 search 过滤器）、读取、派生、重命名、归档和取消归档这些线程。在 OpenClaw 中继续线程之前，请先派生该线程；独立的 Codex 进程不会协调对同一线程的并发写入者。

该 homeScope 选择加入适用于普通的 harness 会话。托管网络搜索和已结算回合的收尾使用私有临时 home 目录和 OpenClaw 认证，即使普通会话共享用户 home。通过 Codex Sessions 创建的 Chat 使用其私有监督连接，从而保留原生连接在规范分支和未来恢复中的认证与提供商配置。如果该受监督的回合完成了工具工作但没有给出最终答案，OpenClaw 不会借用主机凭据来生成答案。它会提供已结算工具回退，而不会重复已完成的操作。

在模型锁定的受监督 Chat 中，codex_threads 无法附加不同的派生分支，也无法归档该 Chat 所绑定的原生线程。列表和仅元数据读取仍然可用。原始记录读取需要 allowRawTranscripts；当该项被禁用时，列表搜索也会被拒绝，因为原生搜索可能匹配到记录预览。重命名、取消归档、分离式派生以及归档不属于另一个 OpenClaw Chat 的无关线程，都需要 allowWriteControls。这两个选项都不能绕过锁定的绑定。

OpenClaw 在普通本地 app-server 启动时不会重写 HOME。 Codex 运行的子进程，例如 openclaw、gh、git、云 CLI 和 shell 命令，会看到正常的进程主目录，并可以找到用户主目录中的配置和 令牌。Codex 还可能发现 $HOME/.agents/skills 和 $HOME/.agents/plugins/marketplace.json；该 .agents 发现机制 有意与操作者主目录共享，并且独立于隔离的 ~/.codex 状态。

在默认代理作用域中，OpenClaw 插件和 OpenClaw 技能快照 仍然通过 OpenClaw 自己的插件注册表和技能加载器流转；个人 Codex ~/.codex 资产则不会。如果你有一些有用的 Codex CLI 技能或 来自某个 Codex 主目录的插件，并且它们应成为隔离 OpenClaw 代理的一部分，请显式清点它们：

openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

凭据需要使用敏感迁移路径，因为默认代理作用域 不会直接使用复制或挂载的 codex-home/auth.json。将 <agent-id> 替换为拥有此 Codex 主目录的已配置代理：

openclaw migrate plan codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai
openclaw migrate apply codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai --yes

如果部署需要额外的环境隔离，请将这些变量 添加到 appServer.clearEnv：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}

appServer.clearEnv 仅影响派生的 Codex app-server 子进程。 OpenClaw 在本地启动规范化期间会从该列表中移除 CODEX_HOME 和 HOME：CODEX_HOME 保持指向所选代理或用户作用域， 并且 HOME 保持继承，以便子进程可以使用正常的用户主目录状态。

从 2026.9.4 升级并使用 Codex 登录

如果 openai:default 仅通过原生 Codex 登录存在，你可以在 2026.9.4 上做好准备，然后再升级到 2026.9.5，因为 2026.9.5 不再提供该覆盖层。 对于传统的 main 共享存储所有者，请通过 OpenClaw 完成一次新的设备代码 登录，并验证已持久化的配置文件：

openclaw models auth login --provider openai --method device-code --profile-id openai:default --agent main
openclaw models auth list --agent main --json

保留 --profile-id：在 2026.9.4 上省略它可能会以不同的 ID 导入并移除旧的覆盖层。openai:default 应出现在上述未过滤 列表中。其他代理继承共享配置文件， 包括具有无关本地凭据的代理。具有相同 ID 的本地 配置文件会覆盖它；只有要创建或替换一个有意的本地 OpenAI 覆盖时，才使用 --agent <id> 单独登录。

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