Codex
Codex CLI와 Codex App에서 AGTCloud를 설정하고 사용합니다.
Codex는 OpenAI가 제공하는 코딩 에이전트입니다. 터미널에서 Codex CLI를 사용하거나 데스크톱 App에서 프로젝트와 작업을 관리할 수 있습니다. 사용자 정의 모델 공급업체를 설정하면 Codex에서 AGTCloud의 OpenAI Responses 호환 진입점을 사용할 수 있습니다.
모델마다 도구 호출, 추론, 다중 에이전트 및 컨텍스트 길이의 지원 범위가 다를 수 있습니다. 현재 API Key에 표시되며 Responses 프로토콜을 지원하는 모델을 선택합니다.
준비 사항
시작하기 전에 다음 사항을 확인합니다.
- 터미널 환경과 열려는 로컬 프로젝트를 준비합니다.
- AGTCloud에 가입하고 로그인합니다.
- API Keys 페이지에서 토큰을 생성합니다.
- 모델 목록에서 현재 토큰으로 사용할 수 있고 Responses 프로토콜을 지원하는 모델 ID를 복사합니다.
Codex 설치
현재 환경에 맞는 설치 방식을 선택합니다.
curl -fsSL https://chatgpt.com/codex/install.sh | sh설치 후 터미널을 다시 열고 버전을 확인합니다.
codex --versionAPI Key 설정
Codex는 사용자 정의 Provider가 지정한 환경 변수에서 API Key를 읽습니다. 이 튜토리얼은 OpenAI 또는 다른 플랫폼의 Key와 혼용하지 않도록 독립된 AGTCLOUD_API_KEY를 사용합니다.
임시 설정
다음 설정은 현재 터미널 세션에서만 적용됩니다.
export AGTCLOUD_API_KEY="your-api-key"영구 설정
터미널을 열 때마다 자동 적용하려면 변수를 shell 설정 파일 또는 Windows 사용자 환경 변수에 기록할 수 있습니다.
~/.zshrc를 편집하고 다음을 추가합니다.
export AGTCLOUD_API_KEY="your-api-key"저장한 뒤 설정을 불러옵니다.
source ~/.zshrcAPI Key를 config.toml에 기록하지 않습니다
config.toml에는 환경 변수 이름만 저장합니다. API Key는 로컬 환경 설정에 평문으로 저장되므로 개인의 신뢰할 수 있는 장치에서만 이 방식을 사용합니다.
AGTCloud Provider 설정
Codex의 사용자 수준 설정은 ~/.codex/config.toml에 있습니다. 파일이 이미 있으면 먼저 백업하고 AGTCloud Provider를 기존 설정에 병합하며 다른 설정을 직접 덮어쓰지 않습니다.
mkdir -p ~/.codex
if [[ -f ~/.codex/config.toml ]]; then
cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi~/.codex/config.toml에 다음을 추가합니다.
model_provider = "agtcloud"
model = "MODEL_ID"
[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"| 설정 항목 | 역할 |
|---|---|
model_provider | 기본 모델 공급업체를 AGTCloud로 전환합니다 |
model | Codex가 사용할 모델 ID를 지정합니다 |
base_url | Responses 요청을 이 페이지에 표시된 AGTCloud API 주소로 보냅니다 |
env_key | API Key를 저장하는 환경 변수 이름을 지정합니다 |
wire_api | OpenAI Responses 프로토콜 사용을 지정합니다 |
Provider는 사용자 수준 설정에 있어야 합니다
프로젝트의 .codex/config.toml에는 프로젝트 설정을 저장할 수 있지만 model_provider와 model_providers를 덮어쓸 수 없습니다. 위 Provider 설정은 사용자 디렉터리의 ~/.codex/config.toml에 저장합니다.
모델 선택
MODEL_ID는 교체해야 하는 자리표시자이며 실제 모델 이름이 아닙니다. 모델 목록에서 현재 API Key로 사용할 수 있고 Responses 프로토콜을 지원하는 모델 ID를 복사하여 config.toml의 MODEL_ID를 교체합니다.
Codex CLI에서 /model로 모델을 확인하거나 전환할 수 있습니다. 사용자 정의 Provider의 선택 범위는 Codex 버전과 현재 API Key에 따라 다릅니다. 대상 모델이 표시되지 않으면 config.toml의 model을 직접 갱신합니다.
Codex CLI 사용
프로젝트 디렉터리로 이동
cd /path/to/your/projectCodex 시작
codex현재 설정 확인
Codex에서 다음을 실행합니다.
/status현재 Provider, 모델 및 설정 파일이 예상과 일치하는지 확인합니다. Base URL은 이 페이지에 표시된 /v1 API 주소여야 하며 /v1/v1이 중복되어서는 안 됩니다.
읽기 전용 테스트 수행
README.md가 있는 테스트 프로젝트에 다음을 입력합니다.
README.md를 읽고 이 프로젝트의 용도를 세 가지로 요약해 주세요. 어떤 파일도 수정하지 마세요.내용이 정상적으로 반환되면 기본 연결이 설정된 것입니다. 이 단계에서는 정상적인 API 사용량이 발생합니다.
Codex App 사용
App 다시 시작
~/.codex/config.toml과 환경 변수를 저장한 뒤 Codex App을 완전히 종료하고 다시 엽니다.
로컬 프로젝트 열기
데스크톱 App에서 Codex로 전환하고 민감한 코드가 없는 테스트 프로젝트를 선택합니다.
모델 확인 및 검증
현재 모델이 config.toml과 일치하는지 확인한 뒤 CLI와 동일한 README 읽기 전용 작업으로 검증합니다.
App의 환경 변수 로드는 버전과 실행 방식에 따라 다릅니다
Codex App은 Codex의 로컬 설정을 재사용하지만 데스크톱 애플리케이션이 shell 환경 변수를 로드하는 방식은 버전과 운영 체제에 따라 달라질 수 있습니다. CLI는 사용할 수 있지만 App에서 API Key를 읽지 못하면 App을 완전히 다시 시작한 뒤 사용자 수준 설정과 환경 변수를 확인합니다.
자주 묻는 질문
| 증상 | 우선 확인할 항목 | 조치 |
|---|---|---|
codex 명령을 찾을 수 없음 | 설치 결과 및 PATH | 터미널을 다시 열고 codex --version을 실행하며 필요한 경우 공식 설치 명령을 다시 실행합니다 |
| API Key가 로드되지 않음 | 현재 프로세스에 AGTCLOUD_API_KEY가 적용되는지 여부 | 터미널 또는 App을 다시 열고 사용자 환경 설정을 다시 불러옵니다 |
| Provider 설정이 적용되지 않음 | 프로젝트 수준 .codex/config.toml에 잘못 기록했는지 여부 | model_provider와 model_providers를 ~/.codex/config.toml로 이동합니다 |
요청 경로에 /v1/v1이 나타남 | base_url에 경로가 추가되었는지 여부 | 이 페이지에 표시된 https://api.agtcloud.cn/v1를 그대로 사용합니다 |
401 반환 | API Key 및 환경 변수 | 유효한 API Key를 사용하고 env_key 이름이 일치하는지 확인합니다 |
403 반환 | 토큰 권한, 모델 권한 및 계정 상태 | 콘솔에서 토큰과 모델의 사용 가능 범위를 확인합니다 |
404 반환 | Base URL, Responses 진입점 및 모델 ID | base_url을 확인하고 현재 Key로 사용할 수 있는 모델 ID를 다시 복사합니다 |
| 모델이 없거나 사용 불가 | 모델 표시 여부 및 Responses 프로토콜 지원 | 모델 목록에서 전체 ID를 복사하고 현재 Key로 호출할 수 있는 모델을 선택합니다 |
| CLI는 정상이나 App이 설정을 읽지 못함 | App 버전, 설정 경로 및 환경 변수 | App을 완전히 다시 시작하며 먼저 CLI로 동일한 사용자 수준 설정을 검증합니다 |
| 일부 고급 기능 사용 불가 | 대상 모델 기능 및 현재 어댑터의 지원 범위 | 기본 읽기 전용 작업으로 먼저 검증하며 고급 기능은 실제 호출 결과를 기준으로 합니다 |
원인을 찾기 어려우면 요청 시각, API Base URL, 모델 ID, HTTP 상태 및 민감 정보를 제거한 오류 내용을 기록하고 오류 및 문제 해결을 확인합니다. 전체 API Key를 제출하지 않습니다.
보안 권장 사항
- Codex 전용 API Key를 생성하여 권한 관리와 자격 증명 비활성화를 쉽게 합니다.
- 실제 Key를
config.toml, 코드, 저장소, 스크린샷, 로그 또는 공유 스크립트에 기록하지 않습니다. - 공유 장치 또는 팀 환경에서는 운영 체제의 자격 증명 관리나 조직의 통합 키 배포 방식을 우선 사용합니다.
- API Key 유출이 의심되면 즉시 콘솔에서 비활성화하거나 삭제하고 새 Key를 생성합니다.
다음으로 API Key, Base URL 및 인증, OpenAI Responses 및 오류 및 문제 해결을 읽을 수 있습니다.