티스토리 뷰

AI AX

Codex GPT-5.6 Sol [collaboration.spawn_agent] 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

RichLegend

Codex GPT-5.6 Sol `collaboration.spawn_agent` 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

GPT-5.6 Sol에서 일반 질문까지 실패하는 원인과 LazyCodex 업데이트, config.toml 우회 설정, CLI 검증 순서를 정리했습니다.

Codex에서 GPT-5.6 Sol을 선택한 뒤 평범한 인사나 질문을 입력했는데 아래 오류만 나오고 대화가 시작되지 않는 경우가 있습니다.

Invalid Value: 'tools'. Function 'collaboration.spawn_agent' is reserved for use by this model and must match the configured schema.

오류 문구에 spawn_agent가 들어가 있으니 멀티 에이전트 기능부터 꺼야 할 것처럼 보입니다. 하지만 영향을 받는 환경에서는 멀티 에이전트를 포기하지 않고도 문제를 해결할 수 있습니다.

2026년 7월 10일 현재 가장 먼저 확인할 것은 LazyCodex 또는 OMO의 버전입니다. LazyCodex v4.16.2에는 GPT-5.6 계열에서 문제가 될 수 있는 관리 설정을 자동으로 정리하는 수정이 포함됐습니다. 업데이트한 뒤에도 같은 오류가 정확히 반복될 때만 tool_namespace 우회 설정을 적용하는 순서가 안전합니다.

바쁜 분을 위한 해결 순서

오류 문구가 위 내용과 정확히 같은지 봅니다.
LazyCodex 또는 OMO를 사용한다면 v4.16.2 이상으로 업데이트합니다.
기존 대화가 아닌 새 작업에서 GPT-5.6 Sol을 다시 실행합니다.
오류가 남으면 config.toml을 백업하고 tool_namespace = "agents"를 추가합니다.
multi_agent = false나 multi_agent_v2.enabled = true부터 적용하지 않습니다.
Codex Desktop과 터미널의 Codex CLI는 따로 확인합니다.

일반 질문까지 막히는 이유

OpenAI Codex 이슈 #31864에 올라온 코드 분석과 A/B 테스트는 도구 이름과 스키마의 충돌을 원인으로 지목합니다.

GPT-5.6 Sol에는 collaboration.spawn_agent라는 예약 도구가 있습니다. 그런데 영향을 받는 Codex 런타임도 MultiAgentV2의 spawn_agent를 같은 collaboration 네임스페이스에 등록합니다. 이름은 같지만 스키마가 일치하지 않으면 서버가 요청을 거부합니다.

Codex는 질문만 보내지 않습니다. 모델이 필요할 때 쓸 수 있도록 도구 정의도 요청에 함께 넣습니다. 서버는 모델이 답변을 만들기 전에 이 정의부터 검사합니다. 서브 에이전트를 요청하지 않은 평범한 질문까지 실패하는 이유가 여기에 있습니다.

tool_namespace = "agents"를 설정하면 도구 이름이 collaboration.spawn_agent에서 agents.spawn_agent로 바뀝니다. 예약된 이름과 겹치지 않도록 이름표만 바꾸는 셈입니다. 멀티 에이전트를 삭제하거나 끄는 설정은 아닙니다.

다만 2026년 7월 10일 확인 시점에도 OpenAI Codex 이슈 #31864는 열려 있습니다. 이 글에서 설명하는 원인은 공개 이슈의 재현 결과를 토대로 한 유력한 분석이며, OpenAI 유지관리자가 확정한 영구 수정 공지는 아닙니다.

가장 먼저 LazyCodex를 업데이트합니다

LazyCodex 이슈 #118에는 v4.16.0이 세션 시작 때 넣던 [features.multi_agent_v2] enabled = false 관리 설정이 GPT-5.6 Sol과 충돌할 수 있다는 내용이 올라왔습니다.

이 문제는 LazyCodex v4.16.2에서 수정됐습니다. 업데이트된 가드는 GPT-5.6 계열에서 문제가 될 수 있는 관리 블록의 enabled = false, hide_spawn_agent_metadata = false, agents.max_threads를 정리합니다. 이후 Codex가 모델 정보에 맞춰 멀티 에이전트 버전을 선택하도록 둡니다.

설치 방식에 맞는 명령 하나를 사용합니다.

codex plugin marketplace upgrade sisyphuslabs

