프로그래밍 자동화

32.1codex exec 기본

공식비대화 모드는 대화형 TUI를 열지 않고 스크립트에서 코덱스를 돌립니다. 명령은 codex exec(짧게 codex e)입니다. non-interactive-mode

공식쓰는 경우가 넷으로 정리됩니다. 파이프라인의 일부로 돌 때(CI, 병합 전 검사, 예약 작업), 다른 도구로 넘길 출력을 만들 때, 명령 출력을 코덱스에 넣고 코덱스 출력을 다시 다른 도구로 넘기는 CLI 흐름에 맞출 때, 샌드박스와 승인 설정을 명시적으로 미리 정해 두고 돌릴 때. non-interactive-mode

기본 사용

codex exec "summarize the repository structure and list the top 5 risky areas"

공식도는 동안 진행 상황은 stderr로 흐르고 stdout에는 마지막 에이전트 메시지만 찍힙니다. 그래서 리다이렉트와 파이프가 그대로 됩니다. non-interactive-mode

출력 파이프

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

공식표준 입력이 파이프로 들어오면서 프롬프트 인자도 주면, 코덱스는 프롬프트를 지시로 보고 파이프 내용을 추가 맥락으로 씁니다. non-interactive-mode

한 명령의 출력을 그대로 넘기기

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md

공식세션 롤아웃 파일을 디스크에 남기고 싶지 않으면 --ephemeral을 씁니다. non-interactive-mode

codex exec --ephemeral "triage this repository and suggest next steps"

32.2출력 다루기

공식스크립트에서 소비하려면 JSON Lines 출력을 씁니다. --json을 켜면 stdout이 JSONL 스트림이 되어 도는 동안의 모든 이벤트를 잡을 수 있습니다. 이벤트 타입은 thread.started, turn.started, turn.completed, turn.failed, item.*, error입니다. 항목 타입에는 에이전트 메시지, 추론, 명령 실행, 파일 변경, MCP 도구 호출, 웹 검색, 계획 갱신이 있습니다. non-interactive-mode

JSONL 스트림 예 (각 줄이 JSON 객체)

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

공식마지막 메시지만 필요하면 -o(--output-last-message)로 파일에 씁니다. 파일에 쓰면서 stdout에도 그대로 찍힙니다. non-interactive-mode

공식후속 단계가 안정된 필드를 필요로 하면 --output-schema로 JSON 스키마에 맞는 최종 응답을 요청합니다. 작업 요약, 위험 리포트, 릴리스 메타데이터처럼 자동화된 흐름에 유용합니다. non-interactive-mode

schema.json

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

공식CI에서는 --json과 --output-last-message를 함께 쓰라고 공식 문서가 권합니다. 기계 판독 가능한 진행과 마지막 자연어 요약을 둘 다 잡기 위해서입니다. developer-commands

32.3권한과 안전

공식codex exec는 기본이 읽기 전용 샌드박스입니다. 자동화에서는 워크플로에 필요한 최소 권한만 줍니다. non-interactive-mode

공식인증은 두 갈래입니다. 일반 자동화에는 API 키가 권장 기본값이고, ChatGPT 워크스페이스 접근·엔터프라이즈 통제가 필요한 신뢰된 로컬 워크플로에는 코덱스 액세스 토큰을 씁니다. 액세스 토큰은 Business·Enterprise 워크스페이스에서 지원됩니다. auth enterprise/access-tokens

토큰을 표준 입력으로 넘기기

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

공식액세스 토큰의 위험도 문서에 명시돼 있습니다. 토큰을 가진 사람은 누구나 토큰 생성자의 자격으로 로컬 실행을 시작할 수 있습니다. 시크릿 매니저에 보관하고, 로그에 남기지 않고, 주기적으로 회전합니다. 공개 CI·포크 PR·공유 기기처럼 워크스페이스 밖 사람에게 노출될 수 있는 곳에서는 쓰지 않습니다. enterprise/access-tokens

32.4실패 판정과 재시도

공식codex login status는 자격증명이 있으면 0으로 끝납니다. 자동화 스크립트에서 선행 검사로 쓰기 좋습니다. developer-commands

