Codex 실전 가이드 5편입니다. 1편부터 4편까지는 Codex 한 세션 안의 이야기였습니다. 지침(AGENTS.md), 경계(샌드박스·승인), 설정과 컨텍스트, 스킬·서브에이전트·훅을 다뤘습니다. 이번 편은 Codex 를 바깥과 잇습니다. 외부 도구는 MCP 와 플러그인으로 붙이고, 사람이 없는 실행은 codex exec 로 합니다. 다른 에이전트가 Codex 를 부르는 경우까지 봅니다.
이번 편이 답하는 질문은 이것입니다. Codex 를 바깥 도구와 다른 에이전트에 이을 때 경계는 어디에 다시 그어야 하나. 답은 “부르는 쪽"입니다. codex exec 는 기본이 읽기 전용이라 안전한 쪽에서 시작합니다. 위험은 다른 프로그램이 Codex 를 부를 때 생깁니다. 이 경로는 샌드박스와 승인을 끈 채 부르기 쉽습니다. 그래서 바인딩 주소·토큰·안전 모드 같은 경계를 부르는 쪽에서 다시 세워야 합니다.
MCP 서버는 config.toml 의 표 하나입니다
MCP 서버 등록은 codex mcp add 가 맡습니다. 0.169.0 도움말로 확인한 형식입니다.
codex mcp add my-db --env LOG_LEVEL=info -- my-db-mcp-server # stdio 서버
codex mcp add my-api --url https://mcp.example.com/mcp \
--bearer-token-env-var MY_API_TOKEN # streamable HTTP 서버
codex mcp list
--env 는 stdio 서버에만, --bearer-token-env-var 는 HTTP 서버에만 씁니다. 후자는 토큰 값이 아니라 토큰을 담은 환경변수 이름을 받습니다. OAuth 를 쓰는 서버는 codex mcp login <이름> 으로 로그인합니다. 등록 결과는 config.toml 의 [mcp_servers.<이름>] 표로 남습니다. 공식 문서 기준으로 시작 제한 시간 startup_timeout_sec 는 기본 10초, 도구 호출 제한 시간 tool_timeout_sec 는 기본 60초입니다. 도구 일부만 열려면 enabled_tools, 막으려면 disabled_tools 를 씁니다. 세션 안에서는 /mcp 로 켜진 서버를 봅니다.
제 맥에는 MCP 서버가 8개 등록돼 있습니다(2026-11-18). 서버가 늘수록 도구 정의도 늘어납니다. prompt-input 의 도구 안내에는 지연 로드되는 도구 묶음이 이름과 한 줄 설명으로만 들어 있었습니다. 등록한 8개가 모두 그렇게 처리되는지는 확인하지 못했습니다. 어느 쪽이든 3편에서 잰 도구 정의 32,266자는 매 세션의 고정 비용입니다.
보안 쪽에서 볼 줄도 있습니다. codex exec --help 는 --trust 를 “MCP commands outside the sandbox” 까지 포함하는 신뢰라고 설명합니다. 해석은 이렇습니다. 신뢰한 프로젝트가 띄우는 MCP 서버 명령은 2편의 샌드박스 밖에서 돕니다. 남의 저장소를 신뢰하기 전에 그 저장소의 .codex/config.toml 에 MCP 서버가 있는지 먼저 봅니다.
플러그인은 스킬·MCP·훅을 한 묶음으로 싣습니다
플러그인은 codex plugin add·list·marketplace·remove 로 관리합니다. 세션 안에서는 /plugins 가 플러그인 목록을 엽니다(공식 문서 기준). 공식 문서는 플러그인에 스킬, MCP 서버, 앱, 훅을 실을 수 있다고 설명합니다. 문서 페이지마다 나열한 항목이 조금씩 달라서, 이 목록은 문서 기준으로만 받아들였습니다.
실제로 만들어 보면서 확인한 것은 세 가지입니다(0.164.0~0.166.0, 소스 대조와 실측).
- 매니페스트는
.codex-plugin/plugin.json이 기본이지만.claude-plugin/plugin.json도 읽습니다. 마켓플레이스도.claude-plugin/marketplace.json을 읽습니다. Claude Code 용 플러그인 저장소 하나를 두 도구가 같이 쓸 수 있습니다. - 설치하면
CODEX_HOME/plugins/cache/아래로 복사하는데, 이때 심링크를 버립니다. 심링크만 있던 스킬 폴더는 빈 폴더가 됐습니다. 플러그인 원본은 실제 파일이어야 합니다. - 서브에이전트는 플러그인에 실을 수 없습니다. 서브에이전트는 4편의 TOML 파일로 따로 깔아야 합니다.
플러그인 안의 훅은 설치만으로 신뢰받지 않습니다. 공식 문서는 사용자가 따로 검토하고 신뢰해야 한다고 적습니다. 4편의 두 겹 신뢰가 플러그인에도 그대로 적용됩니다.
codex exec 는 읽기 전용에서 시작합니다
사람 없이 한 번 돌리고 끝나는 작업은 codex exec 로 합니다. 공식 문서 기준으로 기본 샌드박스는 읽기 전용이고, 편집을 맡기려면 --sandbox workspace-write 를 줍니다.
codex exec --sandbox workspace-write --json -o last.txt \
"실패하는 테스트 하나를 찾아 고쳐줘" </dev/null > events.jsonl
옵션은 0.169.0 도움말로 확인했습니다. --json 은 진행 이벤트를 JSONL 로 내보냅니다. -o 는 마지막 메시지만 파일로 씁니다. --output-schema 는 최종 응답의 JSON 형태를 스키마로 고정합니다. --ephemeral 은 세션 파일을 남기지 않습니다. git 저장소 밖에서 돌리려면 --skip-git-repo-check 가 필요합니다. 이어서 시킬 일이 있으면 codex exec resume --last 를 씁니다. 리뷰만 필요하면 codex review --uncommitted·--base <브랜치>·--commit <SHA> 가 따로 있습니다.
명령 끝의 </dev/null 은 일부러 붙였습니다. 0.160.0 에서 stdin 이 열린 채로 codex exec 를 부르자 실행이 멈췄습니다. 마지막 출력은 “Reading additional input from stdin…” 이었습니다. 도움말도 stdin 이 파이프로 들어오면 프롬프트 뒤에 <stdin> 블록으로 붙인다고 적습니다. 스크립트에서 부를 때는 stdin 을 명시적으로 닫습니다. CI 에서는 CODEX_API_KEY 를 그 호출 하나에만 주라고 공식 문서는 안내합니다.
무인 실행 결과를 판정할 때 지키는 규칙도 하나 있습니다. 응답이 없는 것과 “없다"고 답한 것은 다른 사실입니다. 4편에서 말한 검사 스크립트는 codex exec 한 번에 600초 제한을 두었습니다. 시간 안에 답이 없으면 실패가 아니라 “판정 불가"로 따로 셉니다. 타임아웃을 실패로 세면 Codex 의 동작이 아니라 네트워크 상태를 재게 됩니다.
다른 에이전트가 Codex 를 부를 때는 경계를 다시 긋습니다
제 맥에는 A2A(Agent2Agent) 브리지라는 로컬 서버가 있습니다. 에이전트 CLI 여섯 개를 A2A 에이전트로 노출합니다. Claude Code 세션이 셸에서 node a2a.mjs send codex "<글>" 을 실행하면 그 글이 Codex 에게 갑니다. 브리지는 에이전트를 ACP(Agent Client Protocol)로 붙입니다. 에디터가 에이전트를 stdio 로 부리는 규격입니다. Codex 는 ACP 를 자체 지원하지 않아 어댑터 패키지 @agentclientprotocol/codex-acp 2.6.0 을 거칩니다. 처음에는 작업마다 codex exec 를 띄웠습니다. CLI 마다 출력 해석 코드가 필요했고 대화를 잇지 못하는 CLI 도 있어서 ACP 로 바꿨습니다.
경계는 여기서 다시 그어야 했습니다. 에이전트끼리 일을 맡기려면 파일 쓰기와 명령 실행이 돼야 합니다. 그래서 브리지는 Codex 를 agent-full-access 모드, 곧 샌드박스와 승인이 없는 상태로 띄웁니다. 2편의 두 겹 경계가 이 경로에서는 꺼집니다. 남은 경계는 셋입니다. 서버는 127.0.0.1 에만 바인딩합니다. 상태 확인 주소를 뺀 모든 요청에 Bearer 토큰을 요구합니다. 토큰은 권한 0600 파일에 둡니다. 그리고 필요할 때 안전 모드로 띄웁니다.
안전 모드(A2A_SAFE=1)에서 여섯 에이전트에게 작업 폴더에 파일을 만들라고 시켜 보았습니다(2026-11-16).
| 에이전트 | 권한을 물었나 | 파일이 생겼나 |
|---|---|---|
| Codex | 물었다 | 안 생겼다 |
| Antigravity | 물었다 | 안 생겼다 |
| Claude Code | 안 물었다 | 생겼다 |
| 나머지 셋 | 셋 중 둘은 안 물었다 | 셋 다 생겼다 |
Codex 는 권한 요청이 거절되자 작업을 실패로 끝냈습니다. 샌드박스를 켜 두면 Codex 는 “부르는 쪽이 허락하지 않은 일"을 하지 못합니다. 다만 이 결과는 각 에이전트가 ACP 어댑터로 붙은 이 구성에서 잰 값입니다. 에이전트를 직접 실행할 때의 기본 동작과는 다를 수 있습니다.
무인 작업의 흔적 — Codex 계정으로 남은 커밋
저는 사람이 하지 않은 작업을 에이전트별 계정으로 커밋하게 합니다. 커밋 제목 앞에는 [GPT-6] 처럼 모델 이름을 붙입니다. 이 규칙 덕분에 Codex 가 무인으로 한 일을 이력에서 따로 볼 수 있습니다. 두 건을 소개합니다.
첫째는 세 에이전트 공통 Stop 훅입니다. 머지와 배포 확인이 끝나기 전에는 턴을 끝내지 못하게 막는 훅입니다. Codex 가 2026-10-04 에 13개 파일, 914줄을 더해 테스트와 함께 올렸습니다. 4편의 decision: block 이 여기에 쓰였습니다. 그 설치 문서에는 Codex 의 새 훅을 /hooks 에서 신뢰하라는 규칙이 있습니다. 신뢰 해시를 직접 써넣는 우회는 금지했습니다.
둘째는 되돌린 작업입니다. 2026-11-13 에 Codex 가 한국어 글 검사기를 Rust 로 옮겼습니다. 같은 날 다른 에이전트가 그 검사기를 Go 로 다시 옮겼습니다. 검사기는 사용자 맥에서 처음 실행할 때 빌드되는데, Rust 릴리스 빌드의 CPU 부하가 컸기 때문입니다. “동봉 도구는 Go 표준 라이브러리로” 라는 규칙은 그 뒤에 지침에 들어갔습니다. Codex 는 적혀 있지 않은 제약을 알 수 없었습니다. 작업이 이슈 단위로 나뉘어 있었으니, 다시 옮기는 일도 이슈 하나로 끝났습니다.
Claude Code 와 다른 점
| 항목 | Claude Code | Codex 0.169.0 |
|---|---|---|
| 무인 실행 | claude -p | codex exec, 기본 읽기 전용 |
| 플러그인 매니페스트 | .claude-plugin/plugin.json | .codex-plugin/plugin.json, .claude-plugin 도 읽음 |
| 플러그인에 서브에이전트 | 실을 수 있음 | 실을 수 없음 |
| ACP 지원 | 어댑터 필요 | 어댑터 필요 |
Claude Code 가이드 5편은 “되돌릴 수 있는가"를 자율 실행의 경계로 삼았습니다. Codex 에서도 기준은 같습니다. 차이는 그 기준을 지키는 장치가 Codex 안에 하나 더 있다는 점입니다. 샌드박스입니다. 다만 그 장치는 부르는 쪽이 끄면 사라집니다.
정리 — 다섯 편을 묶는 한 가지
다섯 편에서 반복한 말은 하나입니다. Codex 에서는 파일을 만든 것과 기능이 켜진 것이 다릅니다. 전역 지침은 이름이 틀려 빠졌습니다(1편). 샌드박스 기본값은 신뢰에 따라 달랐습니다(2편). 옛 프로필 표는 조용히 무시됐습니다(3편). 심링크한 스킬은 목록에서 빠졌고, 훅은 신뢰받기 전까지 돌지 않았습니다(4편). 그리고 샌드박스는 부르는 쪽이 끄면 꺼졌습니다(이번 편).
다음에 확인할 것은 하나입니다. Codex 를 부르는 스크립트나 다른 에이전트가 있는지 찾습니다. 있다면 그 호출이 어떤 샌드박스와 승인 정책으로 Codex 를 띄우는지 확인합니다. 6편에서는 연재에서 다룬 설정을 0.170.0 기준 config.toml 매뉴얼로 묶습니다.