이번 주에 하나의 설정 스니펫이 떠돌고 있습니다. Codex의 config.toml에 agents.max_concurrent_threads_per_session = 64를 설정하면 하나의 세션이 수십 개의 서브에이전트로 뻗어 나가는 걸 볼 수 있다는 내용입니다. 이걸 처음 퍼뜨린 글에서는 기본값이 3이고 OpenAI가 64를 테스트했다고 주장합니다. 설정 자체는 실재합니다. 하지만 그 두 숫자는 문서에 없고, 흥미로운 지점은 상한값이 전혀 아닙니다. 상한을 올렸을 때 작업에 무슨 일이 벌어지는지가 핵심입니다.
이 글에서는 Codex 레퍼런스를 기준으로 이 설정이 실제로 하는 일과, 한 사람이 다 읽을 수 없을 만큼 많은 에이전트가 하나의 세션에서 돌아갈 때 순서대로 무너지는 세 가지를 다룹니다.
요약
agents.max_concurrent_threads_per_session은 Codex가 동시에 열어 두는 스폰된 에이전트 스레드의 수를 제한하며, 기본 스레드는 여기에 포함되지 않습니다. 레퍼런스에는 기본값이 공개되어 있지 않고, 키를 설정하지 않으면 Codex가 기본값을 선택한다고만 나와 있습니다. 서브에이전트는 메인 스레드에 요약을 반환하고, 메인 스레드는 이들 모두를 기다렸다가 한 번에 응답합니다. 문서에서는 읽기 위주 작업에 서브에이전트를 권장하면서, 병렬 쓰기 위주 워크플로는 충돌과 조정 오버헤드를 일으킨다고 경고합니다. 상한을 64로 올리면 바로 이 두 지점, 즉 공유 파일과 아무도 감사할 수 없는 단일 통합 응답이 부각됩니다. Sharkly는 Codex를 런타임으로 실행하면서 병렬성을 한 단계 위로 끌어올립니다. 각 실행이 자체 워크트리, 자체 로그, 자체 리뷰어를 가진 Task가 되는 방식입니다.
이 설정이 하는 일
config.toml의 [agents] 섹션에서 여기서 중요한 키는 세 가지입니다. 아래 문구는 구성 레퍼런스에서 그대로 인용한 것입니다.
| 키 | 레퍼런스 설명 |
|---|---|
agents.max_concurrent_threads_per_session |
“동시에 열 수 있는 스폰된 에이전트 스레드의 최대 수이며, 기본 스레드는 제외된다. 설정하지 않으면 Codex가 기본값을 선택한다.” |
agents.max_threads |
“agents.max_concurrent_threads_per_session의 레거시 별칭.” |
agents.enabled |
“멀티 에이전트 도구를 활성화하거나 비활성화한다(기본값: true).” |
관련 키 두 개, agents.default_subagent_model과 agents.default_subagent_reasoning_effort는 스폰 호출에서 별도로 지정하지 않는 한 스폰된 에이전트가 무엇으로 실행될지를 정합니다.
따라서 이 스니펫은 적힌 그대로 작동합니다.
[agents]
max_concurrent_threads_per_session = 64
레퍼런스에 없는 것은 기본값이 무엇인지, 혹은 어떤 값이 테스트되었는지입니다. “기본값 3”과 “OpenAI가 64를 테스트했다”는 문서에서 달리 언급되기 전까지는 벤더가 아닌 어떤 글의 주장으로 취급하세요.
서브에이전트 가이드에는 상한을 올리는 것이 좋은 판단인지 결정해 주는 두 문장이 더 있습니다. 결과에 대해서는 “많은 에이전트가 실행 중일 때 Codex는 요청된 모든 결과를 사용할 수 있을 때까지 기다린 뒤 통합된 응답을 반환한다”고 합니다. 적합성에 대해서는 서브에이전트가 “탐색, 테스트, 트리아지, 요약 등 읽기 위주 작업”에 어울린다고 하며, “병렬 쓰기 위주 워크플로는 에이전트가 동시에 코드를 편집하면 충돌이 생기고 조정 오버헤드가 늘어날 수 있으므로” 주의하라고 조언합니다.
이 둘을 함께 읽으면 무너지는 순서는 저절로 드러납니다.
가장 먼저 무너지는 것: 공유 체크아웃
별도로 조치하지 않는 한 하나의 세션에 있는 서브에이전트는 그 세션의 작업 디렉터리를 공유합니다. 에이전트 64개가 읽기만 한다면 문제없습니다. 하지만 4개가 쓰기를 한다면 머지 문제가 됩니다.
실패는 극적이지 않습니다. 서브에이전트 두 개가 같은 파일을 편집하고, 두 번째 쓰기가 이기고, 통합 요약은 두 작업 모두 완료되었다고 보고합니다. 리뷰가 있다면 리뷰에서, 없다면 프로덕션에서 이 사실을 알게 됩니다. 문서에서 충돌과 조정 오버헤드를 경고하는 대목이 바로 이 상황을 말하는 것입니다.
해법은 모든 병렬 에이전트 구성이 수렴하는 그 방법입니다. 작업 단위마다 작업 사본 하나를 두는 것입니다. Sharkly에서는 각 Task 실행이 격리된 디렉터리를 받고, 저장소 기반 작업은 실행마다 별도의 git 워크트리를 사용합니다. 이는 격리된 워크트리에서의 병렬 에이전트에서 다룬 메커니즘입니다. 하나의 저장소에 대해 10개의 Task, 공유 상태는 전혀 없습니다. 편집을 수행하는 런타임은 여전히 Codex일 수 있고, 격리는 그 주변에 제공됩니다.
두 번째로 무너지는 것: 통합 응답
Codex는 모든 서브에이전트를 기다린 뒤 하나의 응답을 반환합니다. 서브에이전트가 4개라면 이건 편의 기능입니다. 64개라면, 작업 64개를 요약한 하나의 메시지가 되는데, 이를 디스패치한 에이전트가 작성하고 중간 출력은 접혀 사라집니다.
이건 리뷰에 맞지 않는 형태입니다. 리뷰어는 각 작업 단위가 무엇을 건드렸고, 무엇을 실행했고, 어디서 멈췄는지 알아야 하며, 각각을 개별적으로 수락하거나 거부할 수 있어야 합니다. 요약의 요약은 부분적으로 수락할 수 없습니다.
Sharkly는 에이전트의 최종 응답을 Task에 저장하고, 실행마다 트리거, 시작과 종료 시각, 도구 호출, 런타임 이벤트, 실패 세부 정보를 담은 실행 로그를 유지합니다. 실행 내역은 댓글 타임라인과 분리된 자체 탭에 들어갑니다. 작업 단위 64개는 로그 64개를 가진 Task 64개가 되고, 각각 검토 가능하며, 각각의 결과를 사람이 확인할 곳으로 반환합니다.
세 번째로 무너지는 것: 루프 안의 사람
상한값은 서브에이전트에 사람 손이 필요할 때 무슨 일이 일어나는지 전혀 말해 주지 않습니다. 하나의 세션 안에서 막힌 서브에이전트는 통합 대기 속에서 조용히 멈춰 버린 스레드입니다. 메인 스레드가 당신을 대신해 답할 수 없고, 64개 스레드 중 어느 것이 멈춘 건지도 알 수 없습니다.
Sharkly는 Task 상태와 에이전트 작업 상태를 분리해서 유지합니다. 시작된 Task는 Working, Waiting for human reply, Waiting for human review, Error 중 하나를 표시할 수 있습니다. 대기 및 실패 신호는 Inbox의 기본 섹션에서 담당자에게 전달되고, Task에 답글을 달면 해당 스레드를 컨텍스트로 후속 실행이 시작됩니다. 막힌 작업이 검사할 수도 없는 대기 속에 매달려 있는 대신 스스로 알려 주는 것입니다.
서브에이전트일까, Task일까? 선택 기준
작업이 읽기 위주이고 하나의 답으로 수렴할 때는 하나의 세션 안에서 Codex 서브에이전트를 사용하세요. 코드베이스 탐색, 실패 배치 트리아지, 문서 묶음 요약, 테스트 스위트 실행 등이 여기에 해당합니다. 가이드에서 권장하는 용도가 바로 이것이며, 쓰기가 없는 작업에서는 상한을 높여도 부담이 적습니다.
작업 단위가 코드를 작성하거나, 서로 다른 사람이 서로 다른 부분을 리뷰하거나, 실행 도중 사람이 답해야 할 수도 있을 때는 컴퓨터 위의 에이전트에 각각 할당된 별도의 Task를 사용하세요. Sharkly는 Codex를 대체하는 것이 아닙니다. Codex는 각 Task를 실행하는 런타임입니다. 차이는 병렬성이 어디에 있느냐입니다. 하나의 세션의 통합 대기 안에 있는지, 아니면 요청부터 릴리스까지 컨텍스트, 진행 상황, 블로커, 결과, 사람의 리뷰가 계속 보이는 보드 전반에 걸쳐 있는지입니다.
상한을 안전하게 올리는 방법
max_concurrent_threads_per_session을 올린다면, Sharkly 자체 동시성 문서에서 컴퓨터에 대해 설명하는 방식대로 하세요. 현재 구성이 기존 워크로드를 안정적으로 처리한 뒤에만 늘리라는 것입니다. 동시성이 높아지면 CPU, 메모리, 디스크, 제공자 용량, 저장소 대역폭을 더 많이 소비하기 때문입니다. Sharkly의 컴퓨터에는 자체 작업 동시성 한도가 있고, 임시 디렉터리를 사용하는 에이전트는 기본적으로 그 절반으로 설정됩니다. 용량은 컴퓨터, 에이전트의 동시성, 디렉터리 가용성에 의해 제한되며, 온라인 상태의 에이전트라도 그 용량이 꽉 차면 대기 중인 작업이 남아 있을 수 있습니다.
사람들이 가장 자주 잊는 것이 제공자 용량입니다. API 키 하나에 스레드 64개를 걸면 한꺼번에 레이트 리밋에 부딪힐 수 있는 경로가 64개라는 뜻이고, “할당량 소진”을 의미하는 429는 재시도로 해결되지 않습니다. Sharkly의 실패 실행 로그는 제공자의 원래 응답을 알아보기 쉬운 제목과 함께 보관하므로, 누군가 재시도하기 전에 차이를 확인할 수 있습니다.
자주 묻는 질문
agents.max_concurrent_threads_per_session의 기본값은 무엇인가요? 구성 레퍼런스에는 명시되어 있지 않습니다. 키를 설정하지 않으면 Codex가 기본값을 선택한다고 나와 있습니다. 소셜 미디어에 떠도는 숫자는 레퍼런스에서 나온 것이 아닙니다.
상한을 높이면 Codex가 더 빨라지나요? 읽기 위주 팬아웃에서는 스레드가 많을수록 더 빨리 끝납니다. 쓰기 위주 작업에서는 문서에서 동시 편집이 충돌과 조정 오버헤드를 일으킨다고 경고하며, 이는 병렬성이 절약해 주는 시간보다 더 많은 시간을 잡아먹습니다.
Codex 서브에이전트는 별도의 git 워크트리에서 실행되나요? 서브에이전트 가이드에는 그렇다고 나와 있지 않습니다. 직접 격리를 설정하지 않았다면 작업 디렉터리를 공유한다고 가정하고 계획하세요.
Sharkly는 Codex를 어떻게 사용하나요? 런타임으로 사용합니다. Codex를 실행하는 컴퓨터가 사용 가능으로 보고되면, 그 컴퓨터의 에이전트에 할당된 Task가 이를 통해 실행되며, 각 실행은 자체 격리 디렉터리나 워크트리에서 이루어집니다.
Sharkly Task 안에서도 서브에이전트를 쓸 수 있나요? 네. 런타임이 스스로 할 수 있는 모든 것은 실행 안에서도 그대로 작동합니다. Sharkly는 그 주변에 Task, 격리, 로그, 리뷰를 더합니다.
짧게 정리하면
설정은 실재하고 스니펫도 작동합니다. 다만 이것이 해 주지 않는 것은 동시 편집 64개를 안전하게 만들어 주는 일, 하나의 통합 응답을 리뷰 가능하게 만들어 주는 일, 어느 스레드가 당신을 기다리는지 알려 주는 일입니다. 바로 이 세 가지가 그 순서대로 무너집니다. 읽기 위주 팬아웃에는 서브에이전트를 쓰고, 쓰기 위주 병렬 작업은 각 실행이 자체 워크트리와 자체 리뷰어를 갖는 보드에 올리세요. Codex가 설치된 컴퓨터 하나를 연결하고, 에이전트 하나를 만들고, 별것 아닌 일을 하나 맡겨 보세요. 각 개념에 대한 더 자세한 설명은 문서에서 확인할 수 있습니다: docs.sharkly.ai.
