며칠 전, AWS는 Amazon Bedrock에서 OpenAI의 GPT-5.6을 출시했습니다. 저는 여러분이 이미 보유하고 있는 자격 증명(credentials)을 사용하여 Bedrock API를 통해 이러한 모델들을 직접 사용할 수 있도록 Codex CLI를 구성하는 방법을 보여드리겠습니다.

설정에 따라 Codex는 Bedrock의 GPT 모델들과 즉시(out of the box) 작동할 수도 있습니다. 다음을 시도해 보세요:

codex \
  -c model_providers.amazon-bedrock.aws.region="us-east-1" \
  -c model_provider="amazon-bedrock" \
...

만약 이것이 Codex CLI를 시작하고 여러분의 프롬프트에 응답한다면, 바로 시작할 준비가 된 것입니다! 그리고 매번 -c 플래그를 전달하고 싶지 않다면, ~/.codex/config.toml 파일 상단에 다음 두 줄을 추가하세요:

model_providers.amazon-bedrock.aws.region = "us-east-1"
model_provider = "amazon-bedrock"

만약 작동하지 않았거나, 전통적인 AWS 자격 증명 대신 Bedrock API Key를 사용하고 싶다면 계속 읽어주세요.

그렇지 않다면, 즐거운 시간 보내세요! 그리고 GPT-5.6 Sol을 사용하는 Codex와 Fable을 사용하는 Claude Code 중 어떤 것을 더 선호하는지 댓글을 남겨주세요.

로컬 AWS 자격 증명(credentials)을 이용한 설정

Codex CLI에는 내장된 Bedrock 프로바이더(provider)가 포함되어 있습니다. 이를 사용하려면 AWS CLI가 설치되어 있어야 하며, 필요한 권한이 구성되어 있어야 합니다.

이 포스트의 예제는 환경 변수(environment variables)를 설정하기 위해 export를 사용하며, 이는 macOS와 Linux에서 작동합니다. Windows에서는 명령 프롬프트(Command Prompt)의 경우 set으로, PowerShell의 경우 $env:로 대체하여 사용하세요.

AWS CLI 테스트

aws sts get-caller-identity --output=yaml

AWS CLI가 설치되어 있다면, 다음과 같은 정보를 반환해야 합니다 (셸로 돌아가려면 q를 누르세요):

오류가 발생하면 AWS CLI quickstart 또는 문제 해결 가이드를 따르세요.

권한 확인하기

사용자의 AWS 구성은 다양한 모델을 OpenAI와 호환되는 Responses 및 Chat Completions API를 사용하여 제공하는 Bedrock 엔드포인트인 bedrock-mantle을 호출할 권한이 필요합니다. 액세스 권한을 얻는 가장 빠른 방법은 사용하거나 역할을 AmazonBedrockLimitedAccess (arn:aws:iam::aws:policy/AmazonBedrockLimitedAccess)라는 AWS 관리형 정책을 첨부하는 것입니다. 이 정책은 베어러 토큰 호출을 포함하여 클래식한 bedrock-runtime API와 bedrock-mantle 모두를 포괄합니다.

Codex 테스트하기

Codex CLI를 설치했는지 확인한 다음, 다음을 실행하세요:

codex exec \
  --skip-git-repo-check \
  -c model_providers.amazon-bedrock.aws.region="us-east-1"
...

--skip-git-repo-check 플래그는 Git 저장소나 신뢰할 수 있는 폴더 외부에서는 codex exec이 실행되는 것을 거부하기 때문에 있습니다. Git 저장소 내부에서 명령을 실행하는 경우, 이 줄은 생략할 수 있습니다.

만약 아래와 같은 모델 응답을 받는다면, Bedrock의 GPT 모델과 성공적으로 통신한 것입니다.

OpenAI Codex v0.144.5
--------
...
...

단어 하나짜리 프롬프트에 대한 9,580 토큰은 Codex가 요청과 함께 자체 시스템 프롬프트와 도구 정의를 전송한다는 것을 보여주며, 이는 콘텐츠 이전에 약 9,400~9,500 토큰의 오버헤드를 차지합니다. 비용 및 컨텍스트 예산을 추정할 때 이를 염두에 두세요.

provider 라인은 귀하가 OpenAI에 직접 통신하는 것이 아니라 Bedrock과 통신하고 있음을 확인해주며, model 라인은 사용된 모델을 보여줍니다. 이 예시에서는 작성 시점의 Codex 기본 모델인 GPT-5.5가 사용되었습니다.

다른 모델을 사용하려면 명령의 일부로 다음과 같이 구성하십시오:

codex exec \
  --skip-git-repo-check \
  -c model_providers.amazon-bedrock.aws.region="us-east-1" \
...

