Codex 하네스는 모델에 프롬프트만 보내는 래퍼가 아니라, 컨텍스트 유지·도구 호출·실행 정책·승인 요청·진행 이벤트를 관리하는 실행 루프다. 기존 대시보드나 업무 도구 안에 에이전트를 넣고 싶은 팀은 채팅 화면을 복제하기보다, 제품이 가진 데이터·승인·UI는 그대로 두고 Codex를 작업 엔진으로 연결하는 방식이 실용적이다.
통합 계층을 고르는 기준
| 필요 | 권장 계층 | 적합한 경우 |
|---|---|---|
| 한 번 실행하는 스크립트·CI | codex exec | 입력과 종료 조건이 명확한 비대화형 작업 |
| 앱 코드에서 작업 시작·재개 | Codex SDK | 서버가 에이전트 작업을 프로그래밍 방식으로 관리할 때 |
| 스트리밍·도구·승인까지 직접 제어 | Codex app-server | 제품 UI 안에 지속 대화와 사람 검토를 넣을 때 |
이 구분에서 제품이 소유해야 할 것은 업무 맥락과 통제다. 예를 들어 운영 대시보드는 선택된 주문·정책·권한을 MCP 도구로 제공하고, 환불이나 재배정처럼 결과를 바꾸는 동작은 자체 승인 UI에서 확인한다. Codex는 그 사이의 탐색·계획·도구 실행 루프를 담당한다.
안전한 통합 순서
- 작업 경계를 고정한다. 에이전트가 읽을 레코드, 호출할 도구, 성공 조건을 업무 화면의 현재 상태에서 전달한다.
- 읽기와 쓰기를 분리한다. 검색·비교는 자동화하되 상태 변경 도구는 승인 요청을 거치게 한다.
- 결과를 시스템 기록으로 되돌린다. 도구 호출로 데이터가 바뀌면 앱이 다시 조회해 화면을 갱신하고, 에이전트의 자연어 답변만 성공 증거로 삼지 않는다.
- 이벤트를 관찰한다. 턴 시작, 도구 호출, 승인 대기, 오류, 완료 이벤트를 기록해 실패 지점을 재현 가능하게 만든다.
업무 UI·레코드·승인 정책 → 앱 소유 MCP 도구
↓
Codex app-server 하네스
↓
스트리밍 결과와 승인 요청흔한 오해
오픈소스인 부분은 하네스와 통합 표면이다. 모델 접근과 관리형 서비스는 별도다. 또한 범용 채팅 창을 붙이는 것만으로 업무 에이전트가 되지는 않는다. 사용자가 보고 있는 사건·주문·고객의 정보와, 허용된 조치·승인 조건을 앱이 구조화해 제공해야 한다.
관련 문서
- codex — Codex의 앱·CLI·IDE 사용법과 주요 기능
- agent-harness — 모델 외부 실행 환경을 설계하는 방법론
- mcp-v2 — 에이전트 도구를 HTTP 서버로 제공하는 MCP 구조
참고 자료
- Codex as a platform: build on the open agent harness — OpenAI Developers (2026-08-20)