공식필수 MCP 서버가 있는 경우도 실패 신호가 됩니다. required = true로 활성화한 MCP 서버가 초기화에 실패하면 codex exec는 그 서버 없이 계속하지 않고 오류로 끝납니다. non-interactive-mode

공식비대화 실행을 이어가려면 resume 서브커맨드를 씁니다. --last는 현재 작업 디렉터리의 가장 최근 세션을, --all은 모든 세션을 대상으로 찾습니다. developer-commands

관행비대화 실행에서 가장 자주 겪는 실패는 모델 문제가 아니라 권한 문제입니다. 로컬에서 되던 스크립트가 CI에서 멈추면 순서대로 봅니다. 인증(codex login status) → 샌드박스(--sandbox가 편집을 허용하는가) → 승인(-a never인가) → 설정 계층(--ignore-user-config가 필요한가).

33.1Codex SDK

공식SDK는 코덱스를 프로그램에서 제어합니다. 쓰는 경우가 넷으로 제시됩니다. CI/CD 파이프라인의 일부로 통제할 때, 코덱스와 상호작용하며 복잡한 엔지니어링 작업을 수행하는 자기 에이전트를 만들 때, 사내 도구·워크플로에 코덱스를 넣을 때, 자기 애플리케이션에 통합할 때. codex-sdk

공식TypeScript 라이브러리는 애플리케이션이 로컬 코덱스 스레드를 시작·계속·재개하게 합니다. 서버 사이드에서 쓰고 Node.js 18 이상이 필요합니다. codex-sdk

TypeScript

npm install @openai/codex-sdk

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);
console.log(result.finalResponse);

// 같은 스레드를 이어서
const next = await thread.run("Implement the plan");

// 과거 스레드를 재개
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

공식Python SDK는 JSON-RPC로 로컬 앱 서버를 제어합니다. Python 3.10 이상이 필요하고, 배포된 SDK 빌드에는 고정된 코덱스 CLI 런타임 의존성이 포함됩니다. 베타 기간 동안 pip install openai-codex는 최신 베타 빌드를 고릅니다. codex-sdk

Python

pip install openai-codex

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.6-terra",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

공식애플리케이션이 이미 비동기라면 AsyncCodex를 씁니다. codex-sdk

33.2App Server

공식앱 서버는 코덱스가 리치 클라이언트(예: VS Code 확장)를 구동하는 데 쓰는 인터페이스입니다. 자기 제품 안에 깊은 통합이 필요할 때 씁니다. 인증, 대화 이력, 승인, 스트리밍 에이전트 이벤트를 다룹니다. 구현은 코덱스 저장소에 오픈소스로 있습니다. app-server

공식원격 터미널 UI 모드도 있습니다. 한 기계에서 앱 서버를 돌리고 다른 기계에서 CLI 터미널 인터페이스를 붙입니다. app-server

웹소켓 리스너를 열고 터미널 UI를 붙입니다

# 호스트에서
codex app-server --listen ws://127.0.0.1:4500

# 클라이언트에서
codex --remote ws://127.0.0.1:4500

비로컬 연결은 TLS와 베어러 토큰으로

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

33.3MCP 서버로서의 코덱스

공식코덱스를 MCP 서버로 돌려 다른 MCP 클라이언트가 붙게 할 수 있습니다. 예를 들어 OpenAI Agents SDK로 만든 에이전트에서 코덱스를 하나의 전문가로 부르는 구성입니다. mcp-server

터미널

codex mcp-server

# MCP Inspector 로 붙여 보기
npx @modelcontextprotocol/inspector codex mcp-server

공식tools/list를 보내면 도구 둘이 나옵니다. mcp-server

공식threadId는 tools/call 응답의 structuredContent.threadId에서 가져옵니다. 승인 프롬프트(exec·patch)의 params 페이로드에도 threadId가 들어갑니다. mcp-server

33.4셋 중 무엇을

근거는 각 문서의 안내 문장입니다. codex-sdk app-server mcp-server

34.1GitHub Action

