Codex CLI의 codex agents 사용법: 여러 작업 찾기·전환·정리

Codex CLI를 여러 터미널에서 사용하다 보면 작업을 시작하는 것보다 이미 시작한 작업을 다시 찾는 일이 더 어려워집니다. 구현 작업은 끝났는지, 테스트 담당 서브에이전트는 아직 실행 중인지, 어느 세션이 승인 입력을 기다리는지 터미널 창만 보고는 한눈에 알기 어렵습니다.

Codex CLI의 작업 대시보드인 codex agents는 이런 루트 작업을 한곳에서 검색하고 열어 보는 기능입니다. 여기서 루트 작업은 codex로 시작한 하나의 독립 대화를 뜻하며, 그 안에서 생성한 서브에이전트는 별도 루트 작업으로 세지 않습니다. 새 작업 시작, 기존 작업 열기, 이름 변경, 중지에 더해 Codex CLI 0.155.0부터 Hide·Archive·Delete와 관리형 Worktree 소유권 표시가 추가됐습니다.[1][2]

Linux의 임시 Git 저장소와 격리된 Codex 프로필에서 0.155.0을 실행해 사전 루트 작업 4개를 준비하고, 대시보드에서 루트 작업 1개를 더 만들었습니다. 그중 한 작업에는 서브에이전트 1개를 포함했습니다. 작업 수 변화와 입력 대기 상태, Hide·Archive·Delete가 각각 무엇을 남기는지 직접 확인했으며 기준일은 2026년 9월 18일입니다.

codex agents가 필요한 이유

터미널 탭을 여러 개 열어 놓는 방식은 화면을 나눌 뿐, Codex 작업 자체를 분류하지는 않습니다. 세션이 늘어나면 다음 질문에 답하기 어려워집니다.

• 어떤 작업이 실행 중이고 어느 작업이 끝났는가

• 사용자 승인이나 추가 입력을 기다리는 작업은 무엇인가

• 같은 프로젝트에서 시작한 작업끼리 모아 볼 수 있는가

• 이전 작업을 다시 열거나 이름을 바꿀 수 있는가

• 끝난 작업을 화면에서만 치울지, 보관할지, 완전히 지울지

codex agents는 연결된 app-server의 루트 작업 목록을 보여 줍니다. 기본 로컬 실행에서는 백그라운드 프로세스인 공유 daemon이 작업 상태를 관리합니다. 터미널 패인을 유지하는 Herdr 에이전트 멀티플렉서와 달리 Codex 자체 작업 기록과 상태를 탐색하는 화면입니다. 파일과 브랜치를 나누는 Git Worktree 사용법도 대신하지 않습니다.

여러 에이전트를 쓸 이유가 아직 분명하지 않다면 먼저 AI 에이전트 하나와 여러 에이전트 비교에서 작업 분리 기준을 정하는 편이 좋습니다. 대시보드는 작업을 잘 나눠 주는 기능이 아니라, 이미 나뉜 작업을 찾고 관리하는 기능이기 때문입니다.

초보자를 위한 개념 흐름도입니다. 실제 대시보드 화면은 아래 실습 캡처에서 확인할 수 있습니다. 작은 화면에서는 이미지를 눌러 확대하세요.

그림처럼 구현·테스트·문서 작업을 따로 실행하면 터미널 위치보다 현재 상태를 먼저 봅니다. need input 작업은 사람이 답해야 다음 단계로 갈 수 있으므로 가장 먼저 열고, 진행 중인 작업은 그대로 두며, 완료 작업만 Hide·Archive·Delete 중 하나로 정리합니다. 이 순서가 codex agents를 효율적으로 쓰는 핵심입니다.

지원 버전과 설치 방식

codex agents 대시보드는 Codex CLI 0.149.0에서 처음 추가됐습니다. 이 버전의 공식 릴리스 노트는 검색, 작업 시작, 열기, 이름 변경, 중지를 지원한다고 설명합니다.[2]

0.155.0에서는 다음 기능이 더해졌습니다.[1]

먼저 현재 버전을 확인합니다.

codex --version
codex agents --help

