cola-io/codex-acp

이 저장소 코드의 대부분은 다음의 에이전트에 의해 구현되고 검토됩니다.

codex

OpenAI Codex 런타임을 stdio를 통해 ACP 클라이언트와 연결하는 Agent Client Protocol (ACP) 호환 에이전트입니다. 이 프로젝트는 활발히 개발 중이며, 기능이 진화하고 있으며 파괴적 변경(breaking changes)이 발생할 가능성이 높습니다.

이 에이전트는 다음과 같은 몇 가지 핵심 모듈을 중심으로 구조화되어 있습니다:

— 핵심 ACP 요청 핸들러 (agent/core.rs 내 initialize, authenticate, new_session, load_session, prompt 등) 및 CodexAgent 구현
— 다음을 포함한 통합 세션 관리 (agent/session_manager.rs):
- 세션 상태 저장 및 변이 (mutation)
- 세션 모드/모델 쿼리 (current_mode(), is_read_only(), resolve_acp_session_id())
- 대화 로딩 및 캐싱
- 클라이언트 업데이트 알림
- 컨텍스트 오버라이드(Context override) 작업

— 슬래시 명령어 핸들러 (agent/commands.rs 내 /init, /status, /compact, /review)
— Codex 이벤트 → ACP 업데이트 변환 및 추론 집계 (agent/events.rs)
— 세션/대화 설정 구성 (cwd, MCP 서버 등) (agent/config_builder.rs)
— 파일 시스템 브리지 및 fs/ 내 acp_fs MCP 서버 구현

주요 설계 원칙:

SessionManager는 변이(mutation)와 쿼리(query)를 포함한 모든 세션 작업을 중앙 집중화합니다.
SessionState는 세션별 상태를 나타내는 순수 데이터 구조(pure data structure)입니다.
에이전트는 단일 스레드 비동기(async) 처리를 위해 LocalSet을 사용하는 Tokio의 current-thread 런타임에서 실행됩니다.
agent-client-protocol을 사용하여 stdio를 통해 Agent Client Protocol (ACP)을 수행합니다.
대화 관리 및 이벤트 스트리밍을 위해 Codex Rust 워크스페이스와 통합됩니다.
ACP AvailableCommands 업데이트를 포함한 슬래시 명령어를 제공합니다 (세션 시작 시 클라이언트에 광고됨).
IDE에 최적화된 상태 출력 (워크스페이스, 계정, 모델, 토큰 사용량).
ACP 세션 모드를 지원합니다: read-only, auto (기본값), full-access.
rmcp로 구축된 내부 MCP 파일 시스템 서버(acp_fs)를 자동으로 실행하므로, Codex는 셸 명령 대신 ACP 도구를 통해 파일을 읽고 씁니다.

ACP Agent 구현 (implementation)