또는 최신 설치 프로그램을 실행합니다.

npx lazycodex-ai@latest install

LazyCodex 자동 업데이트에는 최대 24시간 간격이 있을 수 있습니다. 오류가 이미 발생했다면 수동 업데이트가 빠릅니다. 업데이트가 끝나면 새 작업을 만들고 GPT-5.6 Sol로 짧은 메시지를 보내 봅니다.

업데이트 후에도 같은 오류가 남는다면

새 작업에서도 정확히 같은 오류가 반복될 때만 설정 파일을 손봅니다. 수정 전 백업은 꼭 남겨 두세요.

사용자 전역 설정 파일의 기본 위치는 다음과 같습니다.

Windows: %USERPROFILE%\.codex\config.toml
macOS/Linux: ~/.codex/config.toml

CODEX_HOME을 별도로 지정했다면 실제 파일은 다른 경로에 있을 수 있습니다.

Windows PowerShell에서 백업

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$env:USERPROFILE\.codex" }
$path = Join-Path $codexHome "config.toml"
Copy-Item -LiteralPath $path -Destination "$path.bak.$(Get-Date -Format 'yyyyMMddHHmmss')"
notepad $path

macOS/Linux에서 백업

cp ~/.codex/config.toml ~/.codex/config.toml.bak
nano ~/.codex/config.toml

`tool_namespace` 한 줄 추가하기

설정 파일에 [features.multi_agent_v2] 블록이 없다면 다음 내용을 한 번만 추가합니다.

[features.multi_agent_v2]
tool_namespace = "agents"

같은 블록이 이미 있다면 새 블록을 만들지 말고 기존 블록 안에 아래 한 줄만 넣습니다.

tool_namespace = "agents"

OpenAI 공식 Configuration Reference가 연결하는 최신 config-schema.json에도 features.multi_agent_v2.tool_namespace 항목이 정의돼 있습니다. 다만 Codex 버전이나 모델 제공 경로가 다르면 결과도 달라질 수 있으므로 백업 후 적용하는 편이 안전합니다.

TOML 중복 선언은 피해야 합니다

다음처럼 [features] 아래에 multi_agent_v2가 불리언 값으로 들어 있는 상태에서 [features.multi_agent_v2] 테이블을 덧붙이면 잘못된 TOML이 됩니다.

[features]
multi_agent_v2 = false

multi_agent_v2를 값과 테이블로 동시에 선언할 수 없기 때문입니다. 오래된 LazyCodex가 만든 관리 설정이라면 먼저 v4.16.2 이상으로 업데이트하여 자동 정리를 실행하는 편이 낫습니다. 직접 넣은 설정이라면 백업한 뒤 기존 불리언 선언을 제거하고 테이블 형식 하나만 남깁니다.

[features.multi_agent_v2]
tool_namespace = "agents"

[features.multi_agent_v2] 블록 자체가 두 번 들어가 있어도 파싱 오류가 날 수 있습니다. 파일 맨 아래에 같은 블록을 통째로 붙이지 않았는지 확인하세요.

설정 저장 후에는 새 작업에서 확인하세요

기존 대화는 시작할 때 정해진 런타임이나 도구 구성을 유지할 수 있습니다. 설정이 반영됐는지는 새 작업을 기준으로 판단하는 편이 낫습니다.

새 Codex 작업을 만듭니다.
GPT-5.6 Sol을 선택합니다.
간단한 메시지를 보냅니다.
오류가 계속되면 Codex Desktop 창을 모두 닫고 다시 실행합니다.
새 작업에서 한 번 더 확인합니다.

앱을 닫았는데도 달라지지 않을 때만 백그라운드 프로세스가 남아 있는지 봅니다. 처음부터 모든 프로세스를 강제 종료할 필요는 없습니다.

CLI에서는 설정을 바꾸기 전에 시험할 수 있습니다

Codex CLI를 사용한다면 네임스페이스 변경을 일회성 옵션으로 먼저 확인해 볼 수 있습니다.

codex exec -m gpt-5.6-sol -c 'features.multi_agent_v2.tool_namespace="agents"' 'Reply exactly OK.'

정상 처리되면 결과에 OK가 나옵니다.

여기서 Unknown model gpt-5.6-sol이 표시된다면 이번 스키마 충돌과는 다른 문제입니다. CLI 버전, 계정별 모델 접근 권한, 모델 캐시, 모델 제공 경로를 따로 살펴봐야 합니다.