이번 머신에 전역 설치돼 있던 버전은 0.153.4였습니다. 기본 대시보드는 사용할 수 있지만 Hide·Archive·Delete 실습에는 0.155.0이 필요해 공식 설치 스크립트의 관리형 standalone 바이너리를 임시 경로에 고정 설치했습니다.

여기서 중요한 설치 경계가 하나 있습니다. npx -y @openai/codex@0.155.0 agents는 도움말과 버전을 보여 줬지만 실제 대시보드를 열 때 다음 오류로 종료됐습니다.

Error: managed standalone Codex install not found

This command requires the standalone install managed by the Codex installer,
because the daemon starts and updates app-server from that fixed path.

즉 npm 패키지를 일회성으로 실행하는 것만으로는 공유 daemon을 시작할 수 없습니다. 공식 설치 스크립트가 관리하는 standalone 설치가 필요합니다. 설치 명령을 바로 파이프로 넘기기보다 먼저 내려받아 내용을 확인합니다.[3]

curl -fsSL https://chatgpt.com/codex/install.sh -o /tmp/codex-install.sh
less /tmp/codex-install.sh
CODEX_HOME=/tmp/codex-agents-home \
CODEX_INSTALL_DIR=/tmp/codex-bin \
CODEX_NON_INTERACTIVE=true \
sh /tmp/codex-install.sh --release 0.155.0

/tmp/codex-bin/codex --version

격리 프로필을 처음 쓴다면 토큰 파일을 복사하지 말고 새 경로에서 로그인합니다. 대시보드도 같은 CODEX_HOME과 명시적 바이너리 경로로 실행해야 기존 설치와 섞이지 않습니다.

CODEX_HOME=/tmp/codex-agents-home /tmp/codex-bin/codex login
CODEX_HOME=/tmp/codex-agents-home /tmp/codex-bin/codex agents

현재 설치를 무조건 0.155.0으로 내리거나 올릴 필요는 없습니다. 최신 안정 버전에 기능이 포함돼 있는지 codex --version과 공식 릴리스 페이지를 먼저 비교하세요. 설치 스크립트는 CODEX_HOME, CODEX_INSTALL_DIR, --release 값을 받지만 셸 프로필의 PATH도 바꿀 수 있습니다. 실행 전 설치 위치와 프로필 변경 부분을 확인하고, 검증 뒤 임시 PATH 항목이 남지 않았는지 점검하세요.

실습 환경

이번 확인은 기존 프로젝트와 작업 기록을 섞지 않도록 임시 저장소와 별도 CODEX_HOME에서 진행했습니다.

파일을 수정하지 않는 읽기 작업부터 시작했습니다. 루트 작업 하나에는 README와 package.json 요약을, 다른 작업에는 서브에이전트 한 개를 만들어 sum.js와 sum.test.js의 일치 여부를 확인하도록 지시했습니다.

Use exactly one subagent to inspect sum.js and sum.test.js.
Ask it to verify whether the test matches the implementation.
Do not modify files.

서브에이전트는 sum(2, 3)이 5인지 확인하는 테스트 1건을 실행했고 통과 결과를 루트 작업에 돌려줬습니다. 이 실습은 실제 파일 변경이나 원격 push 없이 세션 구조만 확인하는 범위로 제한했습니다.

작업 대시보드 열기

프로젝트 폴더에서 다음 명령을 실행합니다.

cd ~/projects/my-app
codex agents

화면 왼쪽에는 프로젝트별 루트 작업이, 오른쪽에는 선택한 작업의 상태와 마지막 메시지, 프로젝트 경로, 브랜치, 원문 프롬프트가 표시됩니다. 상단 숫자는 입력 대기, 작업 중, 준비 완료 상태를 빠르게 보여 줍니다.

실제 tmux 터미널 셀을 캡처한 화면입니다. 작은 화면에서는 이미지를 눌러 원본 크기로 확인할 수 있습니다.

이번 화면에서 확인한 기본 단축키는 다음과 같습니다.