공식openai/codex-action@v1은 CI/CD 잡에서 코덱스를 돌리고, 패치를 적용하고, 리뷰를 게시합니다. 액션이 CLI를 설치하고, API 키를 주면 Responses API 프록시를 띄우고, 지정한 권한 아래에서 codex exec를 돌립니다. github-action

공식선행 조건이 넷입니다. OpenAI 키를 GitHub 시크릿으로 저장하고 워크플로에서 참조하기, Linux나 macOS 러너에서 돌리기(윈도우는 safety-strategy: unsafe 설정), 액션 호출 전에 코드를 체크아웃하기, 어떤 프롬프트를 돌릴지 정하기(prompt 인라인 또는 prompt-file). github-action

name: Codex pull request review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}

공식주요 입력은 여덟입니다. github-action

34.2액세스 토큰

공식코덱스 액세스 토큰은 코덱스 권한으로 범위가 정해진 ChatGPT 워크스페이스 자격증명입니다. 브라우저 로그인 없이 CLI나 앱 서버 클라이언트가 돌아야 할 때 씁니다. 토큰은 만든 사용자와 그 워크스페이스에 묶이고, 실행이 그 워크스페이스 신원으로 기록되어 거버넌스 데이터에 나타납니다. enterprise/access-tokens

공식플랫폼 API 키로 되는 자동화라면 API 키를 계속 씁니다. 액세스 토큰은 ChatGPT 워크스페이스 접근·워크스페이스 관리 자격·엔터프라이즈 통제가 구체적으로 필요할 때 씁니다. enterprise/access-tokens

공식토큰 생성 권한은 워크스페이스 설정의 액세스 토큰 권한으로 켭니다. 이 권한은 토큰 생성만 통제하고, 데스크톱 앱·CLI·IDE 확장 접근을 주거나 좌석 유형·워크스페이스 역할·로컬 런타임 권한 프로파일을 바꾸지 않습니다. enterprise/access-tokens

34.3PR 자동 리뷰 배선

공식PR 리뷰를 거는 방법이 둘 있고 성격이 다릅니다. 하나는 코덱스 설정에서 Automatic reviews를 켜는 것이고(클라우드 경로, 저장소 연결 필요), 다른 하나는 GitHub Action으로 워크플로에서 돌리는 것입니다(CI 경로, API 키 필요). third-party/github github-action

공식사용량 회계 구분의 근거는 요금 문서입니다. Code Review 사용량은 GitHub를 통해 도는 리뷰에만 적용되고, 로컬이나 GitHub 밖에서 도는 리뷰는 일반 사용량에 잡힙니다. pricing

공식보안 리뷰(연구 프리뷰)는 GitHub PR 대상의 더 깊은 검토이고 별도로 구성합니다. 상세는 35.11에 있습니다. security/security-review

35.1무엇인가

공식진입 경로가 넷입니다. 코덱스 안(플러그인), 터미널(CLI), TypeScript SDK, 연결된 GitHub 저장소(클라우드). 데스크톱 워크벤치와 CLI는 코덱스 시큐리티 플러그인을 쓰고, 클라우드 스캔은 코덱스 클라우드를 통해 연결된 GitHub 저장소를 스캔합니다. security

35.2플러그인으로 시작하기

공식가장 규범적인 첫 로컬 스캔 경로는 플러그인 퀵스타트입니다. 데스크톱 앱에서는 Plugins에서 Codex Security를 찾아 설치하고 켠 뒤 사이드바의 Security를 엽니다. CLI에서는 평가할 저장소로 이동해 codex를 띄우고 /plugins에서 설치한 뒤 /new로 새 채팅을 시작합니다. security/plugin

공식스캔 품질을 위해 공식 문서가 권하는 조합은 gpt-5.6-sol + xhigh 추론 강도입니다. security/plugin

35.3스캔 돌리기

공식워크벤치의 스캔 설정은 세 단계입니다. 코드베이스와 스캔 범위를 고르고(저장소 전체 또는 폴더 하나, 브랜치와 리비전이 의도한 코드인지 확인), 모델과 추론 강도를 고르고, 필요할 때만 Additional context를 열어 특정 공격 벡터·보안 민감 영역·저장소 세부를 적습니다. security/plugin security/plugin/scans

