如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

为团队自行托管 Codex 配置

通过您运营的 HTTPS 端点向 Codex 提供默认配置和强制设置。

我们建议您的团队使用 ChatGPT 登录 Codex。如果您的套餐支持托管配置,您可以在管理控制台的 Agent 安全 中设置默认值并强制执行配置要求,无需自行运行服务器。

如果您的用户不使用 ChatGPT 登录 Codex,您可以通过自己运营的 HTTPS 服务器向 Codex CLI 和桌面应用分发配置。无论用户直接连接模型提供商还是通过网关连接,Codex 都会在启动时加载您的设置。

客户端限制

桌面应用无法提示您登录配置服务器。如果服务器要求重新登录,请在同一台计算机的终端中运行 codex login,然后重新打开应用。如果应用无法加载强制设置,启动过程会暂停。

配置 Codex 以使用服务器

在测试计算机上,创建或更新系统级 requirements.toml 文件。添加 [config_server] 表,在其中填写配置服务器的基础 URL。在 Linux 和 macOS 上,文件路径为 /etc/codex/requirements.toml,在 Windows 上则为 %ProgramData%\OpenAI\Codex\requirements.toml。在 macOS 上,您也可以通过托管偏好设置分发该表。

[config_server]
base_url = "https://codex-config.example.com/team"

只有本地管理员控制的强制配置才能指定服务器。将其余策略迁移到端点时,请将此表保留在计算机上。

向配置服务器进行身份验证(可选)

默认情况下,Codex 会尝试在不提供凭据的情况下获取配置。如果服务器要求登录,请将 [config_server.oauth] 添加到同一个 requirements.toml 文件中。Codex 使用 OAuth 授权码流程,并采用授权码交换证明密钥(PKCE)机制。

[config_server.oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "codex-policy"
redirect_port = 43127

本例中的重定向 URI 为 http://127.0.0.1:43127/callback。如果您的身份提供商接受任意可用端口上的环回回调,您可以省略 redirect_port。Codex 会在 Authorization 请求头中发送访问令牌。服务器必须先验证该令牌,再返回配置包。

提供 Codex 配置

通过 HTTPS 端点提供您的托管配置。Codex CLI 获取配置包时,会使用本地 requirements.toml 中的基础 URL 发送 GET 请求:

GET {config_server.base_url}/codex/config/bundle

使用上文初始配置示例中的 base_url 时,Codex 会发送以下请求:

GET https://codex-config.example.com/team/codex/config/bundle

服务器应返回 200 OK,并在响应正文中提供 JSON 配置包。

配置包格式

配置包将 TOML 条目分为两个数组:

  • config_toml.enterprise_managed 包含要应用的默认设置。每个条目的 contents 字段都是 config.toml 文本。
  • requirements_toml.enterprise_managed 包含要强制执行的配置要求。每个条目的 contents 字段都是 requirements.toml 文本。

每个数组条目都有三个字符串字段:id、name(显示名称)和 contents。对于不需要的类别,请使用空数组。

以下示例将网页搜索的默认值设为 disabled,并通过 allowed_web_search_modes 强制使用该值。

{
  "config_toml": {
    "enterprise_managed": [
      {
        "id": "search-default",
        "name": "Default web search",
        "contents": "web_search = 'disabled'"
      }
    ]
  },
  "requirements_toml": {
    "enterprise_managed": [
      {
        "id": "search-policy",
        "name": "Allowed web search modes",
        "contents": "allowed_web_search_modes = ['disabled']"
      }
    ]
  }
}

在 Codex 中验证配置

  1. 在测试计算机的项目目录中打开终端,运行 codex。如果系统提示登录,请使用公司账号完成登录。
  2. 在 Codex CLI 的交互式提示符下输入 /debug-config,然后按 Enter 键。
  3. 如果服务器提供默认设置,请在 Config layer stack 下查找相应条目的名称和 ID。如果使用上面的示例,请查找 enterprise-managed (Default web search, search-default) (enabled)。
  4. 如果服务器提供强制设置,请在 Requirements 下找到一项您强制执行的设置,并核对旁边列出的策略来源。

Codex 可以使用缓存的设置启动,并在后台刷新这些设置。更改服务器上的策略后,请等待 Codex 刷新策略,然后启动新会话并再次检查,之后再将策略推广到其他计算机。