Codex GPT-5.6 Sol `collaboration.spawn_agent` 오류 우회: 멀티 에이전트를 끄지 않고 고치는 방법

특정 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.

처음에는 OMO(LazyCodex) 훅이나 Codex 설치가 꼬인 문제라고 생각했습니다. 하지만 재부팅, 훅 비활성화, 설정 일부 변경으로는 해결되지 않았습니다.

공개 이슈의 코드 분석과 A/B 테스트가 가리키는 가장 유력한 원인은 GPT-5.6 Sol이 예약한 collaboration.spawn_agent 스키마와, 영향을 받는 Codex 런타임이 같은 이름으로 등록한 MultiAgentV2 도구 스키마의 충돌입니다.

해당 환경에서는 멀티 에이전트를 끄거나 Codex를 재설치하는 대신, MultiAgentV2 도구의 네임스페이스를 collaboration에서 agents로 바꾸는 우회책이 동작했습니다.

핵심 우회책: ~/.codex/config.toml의 기존 [features.multi_agent_v2] 설정에 tool_namespace = "agents"를 추가한 뒤 새 작업에서 확인합니다. 반영되지 않을 때만 Codex를 재시작합니다.

주의: tool_namespace는 2026년 7월 10일 기준 공식 Configuration Reference 본문에 노출되지 않은 내부·실험적 설정입니다. 버전에 따라 무시되거나 거부될 수 있으므로 먼저 Codex 업데이트를 확인하고, 설정 파일을 백업한 뒤 적용하세요. 이 글은 아래 오류가 정확히 일치하는 영향받는 환경을 위한 임시 우회 방법입니다.

증상

해당 문제는 5.6 모델로 대화를 시작할 때 항상 아래 메시지가 뜨는 문제 였습니다.

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

 

이 문제의 특징은 다음과 같습니다.

• GPT-5.5 등 다른 모델은 정상 동작한다.
• gpt-5.6-sol을 선택하면 일반적인 질문도 즉시 실패한다.
• 프롬프트에서 서브 에이전트를 요청하지 않아도 같은 오류가 발생한다.
• 컴퓨터를 재부팅해도 해결되지 않는다.
• Codex나 OMO 훅을 의심하게 되지만, 훅만 꺼서는 해결되지 않을 수 있다.

이 오류와 공개 이슈의 분석을 종합하면, 프롬프트 처리 전에 요청에 포함된 도구 스키마를 검사하는 단계에서 실패한 것으로 보입니다.

원인

GPT-5.6 Sol에는 collaboration.spawn_agent라는 예약 도구가 있습니다. 공개 이슈 #31864의 분석에 따르면, 영향을 받는 Codex 구성에서는 MultiAgentV2도 자체적으로 만든 spawn_agent 도구를 collaboration 네임스페이스에 넣습니다.

즉, 요청에는 다음 이름의 도구가 실립니다.

collaboration.spawn_agent

이름은 GPT-5.6 Sol이 예약한 도구와 같지만 스키마는 정확히 일치하지 않아, 모델 추론이 시작되기 전에 요청이 거부된다는 것이 이 이슈의 설명입니다.

OpenAI의 openai/codex 저장소에 동일한 오류가 공개 이슈로 보고되어 있습니다. 이슈 작성자의 A/B 테스트에서는 네임스페이스를 agents로 바꾸자 완전한 도구 이름이 agents.spawn_agent로 변경되었고, 같은 요청이 정상 처리됐습니다. 다만 글 작성 시점에 이 이슈는 열린 상태이며, maintainer가 확정한 공식 원인 분석이나 영구 수정 공지는 아닙니다.

해결 방법

1. Codex 설정 파일 백업하기

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

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

OpenAI 공식 설정 문서에서도 사용자 전역 설정 위치를 ~/.codex/config.toml로 안내합니다.

단, CODEX_HOME을 별도로 지정했다면 실제 사용자 설정 위치가 달라질 수 있습니다. 선택한 profile 설정과 신뢰된 프로젝트의 .codex/config.toml도 전역 설정 위에 적용될 수 있으므로, 수정한 줄이 반영되지 않을 때는 아래의 "설정 계층 확인" 항목도 확인하세요.

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

2. tool_namespace 추가하기

먼저 설정 파일에서 multi_agent_v2가 어떤 형식으로 선언되어 있는지 확인합니다.