단축키는 버전과 사용자 설정에 따라 달라질 수 있습니다. 화면 하단의 실제 키 안내를 기준으로 사용하세요. 0.149.0 릴리스부터 키 바인딩을 설정할 수 있으므로 다른 키가 보이면 문서 예시보다 현재 화면이 우선입니다.[2][4]

새 작업과 입력 대기 상태

Ctrl+N을 누르면 대시보드 아래 입력칸에서 새 루트 작업을 시작할 수 있습니다. 이번에는 README를 한 문장으로 요약하는 읽기 작업을 만들었습니다.

Read README.md and answer in one Korean sentence what this lab tests.
Do not modify files.

작업이 실행되는 동안 상단은 1 working으로 바뀌었습니다. 이 서비스 환경에서는 bubblewrap 권한 문제로 기본 샌드박스의 파일 읽기가 실패했고, Codex가 샌드박스 밖에서 cat README.md를 실행해도 되는지 물었습니다. 대시보드는 이 작업을 Needs input으로 바꾸고 상단에 1 need input을 표시했습니다.

→로 작업을 열자 실제 승인 화면이 이어졌습니다. 허용 뒤에는 README를 읽고 한 문장으로 답한 다음 작업이 끝났습니다. 이 결과가 증명하는 범위는 다음과 같습니다.

• 대시보드의 need input 숫자로 사람이 개입할 작업을 찾을 수 있음

• 작업을 열면 원래 Codex 대화와 승인 흐름으로 이어짐

• 대시보드 자체가 권한을 완화하거나 명령을 대신 승인하지 않음

왼쪽 목록의 Needs input 작업을 선택하면 오른쪽에 필요한 승인과 대기 이유가 나타납니다. 작은 화면에서는 이미지를 눌러 원본 크기로 확인할 수 있습니다.

화면을 보는 순서도 단순합니다. 먼저 상단의 need input 숫자를 보고, 왼쪽에서 ● 표시 작업을 선택한 뒤, 오른쪽 Needs attention에서 왜 멈췄는지 읽습니다. 그다음 →로 작업을 열어 실제 명령과 대상을 확인하고 승인 여부를 결정합니다.

bubblewrap 오류는 이번 호스트의 서비스 실행 환경에서 관찰한 문제이며 Codex CLI 0.155.0의 일반 동작으로 확대하면 안 됩니다. 권한과 샌드박스 기준은 OpenAI Codex 권한 설정에서 별도로 확인할 수 있습니다.

/agent와 대시보드의 차이

이름이 비슷하지만 공식 문서의 /agent와 셸에서 실행하는 codex agents는 범위가 다릅니다.[5]

공식 문서는 서브에이전트를 “Codex가 특정 작업을 처리하도록 위임해 시작한 에이전트”, agent thread를 “서브에이전트가 작업하는 스레드”로 설명합니다. 현재 대화 안에서 진행 중인 서브에이전트를 바꿔 보려면 /agent를 사용합니다.[5]

이번 실습에서도 서브에이전트 한 개를 만든 작업은 대시보드에서 루트 작업 한 줄로 표시됐습니다. 오른쪽 마지막 메시지에는 서브에이전트 결과가 보였지만 자식 스레드가 별도 루트 행으로 늘어나지는 않았습니다.

Hide·Archive·Delete 구분

완료 작업을 치울 때 세 동작을 모두 “삭제”라고 보면 안 됩니다. 남는 기록과 복구 가능성이 다릅니다.

잠깐 치우는 Hide

완료된 작업 한 개를 선택해 Ctrl+W를 누르자 프로젝트 그룹의 표시 개수가 4에서 3으로 줄었습니다. 확인창 없이 현재 대시보드에서만 숨겨졌습니다. TUI를 종료하고 다시 codex agents를 실행하자 개수가 다시 4로 돌아왔습니다.

공식 구현 설명도 Hide를 “선택한 작업을 중지하지 않고 숨기는 동작”으로 정의합니다. 작업 활동이나 메타데이터가 갱신돼도 숨김은 유지되지만, 명시적으로 재개하거나 TUI를 다시 시작하면 다시 나타납니다.[6]

되돌릴 수 있는 Archive

