Codex CLI 치트시트

Amazon Bedrock 프로바이더는 설정된 명령에서 AWS 자격증명을 받아 사용할 수 있다.
가져온 자격증명은 캐시되고 만료 시점에 맞춰 갱신되며 인증 실패에서도 복구하므로, 수명이 짧은 자격증명을 쓰는 환경에서 세션마다 값을 다시 주입하는 부담을 줄일 수 있다 (0.155.0~).

활용

• 외부 자격증명 명령이 AWS 키를 발급하는 환경 → Bedrock이 해당 명령에서 자격증명을 받아 캐시
• 장시간 세션 중 자격증명이 만료되는 상황 → 만료 기준 갱신과 인증 복구로 Bedrock 연결 유지
• 명령 기반 자격증명 지원 버전으로 업데이트:

  npm install -g @openai/codex@0.155.0

  복사

지원되는 Mac의 로컬 TUI 세션에서는 MCP 요청을 Touch ID로 확인할 수 있다.
MCP 도구가 사용자 확인을 요구할 때 기기에서 직접 본인 확인을 마칠 수 있어, 외부 도구 요청에 로컬 사용자 확인 단계를 더할 수 있다 (0.155.0~).

활용

• 로컬 TUI에서 MCP 요청의 사용자 확인이 필요한 상황 → 표시된 Touch ID 요청을 기기에서 확인
• Mac에서 MCP 도구를 사용하는 세션을 시작하는 상황 → 지원 버전으로 업데이트한 뒤 로컬 TUI에서 요청 처리:

  npm install -g @openai/codex@0.155.0
  codex

  복사

주의

Touch ID 확인은 지원되는 Mac의 로컬 TUI 세션에서 제공된다.

TUI 상태 행에서 진행 중인 추론 요약을 실시간으로 확인하고, turn이 성공하면 완료 시각을 볼 수 있다.
오래 걸리는 작업의 현재 방향과 종료 시점을 같은 화면에서 파악할 수 있어 진행 여부를 확인하려고 별도 로그를 오갈 필요가 줄어든다 (0.155.0~).

활용

• 긴 분석이나 구현이 진행 중인 상황 → 상태 행의 실시간 추론 요약으로 현재 작업 방향 확인
• 성공한 turn의 종료 시점을 확인해야 하는 상황 → 완료 시각을 보고 후속 작업 시작 시점 판단
• 해당 표시가 포함된 버전으로 업데이트:

  npm install -g @openai/codex@0.155.0

  복사

ExternalMessage를 동기·비동기 run() 또는 turn()에 넘기면 외부 콘텐츠로 새 turn을 시작하거나 진행 중인 일반 turn에 합류시킬 수 있다.
외부 콘텐츠는 도구 수준 권한으로 전달되고 사용자 승인을 부여하지 않으며, 각 소비자는 독립된 이벤트 스트림을 받는다.
배포 알림이나 외부 시스템 이벤트를 진행 중인 작업에 연결하면서도 원래 사용자의 권한과 구분할 수 있다 (0.154.0~).

활용

• 외부 알림으로 새 turn 시작 → ExternalMessage를 run() 입력으로 전달:

  result = thread.run(external_message)

  복사
• 진행 중인 일반 turn에 외부 이벤트 합류 → turn()에 전달하고 별도 이벤트 스트림 소비:

  handle = thread.turn(external_message)

  복사
• 비동기 워커에서 같은 흐름 사용 → 비동기 run() 또는 turn()에 ExternalMessage 전달

주의

직접 만들었거나 실행 도중 합류한 turn handle에는 연결 시점 이후 이벤트만 전달된다.
앞선 출력이 필요하면 thread.read(include_turns=True)로 저장된 이력을 읽는다.
사용자 지정 codex_bin을 쓰는 경우 이 기능에는 Codex CLI 0.151.0 이상이 필요하다.

Python SDK에서 resume·fork 응답의 이력 포함 여부를 include_turns로 선택하고, 새 turn 하나에만 turn_service_tier를 적용하거나 호출자를 source 메타데이터로 남길 수 있다.
이력 선택은 반환 응답만 바꾸며 모델 컨텍스트는 바꾸지 않고, 옵션을 생략하면 기존 기본값이 유지된다.
호출마다 필요한 응답과 실행 속성만 지정할 수 있어 장기 세션을 다루는 자동화가 더 명확해진다 (0.154.0~).

같은 버전부터 Python SDK의 추론 강도 값에 max와 ultra가 추가된다.
지원하는 모델을 사용하는 자동화에서는 복잡한 turn에 더 높은 추론 강도를 선택할 수 있다 (0.154.0~).

활용

• 재개·분기 직후 저장된 turn 이력까지 필요 → include_turns=True로 호출
• 핸들을 받은 뒤 저장 이력 조회:

  history = thread.read(include_turns=True)

  복사
• 새 turn 하나만 별도 서비스 티어로 실행 → turn_service_tier 지정
• 호출 출처를 결과에 남겨야 하는 통합 → source 메타데이터 지정
• 지원 모델의 복잡한 작업에 높은 추론 강도 적용 → max 또는 ultra 선택

주의

사용자 지정 codex_bin을 쓰는 경우 include_turns와 새 turn별 옵션에는 Codex CLI 0.151.0 이상이 필요하다.

Python SDK에서 일부 notification payload가 정식 타입으로 제공된다.
알려진 알림은 일반 .params 대신 타입에 정의된 명명 필드를 읽고, 알 수 없거나 유효하지 않은 payload는 계속 UnknownNotification으로 처리하면 된다.
이벤트별 데이터 구조가 분명해져 통합 코드의 분기와 검증을 타입에 맞춰 작성할 수 있다 (0.154.0~).

같은 버전에서 HookMetadata의 handler는 .root로 감싸진다.
handler별 필드를 읽기 전에 hook.root.handler_type을 확인하면 command가 아닌 handler를 같은 구조로 잘못 처리하지 않고 안전하게 마이그레이션할 수 있다 (0.154.0~).

활용

• 알려진 notification 처리 → 타입에 정의된 명명 필드를 직접 읽어 이벤트별 로직 분기
• 알 수 없거나 유효하지 않은 payload 처리 → UnknownNotification 분기로 보내 기존 fallback 유지
• command hook의 명령을 읽는 코드 마이그레이션:

  handler = hook.root
  if handler.handler_type == "command":
      command = handler.command

  복사

주의

기존 hook.command 접근은 hook.root.command로 바꿔야 한다.
.command를 읽기 전에 .root.handler_type이 command인지 확인한다.

Codex가 작업 중 보내는 질문에 TUI 안에서 바로 답할 수 있다.
제안된 선택지를 고르거나 직접 텍스트를 작성해도 메인 입력창의 초안은 그대로 남으므로, 진행 중인 요청을 다시 작성하지 않고 필요한 판단만 전달할 수 있다 (0.154.0~).

활용

• Codex가 구현 방향을 묻는 상황 → 인라인 질문에 표시된 선택지 중 하나를 골라 작업을 계속 진행
• 제안된 선택지에 원하는 답이 없는 상황 → 사용자 지정 텍스트를 직접 입력:

  기존 공개 API를 유지하면서 내부 구현만 바꿔줘

  복사
• 메인 입력창에 후속 요청을 작성하던 상황 → 초안을 지우지 않고 인라인 질문에 먼저 답한 뒤 계속 작성