OpenAI Codex 오픈소스 코드 기반 실전 활용 가이드 2026

지난 글에서 OpenAI Codex CLI의 소스코드 구조를 분석했다. 60개 Rust 크레이트, 에이전트 루프, 샌드박스 보안 모델까지 내부를 해부했다. 이번 글에서는 실전으로 넘어간다. 코드를 읽는 데서 그치지 않고, 실제 프로젝트에서 Codex CLI를 팀 도구로 세팅하고, 로컬 LLM을 연결하고, CI/CD에 통합하는 구체적인 방법을 다룬다.

AGENTS.md와 config.toml: 프로젝트별 설정의 계층 구조

Codex CLI의 설정은 두 축으로 나뉜다. AGENTS.md는 에이전트의 행동 지침을, config.toml은 실행 환경을 정의한다.

AGENTS.md는 계층적으로 로드된다. 글로벌 설정 파일인 ~/.codex/AGENTS.md가 먼저 읽히고, 프로젝트 루트의 .codex/AGENTS.md가 그 위에 병합된다. 하위 디렉토리에 별도의 AGENTS.md를 두면 해당 경로에서 작업할 때 추가로 적용된다. 최대 32KB까지 자동 병합되므로, 팀 전체의 코딩 표준을 글로벌에, 프로젝트 고유 규칙을 로컬에 분리할 수 있다.

# ~/.codex/AGENTS.md (글로벌)
모든 코드에 TypeScript strict 모드를 적용한다.
테스트 없는 PR은 거부한다.

# .codex/AGENTS.md (프로젝트)
이 프로젝트는 Next.js App Router를 사용한다.
API 라우트는 src/app/api/ 아래에 둔다.
데이터베이스 마이그레이션은 drizzle-kit을 사용한다.

config.toml은 실행 환경의 핵심이다. 샌드박스 모드(sandbox mode)는 에이전트가 파일 시스템에 접근할 수 있는 범위를 결정한다. read-only 모드는 파일 읽기만 허용하고, workspace-write 모드는 프로젝트 디렉토리 내에서만 쓰기를 허용한다.

# ~/.codex/config.toml
model = "o4-mini"
approval_policy = "untrusted"

[sandbox]
mode = "workspace-write"
writable_roots = ["/home/user/project"]

approval_policy는 세 단계로 나뉜다. on-request는 모든 도구 호출(tool call, 에이전트가 파일 수정이나 명령 실행 등을 요청하는 행위)마다 사용자 승인을 요구한다. untrusted는 안전한 작업은 자동 실행하되 위험한 작업만 승인을 요구한다. never는 모든 것을 자동 실행한다. 팀 환경에서는 untrusted를 기본값으로 두고, CI/CD에서는 never로 전환하는 패턴이 일반적이다.

MCP 서버와 플러그인: 에이전트 기능 확장

MCP(Model Context Protocol)는 Codex CLI에 외부 도구를 연결하는 표준 인터페이스다. MCP 서버는 STDIO(표준 입출력, 프로세스 간 데이터를 주고받는 방식)나 HTTP로 통신하며, codex mcp add 명령으로 등록한다.

# STDIO 기반 MCP 서버 추가
codex mcp add my-db-tool -- npx @my-org/db-mcp-server

# HTTP 기반 MCP 서버 추가
codex mcp add analytics-api --url https://mcp.example.com/v1

등록된 MCP 서버의 도구는 에이전트가 자동으로 인식한다. 도구 화이트리스트(whitelist)와 블랙리스트(blacklist)로 특정 도구만 허용하거나 차단할 수 있다. 예를 들어 데이터베이스 MCP 서버에서 SELECT 쿼리 도구만 허용하고 DROP 관련 도구는 차단하는 식이다.

플러그인 시스템은 MCP보다 한 단계 위의 추상화다. .codex-plugin/plugin.json 매니페스트 파일에 플러그인의 메타데이터, 의존성, 도구 정의를 선언한다. 플러그인 빌드 가이드에 따르면 팀 워크플로우 전체를 하나의 패키지로 묶어 배포할 수 있다.

{
  "name": "my-team-workflow",
  "version": "1.0.0",
  "tools": [
    {
      "name": "deploy-staging",
      "description": "스테이징 환경에 배포",
      "command": "bash scripts/deploy-staging.sh"
    },
    {
      "name": "run-e2e",
      "description": "E2E 테스트 실행",
      "command": "npx playwright test"
    }
  ]
}

코드 리뷰, 배포, 테스트를 하나의 플러그인으로 패키징하면 새로운 팀원이 codex plugin install만으로 전체 워크플로우를 즉시 사용할 수 있다.

로컬 LLM 통합: Ollama와 커뮤니티 포크

Codex CLI는 OpenAI API만 지원하는 것이 아니다. --oss 플래그를 사용하면 Ollama, LM Studio, MLX 같은 로컬 LLM 런타임에 연결할 수 있다. config.toml의 [model_providers.ollama] 섹션에서 엔드포인트와 모델을 지정한다.

[model_providers.ollama]
base_url = "http://localhost:11434/v1"
model = "deepseek-coder-v2:33b"

# Ollama로 Codex 실행
codex --oss --model deepseek-coder-v2:33b "이 함수를 리팩토링해줘"