만약 codex exec가 권한 오류(permission error)로 실패한다면, 한 단계 뒤로 돌아가 AmazonBedrockLimitedAccess 정책이 연결되어 있는지 확인하십시오. 그 외의 모든 사항은 이 포스트의 마지막에 있는 주의 사항(gotchas)을 참조하십시오.

Bedrock API 키를 이용한 설정

Bedrock과 통신하기 위해 AWS 자격 증명 체인(AWS credential chain)이 반드시 필요한 것은 아닙니다. CI 러너(CI runner)나 새로 생성된 컨테이너와 같이 AWS CLI가 설치되어 있지 않거나 구성되지 않은 환경에서는 Bedrock API 키를 일반적인 베어러 토큰 (bearer token)으로 사용할 수 있으며, 이것이 권장되는 방식입니다. 키를 생성하는 방법에는 두 가지가 있습니다. 별도의 설정이 전혀 필요 없는 Amazon Bedrock 콘솔을 사용하는 방법과, 명령줄(command line)을 위한 aws-bedrock-token-generator 라이브러리를 사용하는 방법입니다.

옵션 1: AWS 관리 콘솔 (AWS Management Console)

1. Amazon Bedrock 콘솔을 엽니다.
2. 왼쪽 탐색 창에서 API keys를 선택합니다.
3. Short-term API keys 탭에서 Generate short-term API keys를 클릭합니다.
4. 즉시 키를 복사하십시오. 콘솔에는 다시 표시되지 않습니다. 만약 복사하는 것을 잊었거나 키가 만료되었다면, 다시 Generate short-term API keys를 클릭하여 새 키를 생성하면 됩니다.
5. 키를 AWS_BEARER_TOKEN_BEDROCK 환경 변수에 저장합니다:

   export AWS_BEARER_TOKEN_BEDROCK="bedrock-api-key-..."

중요: 키는 현재 위치한 AWS 리전 (AWS Region)으로 범위가 제한되므로, 필요한 경우 콘솔에서 먼저 리전을 전환하십시오. 키는 콘솔 세션이 만료될 때 함께 만료되며, 최대 12시간 동안 유효합니다.

옵션 2: 명령줄 (the command line)

AWS는 Python 및 JavaScript용 aws-bedrock-token-generator 라이브러리를 제공하며, 이는 AWS CLI에 설정된 자격 증명(credentials)으로부터 베어러 토큰 (bearer token)을 유도합니다. 이 옵션을 사용하려면 AWS CLI가 설치 및 설정되어 있어야 합니다 (위에서 설명한 대로 aws sts get-caller-identity를 통해 테스트하십시오).

Python:

pip를 사용하여 Python용 토큰 생성기를 설치합니다:

pip install aws-bedrock-token-generator

그 다음 키를 생성하여 AWS_BEARER_TOKEN_BEDROCK에 저장합니다:

