팀의 Codex 설정 서버 직접 운영하기

사용자가 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는 PKCE(Proof Key for Code Exchange)를 적용한 OAuth 인가 코드 플로우를 사용합니다.

[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가 설정을 갱신할 때까지 기다리세요. 그런 다음 새 세션을 시작해 설정을 다시 확인한 후 다른 컴퓨터에 정책을 배포하세요.