Codex는 어떤 모델을 사용할지, 어떤 API를 호출할지, 에이전트가 묻지 않고 어디까지 작업할 수 있는지 등의 설정을 하나의 파일인 config.toml에 저장합니다. 2026년에 형식이 여러 차례 바뀌었으며, 연초에 작성된 많은 가이드의 설정을 사용하면 이제 Codex가 시작되지 않습니다.
이 가이드에서는 먼저 작동하는 설정 파일을 살펴보고, 이어서 대부분의 사용자가 변경하는 프로필, 프로젝트 설정, 샌드박스 및 프록시를 알아봅니다. 마지막에는 자주 볼 수 있는 오류와 각 오류의 의미를 정리했습니다. OpenAI 문서를 참고하고 2026년 10월 19일 Codex CLI 0.162.1에서 실행해 확인했습니다. 예제에서는 AIHubMix를 공급자로 사용하지만, OpenAI Responses API를 지원하는 게이트웨이라면 모두 같은 방식으로 사용할 수 있습니다.
요약
- 파일은
~/.codex/config.toml이며, Windows에서는C:\Users\<you>\.codex\config.toml입니다. - 사용자 지정 공급자를 설정하려면
base_url,wire_api = "responses",env_key가 필요합니다. API 키는 환경 변수에 넣습니다. - 프로필은 이제 별도의 파일인
~/.codex/<name>.config.toml에 저장하며,--profile <name>으로 선택합니다. - 저장소의
.codex/config.toml은 신뢰하는 프로젝트에서만 작동하며 공급자는 변경할 수 없습니다. - 수정할 때마다 Codex를 다시 시작하세요. Codex는 시작할 때만 파일을 읽습니다.
config.toml 파일 위치
기본 설정은 ~/.codex/config.toml에 저장됩니다. CLI와 IDE 확장 프로그램이 모두 이 파일을 읽습니다. 파일이 아직 없다면 새로 만드세요.
다음 두 위치에서 설정을 추가로 지정할 수 있습니다.
- 프로필 파일인
~/.codex/<name>.config.toml은--profile <name>옵션으로 Codex를 시작할 때만 사용합니다. - 프로젝트 파일인 저장소 내
.codex/config.toml은 팀에서 공유할 설정을 지정하는 데 사용합니다.
Windows에서 WSL2로 Codex를 실행하면 Windows 경로가 아니라 Linux 홈 디렉터리의 /home/<you>/.codex/config.toml을 읽습니다. CODEX_HOME이 설정되어 있으면 Codex는 ~/.codex 대신 해당 폴더를 사용합니다.
최소한의 작동 설정
다음은 Codex 요청을 AIHubMix로 보내는 완전한 ~/.codex/config.toml 파일입니다.
model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"
[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"
model은 호출할 모델 ID이고,model_reasoning_effort는 기본 추론 수준입니다.model_provider는[model_providers.<name>]에 지정한 이름과 일치해야 합니다.openai,ollama,lmstudio는 Codex 내장 공급자에서 이미 사용하는 이름이므로 지정하지 마세요.base_url은 공급자의 API 주소입니다. 이제 Codex가 허용하는wire_api = "responses"값만 사용할 수 있습니다.env_key에는 환경 변수 자체가 아니라 환경 변수의 이름을 지정합니다.
그런 다음 AIHubMix 콘솔에서 발급한 키로 해당 변수를 설정합니다.
# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...
# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."
새 터미널에서 codex를 실행하고 아무 질문이나 해 보세요. 답변이 오면 공급자가 작동하는 것입니다. Codex 로그인 여부는 여기서 중요하지 않습니다. codex login으로 로그인할 때 사용한 키는 사용자 지정 공급자에 전송되지 않습니다.
프로필: 설정별 파일 하나
프로필에는 기본 설정과 다른 설정만 담습니다. 예를 들어 코드 검토를 위해 추론 수준을 높이거나 샌드박스를 읽기 전용으로 설정할 수 있습니다. 각 프로필은 config.toml과 같은 위치에 별도 파일로 만들고, 키를 최상위 수준에 작성합니다.
# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
codex --profile review
Codex 0.134.0에서 이 방식이 바뀌었습니다. 이전 가이드에서는 config.toml 안에 [profiles.review] 테이블을 만들고 profile = "review"로 프로필을 선택했습니다. 이제 Codex는 해당 선택자가 있으면 시작을 거부합니다. [profiles.review] 테이블만 남아 있으면 아무 메시지 없이 무시되므로 설정이 조용히 적용되지 않습니다. 이전 설정을 옮기려면 각 테이블의 키를 ~/.codex/<name>.config.toml로 옮긴 다음 테이블과 profile = ... 줄을 삭제하세요. 자세한 내용은 OpenAI의 고급 설정 가이드를 참고하세요.
프로젝트 설정: .codex/config.toml
저장소에 .codex/config.toml을 두면 팀에서 기본 모델, 추론 수준 또는 샌드박스 모드를 공유할 수 있습니다. Codex는 사용자의 ~/.codex/config.toml에서 신뢰하는 프로젝트로 표시한 경우에만 이 파일을 읽습니다.
[projects."/Users/you/code/my-app"]
trust_level = "trusted"
프로젝트 파일에서는 요청을 보낼 위치를 바꿀 수 없습니다. Codex는 해당 파일의 model_provider, model_providers, openai_base_url, profile, notify 및 몇 가지 다른 키를 무시하고, 이때 경고를 표시합니다. 공급자 설정은 ~/.codex/config.toml에 두세요. 프로젝트에서 모델을 선택할 수는 있으며, 요청은 사용자가 설정한 공급자로 전송됩니다.
어떤 설정이 우선 적용되나요?
같은 키가 여러 위치에 설정되어 있을 때 적용되는 우선순위는 OpenAI의 설정 기본 사항에 나와 있습니다. 높은 순서부터 정리하면 다음과 같습니다.
-c재정의를 포함한 명령줄 플래그- 프로젝트의
.codex/config.toml --profile로 선택한 프로필- 사용자의
~/.codex/config.toml - 시스템 설정 파일인
/etc/codex/config.toml - Codex 내장 기본값
프로젝트 파일의 우선순위가 프로필보다 높다는 점에 유의하세요. 프로필 설정이 적용되지 않는 것 같다면 저장소의 .codex/config.toml에 같은 키가 설정되어 있는지 확인하세요.
한 번만 실행할 때 설정을 변경하려면 -c를 사용하세요.
codex -c model_reasoning_effort=high
샌드박스 및 승인
Codex가 자체적으로 수행할 수 있는 작업은 두 키로 제어합니다. sandbox_mode는 명령어가 접근할 수 있는 범위를 설정하고, approval_policy는 언제 사용자에게 확인을 요청할지 설정합니다.
| sandbox_mode | 명령어가 수행할 수 있는 작업 |
|---|---|
| read-only | 파일을 읽을 수 있으며, 그 이상의 작업에는 승인이 필요합니다. |
| workspace-write | 프로젝트 폴더와 임시 폴더에 쓸 수 있습니다. |
| danger-full-access | 샌드박스 없이 무엇이든 할 수 있습니다. |
| approval_policy | Codex가 확인을 요청하는 시점 |
|---|---|
| on-request | 샌드박스 제한을 벗어나야 할 때 |
| never | 확인하지 않습니다. 차단된 명령어는 실패합니다. |
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = true # off by default
두 설정은 서로 독립적입니다. never는 확인 요청을 중단하지만 샌드박스 제한을 완화하지는 않습니다. workspace-write에서는 network_access = true로 설정하지 않는 한 명령어가 네트워크에 접근할 수 없습니다.
프록시 사용
Codex의 config.toml에는 프록시 설정이 없습니다. 표준 환경 변수를 사용합니다.
export HTTPS_PROXY=http://127.0.0.1:7890 # your proxy address
export NO_PROXY=localhost,127.0.0.1
OpenAI 문서에는 이 내용이 나와 있지 않아 Codex 0.162.1에서 테스트했습니다. 사용자 지정 공급자 요청을 포함한 요청은 HTTPS_PROXY(또는 ALL_PROXY)를 거쳤고, NO_PROXY에 지정된 호스트에는 직접 연결했습니다. PAC 파일은 지원하지 않으므로 프록시 주소 자체를 입력하세요. 회사 프록시에서 별도의 루트 인증서를 사용한다면 환경 변수 참조에 설명된 대로 CODEX_CA_CERTIFICATE에 해당 인증서 경로를 지정하세요.
/model에 더 많은 모델 표시하기
/model 선택기에는 OpenAI 모델만 표시됩니다. GLM, Claude, Gemini 또는 DeepSeek 모델을 선택기에 표시하려면 모델 카탈로그를 추가하세요. 최상위 수준의 model_catalog_json 키로 JSON 파일을 지정하면 됩니다. 이 키는 첫 번째 [table] 줄보다 앞에 두세요. 그렇지 않으면 TOML에서 해당 키를 테이블의 일부로 취급하여 Codex가 무시합니다.
카탈로그를 추가하면 기본 목록이 대체됩니다. 각 항목에 여러 필드가 필요하므로 직접 작성하기보다 생성하는 편이 좋습니다. AIHubMix Codex CLI 가이드에는 AIHubMix의 상위 30개 모델을 바탕으로 카탈로그를 생성하는 스크립트가 있습니다. 데스크톱 앱의 선택기에는 사용자 지정 모델이 계속 표시되지 않을 수 있으므로(openai/codex#19694) 터미널에서 모델을 전환하세요.
일반적인 오류와 그 의미
다음은 Codex 0.162.1에서 각 실수에 대해 표시한 메시지입니다.
legacy profile = "..." config is no longer supported
config.toml에 이전 방식의 profile = "..." 줄이 남아 있습니다. 위에 설명된 대로 프로필을 별도 파일로 옮기세요. 이전 [profiles.x] 테이블이 있는 상태에서 --profile x를 실행해도 --profile x cannot be used while ... contains legacy ... config와 비슷한 오류가 발생합니다.
wire_api = "chat" is no longer supported
Codex는 더 이상 Chat Completions API를 지원하지 않습니다. wire_api = "responses"로 변경하세요. Chat Completions만 제공하는 공급자는 변환 프록시 없이는 사용할 수 없습니다.
model_providers contains reserved built-in provider IDs
공급자 이름을 openai, ollama 또는 lmstudio로 지정했습니다. 테이블 이름과 model_provider 값을 다른 이름으로 변경하세요.
approval_policy = "untrusted" is no longer supported
해당 줄을 삭제하거나 on-request를 사용하세요.
Missing environment variable: AIHUBMIX_API_KEY
env_key에 지정한 변수가 Codex를 시작한 터미널에 설정되어 있지 않습니다. 새 터미널을 열거나 source ~/.zshrc를 실행한 뒤 Codex를 다시 시작하세요.
401 Unauthorized after a few "Reconnecting..." lines
요청이 키 없이 전송되었습니다. 공급자 테이블에 env_key가 설정되어 있는지 확인하세요. auth.json에 저장된 로그인 정보는 사용자 지정 공급자에 사용할 수 없습니다.
Model metadata for ... not found. Defaulting to fallback metadata
Codex에 해당 모델의 기본 설정이 없다는 뜻이며, OpenAI 이외의 모델에서는 정상입니다. 요청은 계속 작동합니다. 올바른 설정을 사용하고 /model에 해당 모델을 표시하려면 모델 카탈로그를 추가하세요.
Ignored unsupported project-local config keys
저장소의 .codex/config.toml에 사용자의 설정 파일에서만 작동하는 키가 설정되어 있습니다. 보통 model_provider가 원인입니다. 해당 키를 ~/.codex/config.toml로 옮기세요.
missing field base_instructions
모델 카탈로그의 항목에 필수 필드가 누락되어 Codex가 파일 전체를 거부합니다. 직접 수정하지 말고 스크립트를 사용해 카탈로그를 다시 생성하세요.
설정이 적용되지 않을 때
- 설정을 수정한 뒤 Codex를 다시 시작하세요.
- 최상위 키가 첫 번째
[table]줄보다 앞에 있는지 확인하세요. - 저장소의
.codex/config.toml을 확인하세요. 이 파일은 프로필보다 우선 적용됩니다. - 남아 있는
[profiles.x]테이블이 있는지 확인하세요. - 설치, 설정 및 로그인을 점검하는
codex doctor를 실행하세요.
OpenAI, Anthropic, Google, Zhipu, DeepSeek 등의 모델을 하나의 키로 Codex에서 사용하려면 AIHubMix가 Responses API를 통해 https://aihubmix.com/v1에서 모델을 제공합니다. 위의 최소 설정으로 시작한 다음, /model에서 모델을 전환하고 싶다면 모델 카탈로그를 추가하세요.
FAQ
Codex config.toml 파일은 어디에 있나요?
macOS와 Linux에서는 ~/.codex/config.toml에 있고, Windows에서는 C:\Users<you>.codex\config.toml에 있습니다. CODEX_HOME이 설정되어 있으면 대신 해당 폴더에 있습니다.
config.toml을 변경한 후 Codex를 다시 시작해야 하나요?
예. Codex는 시작할 때 파일을 읽으므로 터미널 세션이나 앱을 종료한 뒤 다시 여세요.
Codex에서 "legacy profile config is no longer supported"라고 표시되는 이유는 무엇인가요?
Codex 0.134.0부터 config.toml 안에 정의된 프로필을 지원하지 않습니다. 각 프로필을 ~/.codex/name.config.toml로 옮기고, 기존 줄을 삭제한 다음 --profile name으로 Codex를 시작하세요.
wire_api = "chat"을 계속 사용할 수 있나요?
아니요. Codex는 wire_api = "responses"만 허용합니다. Chat Completions만 지원하는 제공업체를 사용하려면 Responses API로 변환해 주는 프록시가 필요합니다.
Codex에 로그인했는데 사용자 지정 제공업체에서 401 오류가 반환되는 이유는 무엇인가요?
auth.json의 로그인 키는 사용자 지정 제공업체로 전송되지 않습니다. 제공업체 테이블에 env_key를 추가하고 터미널에서 해당 변수를 설정하세요.
Codex는 HTTPS_PROXY를 사용하나요?
예. Codex 0.162.1에서 테스트한 결과, 요청은 HTTPS_PROXY를 거쳤으며 NO_PROXY에 등록된 호스트는 우회했습니다. PAC 파일은 지원하지 않습니다.
프로젝트의 .codex/config.toml에서 model_provider가 무시되는 이유는 무엇인가요?
프로젝트 파일은 요청이 전송되는 위치를 변경할 수 없으므로 저장소에서 트래픽을 다른 곳으로 돌릴 수 없습니다. 제공업체는 ~/.codex/config.toml에 지정하세요. 프로젝트 파일에서는 여전히 모델을 설정할 수 있습니다.
출처
- 기본 설정, OpenAI
- 고급 설정, OpenAI
- 설정 참조, OpenAI
- Codex CLI 통합 가이드, AIHubMix
- Codex CLI 프록시 설정: SOCKS, HTTP 및 기업 네트워크, Daniel Vaughan