[features.multi_agent_v2] 블록이 이미 있는 경우

블록을 하나 더 만들지 말고 기존 블록 안에 tool_namespace 한 줄만 추가합니다. 예를 들어 기존 설정이 다음과 같다면,

[features.multi_agent_v2]
enabled = false
hide_spawn_agent_metadata = false

아래처럼 바꿉니다.

[features.multi_agent_v2]
enabled = false
hide_spawn_agent_metadata = false
tool_namespace = "agents"

multi_agent_v2 설정이 전혀 없는 경우

아래 블록을 한 번만 추가합니다.

[features.multi_agent_v2]
tool_namespace = "agents"

[features] 아래에 boolean으로 선언된 경우

기존 설정이 다음 형태라면 주의해야 합니다.

[features]
multi_agent_v2 = false

multi_agent_v2가 이미 boolean 값인데 [features.multi_agent_v2] 테이블을 추가하면, 같은 키를 값과 테이블로 중복 정의한 잘못된 TOML이 됩니다. 기존 multi_agent_v2 = false 줄을 제거하고 다음 table 형식으로 옮깁니다. [features] 아래의 다른 설정은 그대로 둡니다.

[features.multi_agent_v2]
enabled = false
tool_namespace = "agents"

TOML에서는 같은 [features.multi_agent_v2] 테이블을 두 번 선언하는 것도 일반적으로 파싱 오류가 납니다. 기존 boolean 선언과 중복 테이블을 모두 확인하세요.

3. 멀티 에이전트 설정은 그대로 두기

이 문제를 해결하려고 아래 설정을 false로 바꿀 필요는 없습니다.

[features]
multi_agent = true

공식 설정 문서의 features.multi_agent는 안정화된 멀티 에이전트 기능 플래그이며 현재 기본값도 true입니다. 반면 features.multi_agent_v2는 별도의 개발 중 기능과 세부 설정을 담는 테이블입니다.

공개 이슈의 분석에 따르면 GPT-5.6 Sol의 원격 모델 메타데이터가 로컬 플래그와 별개로 v2 도구 표면을 선택하는 영향받는 경로가 있습니다. 그래서 로컬 설정에 enabled = false가 있더라도 v2용 tool_namespace 변경이 효과를 낼 수 있습니다. 멀티 에이전트를 계속 사용하고 싶다면 기존 multi_agent 값과 multi_agent_v2.enabled 값은 유지하고, tool_namespace만 변경하는 것이 가장 작은 수정입니다.

features.multi_agent_v2.enabled를 무조건 true로 바꾸면 안 됩니다. 현재 Codex 소스에서는 agents.max_threads와 활성화된 MultiAgentV2를 함께 설정할 경우 구성 오류가 발생할 수 있습니다.

4. 새 작업에서 먼저 확인하고, 필요할 때만 재시작하기

설정 저장 후에는 현재 작업에서 바로 다시 시도하지 말고 다음 순서로 확인합니다.

1. 기존 작업이 아닌 새 작업을 만든다.
2. GPT-5.6 Sol을 선택하고 간단한 메시지를 보낸다.
3. 같은 오류가 계속되면 실행 중인 작업이 끝났는지 확인한 뒤 Codex Desktop의 모든 창을 닫는다.
4. Codex를 다시 실행해 새 작업에서 한 번 더 확인한다.
5. 앱을 닫아도 백그라운드 프로세스가 남아 있고 설정이 반영되지 않을 때만 해당 프로세스를 종료한다.

공개 이슈의 A/B 테스트도 새 작업에서 검증했습니다. 기존 작업은 시작할 때 선택된 런타임이나 도구 구성을 유지할 수 있으므로, 설정 반영 여부는 새 작업을 기준으로 판단하는 편이 안전합니다. 모든 창과 프로세스를 항상 강제 종료해야 한다는 뜻은 아닙니다.

CLI에서 바로 검증하는 방법

Codex CLI를 사용하는 경우, 설정 파일을 영구 수정하기 전에 다음 명령으로 네임스페이스 변경만 임시 적용해 볼 수 있습니다. 이 테스트는 현재 PATH에서 실행된 CLI만 검증하며 Codex Desktop을 검증하지는 않습니다.

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 CLI를 확인해야 합니다.

codex --version
where.exe codex