Ctrl+E를 누르면 루트 작업과 자식 에이전트를 중지한 뒤 기록을 보관한다는 확인창이 열립니다. 기본 선택은 Cancel입니다.

작은 화면에서는 이미지를 눌러 원본 크기로 확인할 수 있습니다.

Archive task and child agents를 선택하자 표시 개수가 4에서 3으로 줄었습니다. 기록은 영구 삭제되지 않으며 codex resume에서 이전 작업을 고르는 화면인 resume picker에서 복원할 수 있습니다.[1][7]

되돌릴 수 없는 Delete

Delete 키를 누르면 영구 삭제 경고가 나옵니다. 이 확인창도 기본 선택은 Cancel입니다.

작은 화면에서는 이미지를 눌러 원본 크기로 확인할 수 있습니다.

확인 뒤에는 표시 개수가 3에서 2로 줄었습니다. Delete는 선택한 루트 작업과 자식 에이전트의 실행을 중지하고 기록을 영구 삭제합니다. 나중에 참고할 프롬프트, 결정, 테스트 결과가 있다면 먼저 Archive를 고르는 편이 안전합니다.[1][7]

관리형 Worktree 정리 기준

Codex CLI 0.155.0의 Worktree 소유권 표시는 작업 기록 정리와 별도인 관리형 Worktree 브라우저 기능입니다. 여기서 관리형 Worktree는 Codex가 만들고 소유권 정보를 관리하는 Worktree를 뜻합니다. 이번 임시 대시보드 작업은 모두 원본 저장소의 main에서 실행했으므로 관리형 Worktree 제거까지 직접 재현하지 않았습니다. 아래 경계는 0.155.0 릴리스와 해당 기능의 공식 구현 설명을 기준으로 합니다.[1][8]

소유권 정보에는 소유자 스레드 제목과 마지막 업데이트 시각, Archived 또는 Unavailable 같은 상태가 표시될 수 있습니다. 하지만 소유권 표시는 잠금이나 현재 사용 중이라는 보증이 아닙니다. 다른 세션이 같은 checkout을 사용하고 있는지 따로 확인해야 합니다.[8]

대시보드에서 제거할 수 있는 범위도 제한돼 있습니다.

• 현재 저장소가 관리하는 managed worktree만 대상

• 현재 checkout은 경로 표기가 달라도 제거 거부

• 수정된 tracked 파일이 있으면 제거 거부

• untracked 파일이 있으면 제거 거부

• .gitignore에 포함된 ignored 파일이 있어도 제거 거부

• Worktree를 제거해도 thread history는 유지

정리 전에 Git에서도 상태를 확인합니다.

git worktree list
git -C ../managed-worktree status --short --untracked-files=all --ignored
git -C ../managed-worktree clean -ndx

git clean -ndx는 삭제 실행이 아니라 ignored·untracked 파일을 포함한 정리 후보 미리보기입니다. .env, 빌드 결과, 다운로드 파일처럼 Git이 추적하지 않지만 남겨야 할 자료가 없는지 확인합니다.

기록 Delete가 Worktree까지 자동으로 지운다고 생각하거나, Worktree 제거가 작업 기록까지 삭제한다고 생각하면 안 됩니다. 공식 확인 메시지도 Worktree 제거 뒤 thread history는 유지된다고 구분합니다.[8]

검색·전환·정리 순서

작업이 많아졌을 때는 다음 순서가 단순합니다.

1. codex agents를 열고 상단의 need input, working, ready 숫자를 확인합니다.

2. Ctrl+F로 프로젝트나 작업 문구를 검색합니다.

3. 입력 대기 작업부터 →로 열어 승인·질문을 처리합니다.

4. 이름이 모호한 작업은 Ctrl+R로 목적이 드러나게 바꿉니다.

5. 현재 대화의 서브에이전트 상태는 작업 안에서 /agent로 확인합니다.

6. 당장 목록에서만 치울 작업은 Hide, 나중에 복원할 작업은 Archive를 선택합니다.

7. 정말 필요 없는 기록만 Delete합니다.