initialize, authenticate, session/new, session/load, session/prompt, session/cancel, session/setMode, session/setModel을 처리합니다.
OpenAI (ChatGPT/API key) 및 커스텀 모델 제공자 (custom model providers)에 대한 인증을 지원합니다.
Codex 이벤트 (어시스턴트 메시지, 추론 (reasoning), 토큰 수 (token counts), 도구 호출 (tool calls))를 session/update 알림으로 스트리밍합니다.
이벤트 집계 (Event aggregation): 추론 델타 (reasoning deltas)는 누적되어 완성된 블록 형태로 전송됩니다.
AvailableCommandsUpdate를 통해 공지되는 **슬래시 명령 (Slash commands)**을 처리합니다.
- /init — 리포지토리 기여자 가이드가 포함된 AGENTS.md를 생성합니다. 번들로 포함된 프롬프트 (src/agent/prompt_init_command.md)를 사용합니다.
- /status — 상세한 상태 출력 (워크스페이스, 계정, 모델, 토큰 사용량).
- /compact — 컨텍스트 크기를 줄이기 위해 Codex에 대화 압축/요약을 요청합니다.
- /review — Codex에 현재 변경 사항을 검토하고, 문제를 강조하며, 수정 사항을 제안하도록 요청합니다.
명령은 세션 시작 시 클라이언트에 동적으로 공지됩니다.
세션 모드 (Session modes)
- 세 가지 사전 설정된 모드: read-only, auto (기본값), 그리고 full-access.
- 모드는 승인 정책 (approval policy) 및 샌드박스 제한 (sandbox restrictions)을 제어합니다.
- 클라이언트는 session/setMode를 통해 모드를 전환하며, 에이전트는 CurrentModeUpdate를 방출합니다. SessionManager는 모드 제한을 확인하기 위해 is_read_only()를 제공합니다.
- 세 가지 사전 설정된 모드:
커스텀 모델 제공자 지원 (Custom model provider support)
- 커스텀 (OpenAI가 아닌) 제공자를 위한 동적 모델 목록 표시 및 전환을 지원합니다.
- 모델 형식: {provider_id}@{model_name} (예: OpenRouter@anthropic/claude-3-opus).
- Codex 설정 프로필을 통해 제공자와 모델을 구성합니다.
- 내장되지 않은 제공자를 위한 전용 custom_provider 인증 방법을 제공합니다.
- 모델 전환은 커스텀 $\rightarrow$ 커스텀 제공자 간의 전환만 강제합니다.
세션 관리 (Session management)
SessionManager는 모든 세션 작업에 대한 통합 인터페이스를 제공합니다:
상태 쿼리: current_mode(), is_read_only(), resolve_acp_session_id()
대화 관리 (Conversation management): 캐싱을 이용한 지연 로딩 (lazy loading)
클라이언트 알림 (Client notifications):
send_session_update()
, send_message_chunk()
, send_thought_chunk()
컨텍스트 오버라이드 (Context overrides):
승인/샌드박스/모델 변경을 위한
apply_context_override()
상태 쿼리 (State queries):
읽기 전용 작업 또는 내부 변이 (internal mutation)를 위해
agent.session_manager()
를 통해 액세스합니다.
Rust (rust-toolchain.toml에 고정된 Rust 2024 edition; rustc 1.91+).
Git 의존성(Codex 워크스페이스, ACP 크레이트) 빌드를 위한 네트워크 액세스.

make build

팁: 바이너리를 Zed와 같은 IDE로 배포할 때는
make release
(또는 cargo build --release)를 사용하세요. 릴리스 빌드는 target/release/codex-acp에 위치합니다.

이 설정을 Zed 설정에 추가하세요.

