메인은 GPT-5.6, 서브에이전트는 DeepSeek V4 Flash로 설정하기

GPT-5.6은 감독하고, DeepSeek V4 Flash 서브에이전트가 작업하는 Codex 구성법

이 구성에서 실제 일은 deepseek_v4_flash 자식이 합니다. 자식은 요청을 받아 파일을 조사하고, 필요한 코드를 바꾸고, 관련 검증까지 수행합니다. 메인 GPT-5.6은 같은 결과물을 다시 작성하지 않고 작업 범위·변경 내역·검증 근거를 확인한 뒤 승인하거나 보완 작업만 지시합니다.

이 글은 Codex의 메인을 GPT-5.6으로 유지하면서, deepseek_v4_flash라는 전용 자식 worker가 DeepSeek V4 Flash로 작업을 소유하게 만드는 방법을 다룹니다. 부모는 조율자와 최종 검토자이고, 자식은 실행자입니다.

핵심은 API 키를 에이전트 파일마다 복사하지 않는 것입니다. 키는 provider에 한 번만 연결하고, 서브에이전트는 그 provider를 명시적으로 선택합니다. Codex는 커스텀 provider와 커스텀 에이전트 파일을 지원합니다. Codex 설정 레퍼런스, 서브에이전트 문서

이 글의 예시는 macOS/Linux 기준입니다. API 키를 문서, Git 저장소, 스크린샷, 채팅 로그에 남기지 마세요. 이미 노출된 키라면 먼저 폐기하고 새 키를 발급받는 편이 안전합니다.

먼저 확인할 것

이 구성에는 다음이 필요합니다.

• 최신 Codex
• ChatGPT 또는 OpenAI 인증으로 동작하는 GPT-5.6 메인 모델
• DeepSeek API 키와 사용 가능한 잔액/권한
• deepseek-v4-flash 모델 접근 권한

DeepSeek의 현재 모델 ID와 기본 API URL은 공식 모델 문서에서 확인하는 편이 좋습니다. 모델 이름이나 API 형식은 바뀔 수 있으므로, 다른 블로그의 값을 그대로 복사하기보다 공식 문서를 우선합니다. DeepSeek Models & Pricing

1. 설정부터 백업한다

provider 설정은 사용자 전역 설정에 들어가므로, 먼저 원본을 따로 보관합니다. 아래 명령은 삭제하거나 덮어쓰지 않고 복사본만 만듭니다.

mkdir -p ~/.codex/backups
backup_stamp="$(date +%Y%m%d-%H%M%S)"
backup_dir="$HOME/.codex/backups/before-deepseek-$backup_stamp"

mkdir -p "$backup_dir"
cp -p ~/.codex/config.toml "$backup_dir/config.toml"

if [ -d ~/.codex/agents ]; then
  ditto ~/.codex/agents "$backup_dir/agents"
fi

chmod -R go-rwx "$backup_dir"

config.toml에 토큰이 직접 들어 있을 가능성이 있다면 백업도 민감 정보입니다. 클라우드 드라이브나 Git에 올리지 말고, 소유자만 읽을 수 있도록 둡니다.

2. API 키는 provider에 한 번만 연결한다

~/.codex/config.toml의 기존 메인 모델 설정은 유지합니다. 그 아래에 DeepSeek provider만 추가합니다.

# 메인 모델은 기존 GPT-5.6/OpenAI 설정을 그대로 둡니다.
model = "gpt-5.6-sol"
model_provider = "openai"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"

env_key는 키 자체가 아니라 환경 변수의 이름입니다. Codex의 provider 설정은 환경 변수로 API 키를 받도록 지원하며, 직접 토큰을 TOML에 쓰는 방식보다 안전합니다. Codex provider 설정

macOS 데스크톱 앱이 키를 읽도록 하려면 현재 로그인 세션에 환경 변수를 설정한 뒤 Codex를 완전히 재시작합니다.

launchctl setenv DEEPSEEK_API_KEY "발급받은_키"

이 명령은 현재 로그인 세션을 위한 설정입니다. 영구 보관이 필요하다면 운영체제 키체인이나 조직의 비밀 관리 방식을 사용하면 됩니다. 셸 시작 파일에 실제 키를 평문으로 적는 방법은 피하는 것이 좋습니다.

3. 자식에게 실행권한을 주고, 부모는 감독만 하게 한다

agents.default_subagent_model만 바꾸면 모델 이름만 기본값으로 바뀌고 provider까지 안전하게 고정되지 않습니다. 메인 OpenAI provider로 DeepSeek 모델을 호출하는 실수를 피하려면, provider를 함께 지정한 커스텀 에이전트를 만듭니다.

~/.codex/agents/deepseek-v4-flash.toml 파일을 만듭니다.

name = "deepseek_v4_flash"
description = "Fast DeepSeek V4 Flash worker for bounded implementation, documentation, and verification tasks."
model = "deepseek-v4-flash"
model_provider = "deepseek"
sandbox_mode = "workspace-write"

developer_instructions = """
Own the bounded task delegated by the parent from inspection through
implementation and focused verification. Modify only files needed for the task,
preserve unrelated user changes, and never access or change credentials. Return
a concise summary of changed files, verification evidence, and any limitation.
"""