Windows에서는 Codex Desktop에 포함된 런타임과 npm으로 전역 설치한 codex 명령의 버전이 서로 다를 수 있습니다. codex --version과 where.exe codex는 터미널의 CLI 경로만 확인합니다. 결과가 여러 개라면 터미널 테스트가 구버전 CLI를 실행하고 있지 않은지 확인하고, Desktop 버전은 앱의 정보·업데이트 화면에서 별도로 확인하세요. CLI에서 성공했다고 Desktop까지 수정됐다고 단정하거나, npm CLI를 업데이트하면 Desktop도 함께 바뀐다고 가정하면 안 됩니다.

그래도 해결되지 않을 때 확인할 것

설정이 실제로 저장됐는지 확인

Windows PowerShell:

Select-String -Path "$env:USERPROFILE\.codex\config.toml" -Pattern 'multi_agent|tool_namespace'

macOS/Linux:

grep -nE 'multi_agent|tool_namespace' ~/.codex/config.toml

결과에 다음 줄이 보여야 합니다.

tool_namespace = "agents"

다만 문자열 검색은 주석 처리된 줄이나 실제로 적용되지 않는 설정 계층의 줄도 찾을 수 있습니다. 최종 검증은 Codex가 설정 파싱 오류 없이 시작되고, 새 작업에서 위의 정확한 오류가 사라지는지 확인하는 것입니다.

[features.multi_agent_v2] 블록이 중복되지 않았는지 확인

검색 결과에 [features.multi_agent_v2]가 두 번 이상 있다면 하나의 블록으로 합칩니다. 설정 파일 아래쪽에 같은 블록을 통째로 덧붙이는 실수가 흔합니다.

[features] 아래의 multi_agent_v2 = true 또는 multi_agent_v2 = false와 [features.multi_agent_v2] 블록이 동시에 존재하는지도 확인합니다. 둘 중 하나의 형식만 사용해야 합니다.

설정 계층 확인

전역 파일을 수정했는데도 반영되지 않는다면 다음을 함께 확인합니다.

• CODEX_HOME을 지정해 기본 경로와 다른 설정 파일을 사용하고 있지 않은지
• 선택한 profile의 *.config.toml에 다른 값이 있는지
• 신뢰된 프로젝트의 .codex/config.toml이 전역 설정을 덮어쓰고 있지 않은지

한 파일에서 tool_namespace 문자열을 찾았다는 사실만으로 그 값이 현재 작업에 실제 적용됐다고 판단할 수는 없습니다.

OMO/LazyCodex가 설정을 다시 썼는지 확인

OMO 또는 LazyCodex 설치·업데이트 과정에서 config.toml의 관리 블록이 다시 생성될 수 있습니다. 업데이트 후 문제가 재발했다면 tool_namespace = "agents" 줄이 사라지지 않았는지 먼저 확인하세요.

이 오류만 놓고 보면 OMO 훅 전체를 비활성화하는 것은 첫 번째 해결책이 아닙니다. 훅을 끄더라도 예약 네임스페이스 충돌이 남아 있으면 같은 오류가 계속 발생할 수 있습니다.

앱과 CLI를 구분해서 업데이트

• Codex Desktop에서만 발생한다면 앱 자체의 업데이트 여부를 확인합니다.
• 터미널에서만 발생한다면 codex --version과 실행 경로를 확인한 뒤 CLI를 업데이트합니다.
• 앱 재설치 전에 사용자 설정 파일을 먼저 확인합니다. 앱을 삭제해도 ~/.codex/config.toml이 남는 경우 같은 문제가 그대로 재현될 수 있습니다.

프록시나 비공식 모델 제공자를 사용 중인 경우

CLIProxyAPI 같은 별도 모델 제공 경로를 사용한다면 모델 등록 정보나 지원 버전 문제가 추가로 있을 수 있습니다. 이때 Unknown model, 인증 오류, 모델 목록 누락은 이번 collaboration.spawn_agent 스키마 충돌과 구분해서 진단해야 합니다.

효과가 없었거나 권장하지 않는 대응

컴퓨터 재부팅만 하기

잘못된 설정이 디스크에 그대로 남아 있으므로 재부팅만으로는 바뀌지 않습니다.

Codex부터 삭제하고 재설치하기

사용자 설정이 보존되면 같은 충돌도 보존됩니다. 먼저 config.toml을 확인하는 편이 빠릅니다.

