本页内容
本页内容
Codex 运行时参考
Codex 身份验证和环境隔离
Codex 使用哪个凭证，以及应用程序服务器子进程继承什么凭证。 Codex harness参考 的一部分； 每个部分移动的位置 列出每个部分。
认证和环境隔离
在默认的每个代理主目录中，stdio 启动使用 Codex 的临时凭证存储，包括由 appServer.command 或 OPENCLAW_CODEX_APP_SERVER_BIN 选择的自定义命令。命令包装器必须转发 Codex 的 -c 配置参数。对于使用显式 app-server 子命令启动的 stdio，OpenClaw 会在该子命令之前对 -c / --config 覆盖进行分组，保留它们的顺序并保留包装器前缀和其他参数。当标志出现在 app-server 的两侧时，这可以防止 Codex 丢弃较早的覆盖。当 OpenClaw 拥有 auth 时，OpenClaw 的临时凭证存储覆盖保持在最后；本机用户主目录身份验证未更改。工作区写入轮流还保留这些参数中的显式 sandbox_workspace_write 临时根排除，包括附加的 -ckey=value 标志和布尔值后面的 TOML 注释。最后一个显式值获胜。显式的轮流沙箱策略和网络代理权限配置文件保持其现有的优先级。
OpenClaw 按以下顺序提供身份验证：
- 为该 agent 显式指定或按顺序排列的 OpenClaw 认证 profile。
- 仅适用于 API-key 路由，从
CODEX_API_KEY到OPENAI_API_KEY的准备好的密钥或本地 stdio 回退。
应用程序服务器在此模式下不会读取现有的 codex-home/auth.json。如下所述显式导入该文件。仅当应用程序服务器应拥有并使用运营商的本机 Codex 帐户时，才设置 appServer.homeScope: "user"。
有关移交内容、谁刷新以及共享本机帐户如何影响受监督聊天的并排说明，请参阅 凭据和帐户所有权。
在此模式下，任何一个 home 中都不会写入任何凭证文件。订阅配置文件作为 chatgptAuthTokens 类型的 account/login/start 请求移交，Codex 将其安装为内存中外部身份验证而不是持久保存；临时凭证存储涵盖 API-key 登录，否则将写入 CODEX_HOME/auth.json。
令牌刷新是反向的，因此长期秘密永远不会离开 OpenClaw。 Codex 仅持有短期访问令牌，并且在未经授权的响应时，它会通过同一连接将 account/chatgptAuthTokens/refresh 请求发送回 OpenClaw。 OpenClaw 根据其自己的身份验证配置文件存储进行刷新并返回新的访问令牌，因此刷新令牌保留在 SQLite 中。在应用程序服务器的超时时间内未响应的刷新将失败，而不是回退到另一个凭据。刷新失败会使共享客户端不再重用；现有的租约耗尽，下一个请求启动一个新的客户端。如果工作区发生更改，请重试该请求。如果凭据无法刷新，请使用 openclaw models auth login --provider openai 再次登录并选择该配置文件。共享客户端在重复使用之前会重新检查所选配置文件，因此更改同一配置文件 ID 下的帐户也会选择新客户端。
当 OpenClaw 看到 ChatGPT 订阅风格的 Codex auth profile（OAuth 或 token 凭据类型）时，它会从启动的 Codex 子进程中移除 CODEX_API_KEY 和 OPENAI_API_KEY。 这样可以让 Gateway 级别的 API key 可用于 embeddings 或直接的 OpenAI 模型， 同时避免原生 Codex app-server 的交互意外通过 API 计费。
显式 Codex API-key 配置文件和本地 stdio env-key 后备使用应用程序服务器登录而不是继承的子进程环境。 WebSocket 应用程序服务器连接不接收网关环境 API-key 回退；使用显式身份验证配置文件或远程应用程序服务器自己的帐户。
Stdio应用程序服务器启动默认继承OpenClaw的进程环境。 OpenClaw 拥有 Codex 应用程序-服务器帐户桥，并将 CODEX_HOME 设置为该代理的 OpenClaw 状态下的每个代理目录。这使得 Codex 配置、帐户、插件 cache/data 和线程状态的范围仅限于 OpenClaw 代理，而不是从操作员的个人 ~/.codex 主目录泄漏。
设置 appServer.homeScope: "user" 以与 Codex Desktop 和 CLI 共享本机 Codex 状态。这种本地用户主模式支持托管 stdio 和显式 Unix 传输。它在设置时使用 $CODEX_HOME，否则使用 ~/.codex，包括本机身份验证、配置、插件和线程。 OpenClaw 跳过应用程序服务器的身份验证配置文件桥。经过验证的所有者可以使用 codex_threads 列出（使用可选的 search 过滤器）、读取、分叉、重命名、存档和取消存档这些线程。在OpenClaw中继续线程之前分叉一个线程；独立的 Codex 进程不协调同一线程的并发写入程序。
homeScope 选择加入适用于普通的harness会话。即使普通会话共享用户主目录，托管网络搜索和最终确定也使用私有临时主目录和 OpenClaw 身份验证。通过 Codex 会话创建的聊天改为使用其私有监督连接，这会保留主分支和未来恢复的本机连接的身份验证和提供程序配置。如果该受监督轮次完成工具工作而没有最终答案，则 OpenClaw 不会借用主机凭据来生成最终答案。它提供 已解决工具后备 ，而无需重复已完成的操作。
在模型锁定的受监督 Chat 中，codex_threads 不能附加到不同的分叉，也不能归档 Chat 绑定的原生线程。列表和仅元数据读取仍然可用。原始转录读取需要 allowRawTranscripts；当它被禁用时，列表搜索也会被拒绝，因为原生搜索可能匹配转录预览。对不属于其他 OpenClaw Chat 的无关线程进行重命名、取消归档、分叉（分离）和归档，需要 allowWriteControls。这两个选项都不能绕过已锁定的绑定。
OpenClaw 不会为正常的本地应用程序服务器启动重写 HOME。 Codex-run 子进程（例如 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 代理的一部分），请显式清点它们：
凭据需要通过敏感迁移路径处理，因为默认的 agent 范围不会直接使用复制或挂载的 codex-home/auth.json。将 <agent-id> 替换为拥有此 Codex home 的已配置 agent：
如果部署需要额外的环境隔离，请将这些变量添加到 appServer.clearEnv：
appServer.clearEnv 仅影响生成的 Codex 应用程序服务器子进程。 OpenClaw 在本地启动规范化期间从此列表中删除 CODEX_HOME 和 HOME：CODEX_HOME 保持指向所选代理或用户范围，而 HOME 保持继承状态，因此子进程可以使用正常的用户主状态。
通过 Codex 登录从 2026.9.4 升级
If openai:default仅通过本机存在Codex登录后，您可以准备2026.9.4在升级到之前2026.9.5，不再提供该覆盖层。对于常规的main共享商店所有者，通过以下方式完成新的设备代码登录OpenClaw并验证持久化的配置文件：
保留 --profile-id：在 2026.9.4 上省略它可以在不同的 ID 下导入并删除旧的覆盖。 openai:default 应出现在上面未过滤的列表中。其他代理 继承共享配置文件 ，包括具有不相关本地凭据的代理。具有相同 ID 的本地配置文件会覆盖它；使用 --agent <id> 单独登录只是为了创建或替换有意的本地 OpenAI 覆盖。