"agent_servers": {
"Codex": {
"command": "/path/to/codex-acp",
...

세션이 시작되면, codex-acp는 프로세스 내 TCP 브리지 (in-process TCP bridge)를 실행하고 rmcp를 사용하여 acp_fs라는 이름의 MCP 서버를 등록합니다. 그러면 Codex는 다음과 같은 구조화된 도구 (structured tools)를 호출합니다:

read_text_file — ACP client.read_text_file을 통해 워크스페이스 파일을 읽으며, 클라이언트에 파일 시스템 (FS) 지원이 없는 경우 로컬 디스크로 폴백 (fallback)합니다.
write_text_file — ACP client.write_text_file을 통해 워크스페이스 파일을 쓰며, 로컬 폴백을 제공합니다.
edit_text_file — 파일 내에서 집중된 교체 (focused replace)를 적용하고 저장합니다.
multi_edit_text_file — 여러 개의 순차적인 교체를 적용하고 저장합니다.

codex-acp는 또한 모델이 cat / tee를 사용하여 셸 명령을 실행하는 대신 이러한 도구들을 사용하도록 상기시키는 기본 지침 (default instruction)을 주입합니다. 클라이언트가 파일 시스템 기능을 노출하는 경우, 파일 액세스는 ACP 내에서 유지됩니다.

동적 도구 가용성 (Dynamic tool availability):

도구는 클라이언트의 파일 시스템 기능에 따라 활성화/비활성화됩니다.
읽기 전용 세션은 쓰기 도구(write_text_file, edit_text_file, multi_edit_text_file)를 비활성화합니다.
클라이언트에 FS 지원이 없는 경우, 도구는 로컬 디스크 I/O로 폴백합니다.
FS 브리지는 MCP 서버 통신을 위해 전용 브리지 주소와 세션 ID를 사용합니다.

/status 명령은 다음과 같이 사람이 읽기 쉬운 요약 정보를 출력합니다:

📂 Workspace (워크스페이스)
• Path (경로): ~/path/to/workspace
• Approval Mode (승인 모드): on-request (요청 시)
...

참고 사항 (Notes)

인증 모드 (auth mode) 및 환경에 따라 일부 필드는 알 수 없음 (unknown)으로 표시될 수 있습니다.
토큰 수 (Token counts)는 사용 가능한 경우 Codex의 EventMsg::TokenCount로부터 집계됩니다.

codex-acp는 다음과 같은 여러 인증 방법 (authentication methods)을 지원합니다:

ChatGPT: codex login을 통해 ChatGPT 계정으로 로그인

API Key (API 키): 환경 변수 또는 auth.json에서 OPENAI_API_KEY 사용

커스텀 모델 제공자 (Custom model providers, 예: Anthropic, 커스텀 LLM)의 경우:

Codex 설정에서 제공자 (provider)를 구성하십시오:

model_provider_id = "anthropic" model = "claude-3-opus" [model_providers.anthropic] name = "Anthropic" # ... 제공자별 설정 [profiles.custom-fast] model = "claude-3-haiku" model_provider = "anthropic"

에이전트 (agent)는 초기화 중에 custom_provider 인증 방법을 공지합니다.
Codex 설정에 구성된 제공자별 자격 증명 (credentials)으로 인증하십시오.

OpenAI: 표준 인증, 모델 전환 없음 (설정 기본값 사용)

Custom Providers (커스텀 제공자):

세션 응답의 available_models를 통한 모델 목록 확인
{provider}@{model} 형식을 사용하는 session/setModel을 통한 모델 전환
쉬운 전환을 위한 여러 모델 프로필 (model profiles)

모델 목록 확인 예시 (커스텀 제공자 전용):

{
"method": "session/setModel",
"params": {
...

codex-acp는 tracing을 사용하며 stderr 및/또는 파일로 로그를 남길 수 있습니다. 환경 변수를 통해 이를 구성하십시오:

환경 변수 (우선순위가 높은 순서대로):

CODEX_LOG_FILE — 로그를 추가할 경로 (순환되지 않음/non-rotating). 상위 디렉토리는 자동으로 생성됩니다. 파일 로그의 경우 ANSI는 비활성화됩니다.

CODEX_LOG_DIR — 일일 순환 로그 (file name: acp.log)를 위한 디렉토리. 디렉토리는 자동으로 생성됩니다. 파일 로그의 경우 ANSI는 비활성화됩니다.

CODEX_LOG_STDERR — stderr 로깅을 비활성화하려면 0, false, off, 또는 no로 설정하십시오. 기본적으로 활성화되어 있습니다.

RUST_LOG — 표준 필터링 지시어 (설정되지 않았거나 유효하지 않은 경우 기본값은 info). 예시: info, debug

, codex_acp=trace,rmcp=info

동작 (Behavior):

CODEX_LOG_FILE이 설정된 경우, 로그는 stderr (비활성화되지 않은 경우) 및 지정된 파일로 전송됩니다. - 그렇지 않고 CODEX_LOG_DIR이 설정된 경우, 로그는 stderr (비활성화되지 않은 경우) 및 해당 디렉토리 내의 일일 로테이션 (daily-rotated) 파일로 전송됩니다. - 그 외의 경우 로그는 stderr로만 전송됩니다 (비활성화되지 않은 경우).

예시 (Examples):

# 콘솔 전용
RUST_LOG=info cargo run --quiet
# 콘솔 + 파일에 추가 (로테이션 없음)
...

Zed ACP 예시 (Claude): https://github.com/zed-industries/claude-code-acp
Agent Client Protocol (Rust): https://crates.io/crates/agent-client-protocol
OpenAI Codex (Rust workspace): https://github.com/openai/codex
rmcp (Rust MCP): https://github.com/domdomegg/rmcp

cola-io/codex-acp

요약

핵심 포인트

댓글