workspace-write는 자식에게 현재 작업공간 안에서 구현할 권한을 줍니다. 자식은 요청을 받아 구현과 검증을 마칠 때까지 작업을 소유하고, 부모는 결과가 요구사항과 맞는지 확인합니다. 자격 증명·전역 설정·배포 권한은 자식의 범위에서 제외하는 편이 좋습니다.

Codex는 ~/.codex/agents/ 아래의 각 TOML 파일을 커스텀 에이전트로 로드하며, 그 파일의 model 설정은 부모 설정보다 우선합니다. 커스텀 에이전트 설정 방식

4. 부모는 작업을 넘기고, 결과만 검토한다

Codex를 완전히 종료한 뒤 다시 엽니다. 부모에게는 다음처럼 역할을 분명히 요청합니다. 부모는 직접 파일을 고치지 않고, 자식이 작업한 결과와 검증 기록을 검토합니다.

deepseek_v4_flash 자식에게 이 작업을 전부 맡겨 주세요.
자식이 관련 파일을 조사하고 구현한 뒤, 필요한 테스트를 실행해 결과를 보고하게 하세요.
부모는 파일을 직접 수정하지 말고 변경 파일, 테스트 결과, 요구사항 충족 여부만 검토해 승인 또는 보완 사항을 알려 주세요.

자식에게 원래 사용자 요청 또는 그 요청을 정확히 요약한 작업 지시가 전달돼야 합니다. 부모가 결과물을 대신 쓸 필요는 없지만, 자식이 무엇을 완성해야 하는지 알 수 있어야 하기 때문입니다.

부모가 확인할 항목은 세 가지면 충분합니다.

• 자식이 수정한 파일이 작업 범위 안에 있는가
• 자식이 실행한 검증이 변경 내용과 맞는가
• 결과가 사용자의 요청을 충족하는가

5. provider와 worker를 각각 검증한다

먼저 DeepSeek provider 자체를 확인합니다.

codex exec --strict-config --sandbox workspace-write \
  --model deepseek-v4-flash \
  --config 'model_provider="deepseek"' \
  'Create a small Markdown file, read it back, and report the title and line count.'

성공 기준은 자식이 파일을 만들고, 스스로 읽어 확인한 결과를 반환하는 것입니다. 이후 부모가 같은 파일을 읽어 제목·줄 수·변경 범위를 독립적으로 확인하면 작성과 감독이 분리됩니다.

커스텀 에이전트를 통한 자동 위임은 Codex 버전과 실행 환경에 따라 작업 본문 전달이 실패할 수 있습니다. 실제 업무에 쓰기 전에 반드시 자식이 전달받은 작업을 자신의 말로 요약하고, 해당 파일을 실제로 수정·검증했는지 확인하세요. 작업 지시가 비어 있다면 provider 문제가 아니라 handoff 문제이므로, 성공한 것처럼 다음 단계로 넘어가면 안 됩니다.

6. 문제가 생기면 원본으로 되돌린다

테스트가 실패했거나 메인 모델 선택이 달라졌다면, Codex를 종료한 상태에서 백업본의 config.toml과 agents 폴더를 복원합니다. 복원 전 현재 파일도 별도로 복사해 두면 원인을 비교할 수 있습니다.

복원 후에는 codex doctor로 다음 두 가지를 확인합니다.

• config.toml parse ok
• 메인 모델이 의도한 GPT-5.6과 openai provider로 표시되는지

DeepSeek 모델을 못 찾는다는 메타데이터 경고가 나올 수 있습니다. 호출이 성공하더라도 복잡한 도구 사용이나 장기 작업에서 동작이 달라질 수 있으므로, 처음에는 작은 기능 하나처럼 검증 범위가 분명한 작업부터 맡기는 편이 안전합니다.

어떤 작업을 DeepSeek 서브에이전트에 맡길까

DeepSeek 자식이 소유할 작업	GPT-5.6 부모가 관리할 작업
관련 코드 조사, 구현, 단위·통합 테스트	요구사항을 작업 단위로 나누기
문서 작성과 코드 정리	변경 범위와 사용자 의도 대조
오류 재현, 원인 분석, 수정안 적용	테스트 근거와 회귀 위험 검토
반복되는 기능 작업	보안·배포·데이터 변경의 최종 승인

부모가 자식의 결과를 다시 구현하면 분업의 이점이 사라집니다. 부모는 결과를 믿는 것이 아니라, 변경 파일과 검증 근거를 살펴 결과를 판정합니다. 이 역할 분리가 비용을 줄이면서도 품질을 통제하는 핵심입니다.

마무리

이 구성의 목표는 GPT-5.6을 구현자로 쓰는 것이 아닙니다. GPT-5.6은 맥락·우선순위·최종 책임을 유지하고, DeepSeek V4 Flash 자식은 실제 작업과 검증을 끝까지 수행합니다. provider에는 키를 한 번만 연결하고, 에이전트 파일에는 worker의 역할·모델·권한만 남기면 관리와 복구가 단순해집니다.