로컬 LLM의 장점은 분명하다. API 비용이 없고, 코드가 외부 서버로 전송되지 않으며, 네트워크 지연이 없다. 반면 성능은 모델 크기와 하드웨어에 크게 의존한다. 33B 파라미터 모델은 M4 Max MacBook에서 초당 약 30토큰을 생성하는데, OpenAI의 o4-mini가 초당 100토큰 이상을 스트리밍하는 것과 비교하면 속도 차이가 크다.

커뮤니티 포크(fork)들은 이 로컬 LLM 통합을 더 밀어붙이고 있다. GitHub에서 codex 포크를 검색하면 Ollama 전용 최적화, 커스텀 모델 프로바이더, 자체 프롬프트 체인을 구현한 변형들을 찾을 수 있다. Apache 2.0 라이선스가 이런 실험을 가능하게 한다.

CI/CD 자동화: GitHub Action과 비상호식 실행

Codex CLI의 가장 실용적인 확장은 CI/CD 통합이다. openai/codex-action@v1 GitHub Action을 사용하면 PR이 올라올 때마다 Codex가 자동으로 코드를 리뷰하거나 테스트를 생성한다.

# .github/workflows/codex-review.yml
name: Codex PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            이 PR의 변경사항을 리뷰해줘.
            보안 취약점, 성능 문제, 코딩 컨벤션 위반을 체크해.
          approval_policy: "never"

codex exec 명령은 비상호식(non-interactive) 실행 모드다. 터미널 UI 없이 명령을 실행하고 결과를 stdout으로 출력한다. CI 환경에서 스크립트처럼 사용할 수 있다.

# 비상호식 실행
codex exec "src/utils.ts의 모든 함수에 JSDoc 주석을 추가해"

# JSON 출력 모드
codex exec --output json "이 프로젝트의 보안 취약점을 분석해"

PR 리뷰 자동화의 핵심은 AGENTS.md와의 결합이다. 프로젝트의 AGENTS.md에 코딩 규칙을 정의해두면, CI에서 실행되는 Codex도 같은 규칙을 따른다. 코드 스타일, 아키텍처 패턴, 금지 사항이 사람 리뷰어와 AI 리뷰어 사이에서 일관되게 적용된다.

Plan 모드와 에이전트 루프 코드 경로

Plan 모드는 복잡한 작업을 사전에 계획한 뒤 구현하는 2단계 접근이다. codex plan을 실행하면 에이전트가 파일 시스템을 분석하고 실행 계획을 텍스트로 출력한다. 사용자가 계획을 승인하면 그때 실행이 시작된다.

에이전트 루프의 핵심 코드는 codex-rs/core/ 디렉토리에 있다. 이 디렉토리를 읽으면 에이전트가 어떻게 사용자 입력을 받고, API에 요청을 보내고, 도구를 실행하고, 결과를 반환하는지 전체 흐름을 추적할 수 있다. codex-rs/core/src/agent_loop.rs가 루프의 진입점이고, tool_spec.rs가 도구 정의, sandbox.rs가 보안 경계를 담당한다.

codex-rs/core/
├── src/
│   ├── agent_loop.rs    # 에이전트 루프 진입점
│   ├── tool_spec.rs     # 도구 정의 및 JSON Schema
│   ├── sandbox.rs       # 샌드박스 보안 경계
│   ├── config.rs        # config.toml 파싱
│   └── mcp_client.rs    # MCP 프로토콜 클라이언트

코드를 직접 읽으면 문서에서 설명하지 않는 디테일이 보인다. 예를 들어 agent_loop.rs의 재시도 로직, sandbox.rs의 macOS/Linux별 분기 처리, mcp_client.rs의 타임아웃 설정 같은 것들이다.

시사점: 오픈소스 코딩 에이전트의 확장 전략

Codex CLI의 오픈소스 공개는 단순한 코드 공유가 아니다. 확장 가능한 플랫폼으로의 전환이다.

AGENTS.md의 계층적 설정은 조직 전체에 일관된 AI 코딩 표준을 배포하는 메커니즘이다. 글로벌 설정에 보안 정책을 넣고, 프로젝트별 설정에 아키텍처 규칙을 넣으면, 모든 팀원의 Codex가 같은 기준으로 동작한다.

MCP와 플러그인은 도구 생태계의 확장을 가능하게 한다. 내부 API, 데이터베이스, 모니터링 시스템을 MCP 서버로 감싸면 에이전트가 코드 작성 이상의 작업을 수행할 수 있다.

로컬 LLM 통합은 비용과 프라이버시 문제를 해결한다. 민감한 코드베이스를 다루는 팀은 Ollama로 로컬에서만 실행할 수 있다.

CI/CD 통합은 에이전트를 개발자 워크스테이션에서 파이프라인으로 이동시킨다. 코드 리뷰, 문서 생성, 테스트 작성이 자동화된다.

이 모든 확장 포인트가 Apache 2.0 라이선스 아래 열려 있다는 것이 핵심이다. 경쟁 제품인 Claude Code는 강력하지만 소스가 비공개다. Codex CLI는 성능에서는 아직 따라가는 중이지만, 커스터마이징과 확장에서는 구조적 우위를 가진다.

참고 자료

AI 코딩 에이전트와 오픈소스 트렌드를 매일 분석한다. spoonai.me 뉴스레터를 구독하면 매일 아침 핵심만 정리해서 보내준다.