multi_agent = false로 끄기

안정화된 멀티 에이전트 기능을 포기하게 될 뿐 아니라, 모델 메타데이터가 v2를 선택하는 영향받는 빌드에서는 이것만으로 오류가 사라진다고 보장할 수도 없습니다. 이 문제에는 네임스페이스만 바꾸는 더 작은 우회책이 있습니다.

features.multi_agent_v2.enabled = true를 무조건 강제하기

공개 이슈가 지목한 원인은 활성화 여부 자체가 아니라 도구 이름과 스키마의 충돌입니다. 또한 현재 Codex 소스에서는 agents.max_threads가 설정된 상태로 MultiAgentV2를 활성화하면 구성 오류가 발생할 수 있습니다.

OMO 훅을 전부 끄기

OMO가 설정을 생성하는 데 관여했을 수는 있지만, 정확한 오류 메시지는 collaboration.spawn_agent 예약 스키마 충돌을 가리킵니다. 먼저 tool_namespace를 수정한 뒤 플러그인 문제는 별도로 확인하는 것이 좋습니다.

왜 일반 질문까지 전부 실패했나

“서브 에이전트를 호출하지 않았는데 왜 spawn_agent 오류가 나지?”라는 의문이 들 수 있습니다.

Codex는 모델이 필요할 때 사용할 수 있도록 도구 정의를 요청에 함께 보냅니다. 서버는 실제로 그 도구를 호출할지와 관계없이 요청을 받는 시점에 도구 이름과 스키마를 검사합니다.

공개 이슈의 분석과 A/B 결과는 다음 실패 순서와 일치합니다.

1. Codex가 프롬프트와 도구 스키마를 함께 전송한다.
2. 서버가 collaboration.spawn_agent를 발견한다.
3. GPT-5.6 Sol용 예약 스키마와 Codex가 보낸 스키마가 다르다고 판단한다.
4. 모델 추론이 시작되기 전에 전체 요청을 거부한다.

tool_namespace = "agents"를 설정하면 도구 이름이 agents.spawn_agent로 바뀝니다. 예약 이름과 충돌하지 않게 될 뿐, MultiAgentV2 구현 자체나 멀티 에이전트 기능을 제거하는 것은 아닙니다.

정리

오류가 아래와 정확히 일치한다면,

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

영향받는 버전에서 가장 먼저 시도할 수 있는 우회책은 이것입니다.

[features.multi_agent_v2]
tool_namespace = "agents"

먼저 새 작업에서 GPT-5.6 Sol을 다시 선택해 확인하고, 반영되지 않을 때 Codex를 재시작한 뒤 새 작업에서 다시 시도합니다.

핵심만 다시 요약하면 다음과 같습니다.

• GPT-5.6 Sol 자체나 요금제 문제로 곧바로 단정할 증상이 아니다.
• 프롬프트 문제도 아니다.
• 멀티 에이전트를 끌 필요가 없다.
• OMO 훅 전체를 먼저 끌 필요도 없다.
• Codex 재설치 전에 config.toml을 확인한다.
• 영향을 받는 버전에서는 collaboration 대신 agents 네임스페이스를 사용하는 우회책이 동작했다.

참고 자료

• OpenAI Codex 이슈 #31864: GPT-5.6 Sol rejects every turn because MultiAgentV2 uses reserved collaboration.spawn_agent with a mismatched schema
• OpenAI Codex 공식 Configuration Reference
• LazyCodex 관련 이슈 #118
• 문제 발견에 참고한 커뮤니티 글

이 글은 2026년 7월 10일 기준 공개 이슈 #31864의 A/B 결과와 Windows에서 별도로 실행한 Codex CLI 0.144.0-alpha.4 검증을 바탕으로 작성했습니다. CLI 검증 결과는 Codex Desktop 내부 런타임까지 같은 버전과 동작임을 보장하지 않습니다. tool_namespace는 당시 공식 Configuration Reference 본문에 노출되지 않은 내부·실험적 설정이며, 이후 근본 수정이 배포되면 이 우회 설정이 더 이상 필요하지 않을 수 있습니다.

---

티스토리 태그 추천:

Codex, GPT-5.6, OpenAI, collaboration.spawn_agent, MultiAgentV2, LazyCodex, OMO, config.toml, Windows