공식더 넓게 검토하고 시간을 더 쓸 수 있으면 딥 스캔을 씁니다. 저장소나 범위를 좁힌 폴더에 대해 더 느리고 더 철저한 검토를 돌립니다. security/plugin/deep-scans

35.4결과 다루기

관행이 세 갈래의 순서가 결과를 가릅니다. 스캔 직후 고치기부터 시작하면 중요도가 낮은 항목에 시간이 갑니다. 백로그 트리아지로 순서를 먼저 정하고, 상위 항목만 고치고, 나머지는 내보내 추적하는 편이 남는 것이 많습니다.

35.5변경 리뷰와 하드닝

비대화로 변경 스캔 (공식 예)

codex exec --sandbox workspace-write 'Use $codex-security:security-diff-scan to review changes from <base-revision> to <head-revision> for security regressions. Do not modify the checkout.'

이 예는 스캔이 체크아웃을 고치지 않게 하면서도 workspace-write가 필요한 이유를 보여 줍니다. 스캔 자체가 작업 디렉터리에 산출물을 써야 합니다. plugin/code-changes

35.6워크벤치

공식플러그인을 설치하고 켜면 데스크톱 앱 사이드바에 Security가 열립니다. 워크벤치는 스캔·발견 항목·저장소를 한곳에 모으고, 코덱스가 각 스캔을 작업으로 돌립니다. Scans에서 시작·진행·저장된 결과를 보고, Findings에서 완료된 스캔의 이슈와 근거를 보고, Repositories에서 저장소 이력과 열린 발견 항목을 봅니다. security security/plugin/workbench

35.7CLI

공식CLI와 TypeScript SDK는 공개 패키지 @openai/codex-security로 배포됩니다. 패키지는 공개지만 스캔 실행에는 접근 권한이 필요합니다. security security/cli

공식선행 조건은 Node.js 22.13.0 이상이고, 스캔이나 내보내기에는 Python 3.10 이상도 필요합니다. security/cli

실행 확인과 로그인

# 설치 없이 npx 로 바로 실행합니다(공식 문서가 2026-08-11 이 방식으로 바뀌었습니다)
npx @openai/codex-security --version
npx @openai/codex-security --help

# 로컬: ChatGPT 계정으로
npx @openai/codex-security login

# 원격·헤드리스: 기기 인증
npx @openai/codex-security login --device-auth

# CI·자동화: API 키
export OPENAI_API_KEY="..."

공식API 키가 설정된 상태에서 ChatGPT 로그인을 쓰려면 명시적으로 고릅니다. 반대로 환경의 API 키를 강제하려면 --auth api-key입니다. security/cli

npx @openai/codex-security scan . --auth chatgpt
npx @openai/codex-security scan . --auth api-key

공식인자·출력 형식·스캔 산출물·종료 코드 전량은 CLI 레퍼런스가 정본입니다. Amazon Bedrock·OpenRouter·Fireworks를 쓰는 구성도 그 문서에 있습니다. security/cli/reference

35.8CI와 대량 스캔

공식CI에서는 PR·MR의 변경만 검토하고, 발견 항목과 커버리지를 보존하고, 선택적으로 지정한 심각도에서 검사를 실패시킬 수 있습니다. 공식 권장 순서는 먼저 권고(advisory)로 시작해 스캔 품질과 실행 시간을 검토한 뒤 저장소에 맞는 심각도 정책을 붙이는 것입니다. security/cli/ci

공식러너 요구사항이 넷입니다. Node.js 22.13.0 이상, Python 3.10 이상, 저장소 체크아웃 바깥에 설치한 @openai/codex-security 패키지, 그리고 git이 병합 기점을 계산할 수 있도록 PR·MR의 head와 base 히스토리. security/cli/ci