8. 관리형 Worktree는 기록 정리와 분리해 소유권·Git 상태·다른 세션 사용 여부를 확인합니다.

역할 이름과 완료 조건이 처음부터 분명하면 대시보드에서도 찾기 쉽습니다. 구현자·테스트 담당·문서 담당처럼 작업 지시를 나누는 방법은 AI 에이전트 역할 정의서에서 이어서 볼 수 있습니다.

자주 막히는 지점

명령이 보이지 않음

codex agents는 0.149.0에서 추가됐습니다. 버전을 먼저 확인하고 공식 설치 경로로 업데이트합니다.

codex --version
codex agents --help

managed standalone 오류

npm의 특정 버전을 npx로 일회성 실행해도 daemon에 필요한 managed standalone 설치가 없으면 대시보드가 열리지 않을 수 있습니다. 이 글의 실습에서도 같은 오류를 확인했습니다. 공식 설치 스크립트로 설치한 뒤 실제 실행 경로와 버전을 다시 확인합니다.

command -v codex
codex --version

작업이 목록에 없음

다음 순서로 범위를 확인합니다.

• 같은 사용자와 같은 Codex 홈을 쓰는지

• 다른 프로젝트 그룹으로 묶여 있지 않은지

• 검색 필터가 남아 있지 않은지

• Hide한 작업이라면 TUI를 다시 시작했는지

• Archive한 작업이라면 resume picker에서 찾을 수 있는지

작업이 Needs input에서 멈춤

대시보드에서 작업을 열고 실제 질문이나 승인 요청을 읽습니다. 자동 승인으로 우회하기보다 명령, 대상 파일, 네트워크·삭제 여부를 확인한 뒤 승인하거나 다른 방법을 지시합니다. 대시보드는 입력 대기를 찾아 줄 뿐 안전 판단을 대신하지 않습니다.

원격 app-server 연결

codex agents --help에는 --remote, --remote-auth-token-env, -C 옵션이 표시됩니다. --remote는 ws://, wss://, unix:// 형태의 app-server endpoint를 받고, -C는 원격 서버에서 새 작업에 사용할 디렉터리를 지정합니다.

원격 bearer token은 명령줄에 값을 직접 쓰지 말고 --remote-auth-token-env에 토큰이 들어 있는 환경변수 이름을 전달합니다. 외부 네트워크를 통과한다면 평문 ws://보다 인증과 암호화가 적용된 운영 구성을 먼저 확인하세요. 이번 실습은 로컬 daemon만 사용했으며 원격 연결은 실행하지 않았습니다.

작업 정리 체크리스트

정리

codex agents의 장점은 에이전트를 무조건 더 많이 실행하는 데 있지 않습니다. 흩어진 루트 작업을 한 화면에서 찾고, 입력이 필요한 작업으로 전환하며, 완료 기록을 의도에 맞게 정리하는 데 있습니다.

처음에는 읽기 전용 작업 두 개로 시험해 보세요. 하나는 일반 루트 작업, 다른 하나는 서브에이전트 한 개를 포함한 작업으로 만들면 codex agents와 /agent의 범위를 구분하기 쉽습니다. 그다음 Hide로 화면만 정리하고, Archive 확인창과 resume 경로를 익힌 뒤, Delete는 복원이 필요 없는 임시 기록에만 사용합니다.

Worktree 정리는 마지막입니다. 소유권 표시는 참고 정보이지 잠금이 아니며, 작업 기록 삭제와 폴더 제거도 같은 동작이 아닙니다. Git 상태와 남길 파일을 확인한 뒤 깨끗한 관리형 Worktree만 정리해야 합니다.

참고 자료

• [1] OpenAI Codex CLI 0.155.0 릴리스

• [2] OpenAI Codex CLI 0.149.0 릴리스

• [3] OpenAI Codex 공식 설치 스크립트

• [4] Codex agents 키 바인딩 변경

• [5] OpenAI Codex 공식 문서 — Subagents

• [6] Codex 작업 Hide 동작

• [7] Codex 작업 Archive·Delete 동작

• [8] Codex 관리형 Worktree 소유권·정리