export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK=$(python3 << 'EOF'
from aws_bedrock_token_generator import provide_token
...

JavaScript:

npm을 사용하여 JavaScript용 토큰 생성기를 설치합니다:

npm install @aws/bedrock-token-generator

그 다음 키를 생성하여 AWS_BEARER_TOKEN_BEDROCK에 저장합니다:

export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK=$(node --input-type=module << 'EOF'
import { getTokenProvider } from '@aws/bedrock-token-generator';
...

Python 및 JavaScript 토큰 생성기 모두 기본 자격 증명 제공자 체인 (default credential provider chain)을 사용하므로, AWS CLI가 사용 중인 프로필이나 세션을 그대로 가져옵니다. 키는 단일 AWS 리전 (AWS Region)으로 범위가 제한되며, 기반이 되는 자격 증명이 만료될 때 함께 만료되지만 최대 12시간까지만 유효합니다.

토큰 생성은 계산 비용이 저렴하고 무료이므로, 토큰을 캐싱(caching)하는 대신 매 요청 전에 provide_token()을 호출할 수 있습니다.

키 테스트하기

이 키는 Codex가 등장하기 전이라도 bedrock-mantle API에 직접 사용할 수 있는 베어러 토큰 (bearer token)입니다. 다음은 OpenAI 호환 Responses API를 통한 GPT-5.6 Luna의 예시입니다:

curl -X POST \
  "https://bedrock-mantle.$AWS_REGION.api.aws/openai/v1/responses" \
  -H "Content-Type: application/json" \
...

동일한 키는 Bedrock Runtime API 및 권한이 허용하는 다른 모든 모델에서도 작동합니다:

curl -X POST \
  "https://bedrock-runtime.$AWS_REGION.amazonaws.com/model/us.anthropic.claude-sonnet-5/converse" \
  -H "Content-Type: application/json" \
...

API 키를 사용하여 Codex 사용하기

AWS_REGION이 설정되어 있고 키가 AWS_BEARER_TOKEN_BEDROCK에 저장되어 있다면, Codex를 Bedrock으로 직접 지정할 수 있습니다. 두 개의 환경 변수(environment variables)와 두 개의 -c 플래그만 있으면 설정이 완료됩니다:

export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK="bedrock-api-key-..."

...

두 변수 모두 Codex에서 임의로 만든 것이 아닌 표준 AWS 명칭이므로, 별도로 연결할 작업은 없습니다. Codex는 SDK 자격 증명 체인 (credential chain)으로 넘어가기 전에 AWS_BEARER_TOKEN_BEDROCK을 확인하며, AWS_REGION은 어떤 리전 (region)의 엔드포인트 (endpoint)를 호출할지 알려줍니다. 이는 AWS CLI가 설치되어 있지 않고 Codex 설정이 전혀 되어 있지 않은 머신에서도 작동합니다.

모델이 실행되는 리전 선택하기

이 글을 쓰는 시점을 기준으로, GPT-5.6 모델들은 모든 AWS 리전에서 실행되지 않으며, 모든 모델이 동일한 리전에서 실행되는 것도 아닙니다. 이 포스트의 모든 내용은 API 키를 포함하여 리전 범위 (region-scoped)로 제한되므로, 아래 표에서 리전을 선택하여 일관되게 사용하십시오:

세 모델 모두 us-east-1 및 us-east-2에서 사용할 수 있으므로, 시작 단계에서는 이 중 하나를 기본값으로 사용하는 것이 편리합니다. 모델이 없는 리전에 요청하면 The model 'openai.gpt-5.6-sol' does not exist와 같은 HTTP 404 오류가 반환됩니다.

시간이 지남에 따라 모델들은 추가적인 리전으로 배포될 가능성이 높습니다. 모델 가용성을 확인하려면...

• 모델 카드(Via the model cards)를 통해 확인하기 - Amazon Bedrock 문서의 각 모델 페이지(GPT-5.6 Sol, Terra, 그리고 Luna)에는 현재 리전 테이블이 표시되어 있습니다. 무언가를 구성하기 전에 반드시 거기서 확인하십시오.

• 명령줄(From the command line)에서 확인하기 - AWS_BEARER_TOKEN_BEDROCK을 설정한 후, bedrock-mantle Models API를 사용하여 특정 리전이 실제로 어떤 모델들을 호스팅하는지 문의할 수 있습니다. 확인할 원하는 리전을 설정하십시오:

  export AWS_REGION=us-east-1

그런 다음, jq를 사용하여 실행합니다:

  curl -s "https://bedrock-mantle.$AWS_REGION.api.aws/v1/models" \
       -H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
  | jq -r '.data[].id' | sort

리전에 따라 다양한 제공업체의 수십 개의 모델 목록을 볼 수 있습니다:

  anthropic.claude-fable-5
  anthropic.claude-haiku-4-5
  ...
...

만약 jq가 설치되어 있지 않다면, grep이 대체재로 작동합니다:

  curl -s "https://bedrock-mantle.$AWS_REGION.api.aws/v1/models" \
       -H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
  | grep "gpt-5.6"

이 경우, 본문이 단일 JSON 라인이기 때문에 일치하는 항목을 찾으면 전체 응답이 출력됩니다. 만약 빈 결과가 나온다면, 검색한 모델들이 선택된 리전에서 사용 불가능하다는 의미입니다.

참고: 이 URL의 bedrock-mantle은 Bedrock의 두 가지 추론 엔드포인트(inference endpoints) 중 더 최신 버전입니다. 클래식 bedrock-runtime 엔드포인트는 InvokeModel 및 Converse를 제공하는 반면, bedrock-mantle은 OpenAI 호환 Responses 및 Chat Completions API를 제공합니다. GPT-5.6 모델은 오직 mantle에서만 실행되는데, 이는 제가 처음 이 모델들을 찾으려고 했을 때 겪었던 의문점을 설명해 줍니다. 즉, aws bedrock list-foundation-models 명령어로 이 모델들이 나열되지 않는 이유입니다 (아래의 주의 사항 참조).

모델 선택하기

세 가지 GPT-5.6 모델은 하나의 모델에 대한 크기 계층(size tiers)이라기보다 실제로 서로 다른 제품입니다.

Sol은 최첨단 추론(frontier reasoning)과 에이전트 기반 코딩(agentic coding)을 위해 구축된 플래그십 모델입니다. Terra는 일상적인 프로덕션 작업을 위한 균형 잡힌 모델로, 대부분의 Codex 세션에서 제가 가장 먼저 시도해 볼 모델입니다. Luna는 분류(classification), 요약(summarization), 라우팅(routing)을 위해 구축되었으며, 이는 파이프라인 내의 codex exec에 적합합니다.

대화형 CLI(interactive CLI)에서는 한 번의 명령으로 모델을 전환할 수 있습니다:

› /model

Select Model and Effort
...