공식자격증명은 CI 시크릿 저장소에 CODEX_SECURITY_API_KEY로 두고 스캔 단계의 OPENAI_API_KEY 환경 변수로 직접 매핑합니다. 자격증명을 스캔 프로세스로 좁히고 --auth api-key로 명시적으로 고릅니다. security/cli/ci

공식여러 저장소를 훑어야 하면 대량 스캔을 씁니다. GitHub 저장소를 발견하거나 CSV 인벤토리에서 재개 가능한 스캔 캠페인을 돌립니다. security/cli/bulk-scans

35.9TypeScript SDK

공식SDK는 애플리케이션이나 개발자 도구에서 저장소·변경 스캔을 돌립니다. 타입이 붙은 발견 항목, 커버리지 상세, 스캔 산출물 경로를 돌려줍니다. 오래 걸리는 스캔을 위해 사전 점검(preflight), 비용 상한, 진행 콜백, 취소를 지원합니다. ESM이고 Node.js 22.13.0 이상 서버 사이드에서 돕니다(스캔에는 Python 3.10 이상도 필요). security/sdk

설치

npm install @openai/codex-security

공식스캔 전에 OPENAI_API_KEY나 CODEX_API_KEY를 설정하거나, 기존 파일 기반 코덱스 로그인을 쓰거나, 다른 제공자를 구성합니다. outputDir를 넘겨 결과 디렉터리를 git 워크트리 밖 비공개 위치로 고릅니다. security/sdk

공식일반 코딩 에이전트에는 Codex SDK, 터미널·CI 워크플로에는 코덱스 시큐리티 CLI를 쓰라고 문서가 구분해 안내합니다. security/sdk

35.10클라우드와 위협 모델

공식클라우드 스캔은 코덱스 클라우드로 연결된 GitHub 저장소를 대상으로 합니다. 선행 조건은 코덱스 클라우드 설정과 그 저장소의 환경입니다. 환경이 없으면 먼저 만듭니다. security/setup

공식스캔 순서에 특징이 있습니다. 코덱스 시큐리티는 저장소를 최신 커밋에서 거꾸로 스캔하고, 이것으로 새 커밋이 들어올 때 스캔 맥락을 만들고 갱신합니다. security/setup

공식쓸모 있는 위협 모델이 담는 것은 넷입니다. 진입점과 신뢰할 수 없는 입력, 신뢰 경계와 인증 가정, 민감 데이터 경로나 특권 동작, 팀이 먼저 검토받고 싶은 영역. 발견 항목이 원하는 영역을 놓치거나 예상하지 않은 곳에서 나올 때 이것부터 고칩니다. security/threat-model

35.11보안 리뷰

공식보안 리뷰는 GitHub PR을 대상으로 하는 심층 보안 검토이고 연구 프리뷰입니다. 일반 코드 리뷰(@codex review)와 별개로 구성합니다. security/security-review third-party/github

공식둘을 같은 것으로 취급하지 않습니다. 공식 문서가 보안 리뷰를 "PR의 잠재적 보안 문제에 대한 더 깊은 검토"로 따로 정의하고, 일반 리뷰는 GitHub에서 P0·P1 문제만 표시합니다. 보안이 중요한 변경(인증, 입력 처리, 권한, 외부 통신)에는 보안 리뷰를 별도로 겁니다. third-party/github security/security-review

35.12자주 묻는 것

공식FAQ가 세 문서로 갈려 있습니다. CLI 쪽은 스캔 이력·오탐 피드백·커버리지·수정 검증을 다루고, 클라우드 쪽은 클라우드 스캔 일반을 다루고, 플러그인 변경 이력은 사용자에게 보이는 변경을 기록합니다. security/cli/faq security/faq security/plugin/changelog

공식CLI가 플러그인과 같은 스캐너를 저장소와 시간을 가로질러 쓴다는 점이 이 제품군의 설계입니다. CLI는 GitHub 저장소를 발견하고, 대량 스캔을 재개하고, 스캔 간 발견 항목을 추적하고, 오탐 피드백을 기록합니다. 아키텍처와 보안 정책을 더하거나 예상 비용 상한을 걸거나 CI·커밋 전 검사를 돌릴 수 있습니다. security