codex --version

Windows에서는 실제 실행되는 CLI 위치도 확인합니다.

where.exe codex

Codex Desktop에 포함된 런타임과 npm으로 설치한 Codex CLI의 버전은 다를 수 있습니다. CLI에서 성공했다고 Desktop까지 해결됐다고 단정하지 말고 두 환경을 나눠서 확인하세요.

그래도 안 될 때 보는 항목

[features.multi_agent_v2] 블록이 두 번 이상 있는지
[features]의 multi_agent_v2 = false와 [features.multi_agent_v2] 테이블이 함께 있는지
CODEX_HOME이 기본 경로와 다른 설정 파일을 가리키는지
선택한 프로필의 설정이 전역 설정을 덮어쓰는지
신뢰된 프로젝트의 .codex/config.toml에 다른 값이 있는지
LazyCodex 또는 OMO 업데이트 뒤 설정 파일이 다시 바뀌었는지
Desktop과 CLI 가운데 어느 쪽에서만 문제가 생기는지
프록시나 비공식 모델 제공자의 인증 오류, 모델 목록 누락, Unknown model이 섞여 있지 않은지

문자열 검색으로 tool_namespace = "agents"가 보인다고 해서 현재 작업에 그 설정이 적용됐다고 단정할 수는 없습니다. Codex가 설정 파싱 오류 없이 실행되고, 새 작업에서 해당 오류가 사라졌는지가 최종 기준입니다.

재부팅과 재설치부터 할 필요는 없습니다

컴퓨터를 재부팅해도 디스크에 저장된 설정은 그대로입니다. Codex를 삭제하고 다시 설치해도 ~/.codex/config.toml이 남으면 같은 문제가 이어질 수 있습니다.

multi_agent = false로 바꾸면 사용하려던 멀티 에이전트 기능까지 포기하게 됩니다. 영향을 받는 런타임에서 이 설정 하나로 충돌이 사라진다는 보장도 없습니다.

features.multi_agent_v2.enabled = true를 무조건 강제하는 것도 피하세요. 설정 조합에 따라 agents.max_threads와 충돌할 수 있습니다. OMO 훅 전체를 끄는 방법 역시 정확한 원인을 확인하기 전에는 범위가 너무 큽니다.

같은 오류가 반복된다면 LazyCodex 업데이트 → 새 작업 확인 → 설정 백업 → 네임스페이스 변경 순서로 접근하는 것이 낫습니다.

아래 오류가 GPT-5.6 Sol에서 모든 질문마다 반복된다면 프롬프트부터 고칠 문제는 아닐 가능성이 큽니다.

Invalid Value: 'tools'. Function 'collaboration.spawn_agent' is reserved for use by this model and must match the configured schema.

LazyCodex 또는 OMO 사용자라면 v4.16.2 이상으로 업데이트하고 새 작업에서 다시 확인하세요. 오류가 그대로 남을 때만 config.toml을 백업하고 다음 설정을 적용합니다.

[features.multi_agent_v2]
tool_namespace = "agents"

이 한 줄은 멀티 에이전트를 끄지 않습니다. 예약된 collaboration 이름과 겹치지 않도록 도구 네임스페이스만 바꿉니다. 업데이트부터 확인하면 불필요한 재설치나 기능 비활성화를 피할 수 있습니다.

참고 자료

원문 정리 참고: https://mekain80.tistory.com/325
OpenAI Codex 이슈 #31864: https://github.com/openai/codex/issues/31864
OpenAI Codex Configuration Reference: https://developers.openai.com/codex/config-reference
OpenAI Codex config schema: https://developers.openai.com/codex/config-schema.json
LazyCodex 이슈 #118: https://github.com/code-yeongyu/lazycodex/issues/118

부제목/미리보기: GPT-5.6 Sol에서 일반 질문까지 실패하는 collaboration.spawn_agent 오류의 원인과 LazyCodex v4.16.2 업데이트, config.toml 우회 설정, CLI 검증 순서를 정리했습니다.

태그: Codex, GPT-5.6 Sol, OpenAI Codex, collaboration.spawn_agent, MultiAgentV2, LazyCodex, OMO, config.toml, Codex 오류 해결, 멀티 에이전트

저작자표시 (새창열림)

Total

최근에 올라온 글

주현 - AX | Backend/Frontend Developer

티스토리 뷰