사용량 위키: 한도 초기화 시간과 토큰 절약

한도는 언제 초기화되고, 어떻게 하면 더 오래 쓸 수 있을까요? 주제별로 찾아보세요. Codex와 Claude를 따로 답하며, 공식 문서의 원문 인용과 링크를 함께 제공합니다.

서브에이전트가 토큰을 너무 많이 써요. 더 저렴한 모델은 어떻게 지정하나요?

Claude Code는 서브에이전트 파일 맨 위에 model: haiku를 적습니다. Codex는 ~/.codex/config.toml의 [agents] 아래에 default_subagent_model을 설정합니다. 서브에이전트는 저마다 같은 한도에서 따로 요청을 실행하므로, 검색이나 파일 읽기 같은 단순한 일은 작은 모델에 맡기는 것이 가장 저렴합니다.

Codex

~/.codex/config.toml의 [agents] 아래에 default_subagent_model을 설정하면 모든 서브에이전트가 기본으로 작은 모델을 씁니다.

설정하지 않으면 서브에이전트는 메인 세션의 모델과 추론 강도를 그대로 이어받습니다. config.toml의 [agents] 아래에 전체 기본값을 설정하거나, 특정 서브에이전트 하나에 .toml 파일을 따로 만들어 model과 model_reasoning_effort를 적으세요. 파일에 적은 값이 기본값보다 우선합니다. OpenAI는 검색, 큰 파일 읽기, 자료 처리에는 GPT-5.6 Terra를, 범위가 분명하고 반복적인 작업에는 GPT-5.6 Luna를 권합니다. 동시에 몇 개까지 실행할지 제한하려면 [agents] 아래에 max_concurrent_threads_per_session을 설정하세요.

공식 문서 원문

Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.
OpenAI docs · Subagents
If you don't configure a subagent model or model_reasoning_effort, the subagent inherits the parent agent's model and reasoning effort.
OpenAI docs · Subagents
To balance intelligence, speed, and price for each task, request a specific model or reasoning effort in your prompt, configure [agents] defaults in config.toml, or set model and model_reasoning_effort directly in the custom agent file.
OpenAI docs · Subagents
Use gpt-5.6-terra when you want a faster, lower-cost option for lighter subagent work.
OpenAI docs · Subagents
If a custom agent file sets model or model_reasoning_effort, the value in the file takes precedence.
OpenAI docs · Subagents

Claude

서브에이전트 파일 맨 위에 model: haiku를 적으세요. 한꺼번에 바꾸려면 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL을 설정합니다.

/usage 패널이 이유를 알려 줍니다. "Each subagent runs its own requests. Be deliberate about spawning them — and consider configuring a cheaper model for simpler subagents."(서브에이전트는 저마다 따로 요청을 실행합니다. 신중하게 띄우고, 단순한 서브에이전트에는 더 저렴한 모델을 지정해 보세요.) 서브에이전트 파일은 .claude/agents/(현재 프로젝트) 또는 ~/.claude/agents/(모든 프로젝트)에 있습니다. 파일 맨 위의 model 필드에는 haiku, sonnet, opus, fable, 전체 모델 ID, inherit를 쓸 수 있고, 적지 않으면 메인 세션의 모델을 씁니다. CLAUDE_CODE_SUBAGENT_MODEL은 모든 서브에이전트의 기본값을 정하지만 어디까지나 기본값입니다. 파일에 적힌 모델이나 Claude가 작업을 맡기면서 지정한 모델이 우선합니다. 서브에이전트가 실행되는 동안 /tasks를 입력하면 실제로 어떤 모델을 쓰는지 볼 수 있습니다.

공식 문서 원문

For simple subagent tasks, specify model: haiku in your subagent configuration.
Claude Code docs · Manage costs effectively
CLAUDE_CODE_SUBAGENT_MODEL is a default, so a subagent's definition or a model Claude passes still takes precedence over it. To apply one model to every subagent, teammate, and workflow agent, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1.
Claude Code docs · Create custom subagents
A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to keep exploration on a lower-cost model.
Claude Code docs · Create custom subagents
Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance.
Claude Code docs · Manage costs effectively
A single burst of heavy activity, such as a large workflow fanout, can exhaust the weekly allowance before the session window resets.
Claude Code docs · Error reference

Codex: 이렇게 적으세요

모든 서브에이전트의 기본값: ~/.codex/config.toml의 [agents] 아래에 default_subagent_model = "gpt-5.6-terra"와 default_subagent_reasoning_effort = "medium"을 추가합니다.

서브에이전트 하나만: .codex/agents/(현재 프로젝트) 또는 ~/.codex/agents/(모든 프로젝트)에 .toml 파일을 만듭니다. 필수 항목은 name, description, developer_instructions 세 가지입니다. 여기에 model과 model_reasoning_effort를 더합니다. 공식 예시 pr-explorer.toml은 name = "pr_explorer", model = "gpt-5.6-luna", model_reasoning_effort = "medium"으로 되어 있습니다.

우선순위: 서브에이전트를 띄울 때 지정한 모델, 그다음 [agents]의 기본값, 마지막이 메인 세션의 모델입니다. 에이전트 파일에 적은 값은 기본값보다 우선합니다.

Claude Code: 이렇게 적으세요

서브에이전트 하나만: .claude/agents/에 log-reader.md를 만듭니다. 맨 위 두 줄의 --- 사이에 세 줄을 적습니다. 첫째 줄은 name: log-reader, 둘째 줄은 description: Reads logs and runs tests, reports failures only(로그를 읽고 테스트를 실행해 실패한 항목만 보고한다는 뜻), 셋째 줄은 model: haiku입니다. 그 아래에 지시 사항을 적습니다. 예: Report only the failing tests and their errors. Do not paste the full output.(실패한 테스트와 오류만 보고하고 전체 출력은 붙여 넣지 말라는 뜻)

모든 서브에이전트: settings.json의 env 블록에 "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"를 추가합니다. 예외 없이 모든 서브에이전트에 적용하려면 "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"도 추가하세요(v2.1.257 이상 필요).

기본 제공 Explore만: Explore라는 같은 이름으로 서브에이전트를 직접 만들고 model: haiku를 적으세요. 기본 제공되는 것을 대체합니다.

우선순위: 작업을 맡길 때 지정한 모델, 그다음 서브에이전트 파일의 model, 그다음 CLAUDE_CODE_SUBAGENT_MODEL, 마지막이 메인 세션의 모델입니다.

흔한 오해

  • 서브에이전트에는 별도 한도가 있어서 여러 개를 병렬로 돌려도 메인 세션에는 영향이 없다

    별도 한도는 없습니다. 서브에이전트, 에이전트 팀, 클라우드 병렬 작업은 모두 같은 5시간 한도와 주간 한도에서 차감됩니다. 병렬로 돌리면 그 한도를 더 빨리 쓸 뿐입니다.

  • CLAUDE_CODE_SUBAGENT_MODEL을 설정하면 모든 서브에이전트가 작은 모델로 바뀐다

    꼭 그렇지는 않습니다. 이 값은 기본값일 뿐입니다. 서브에이전트 파일에 적힌 모델이나 Claude가 작업을 맡기면서 지정한 모델이 우선하고, 기본 제공되는 Explore와 Plan도 영향을 받지 않습니다. 전부 강제하려면 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1도 설정한 다음 /tasks로 확인하세요.

  • 일을 서브에이전트에 맡기면 토큰이 절약된다

    꼭 그렇지는 않습니다. 서브에이전트가 절약해 주는 것은 메인 세션의 컨텍스트입니다. 긴 출력은 서브에이전트 쪽에 남고 메인 세션은 요약만 받습니다. 하지만 서브에이전트는 배경을 처음부터 다시 읽어야 해서 전체 토큰은 오히려 더 많은 경우가 흔합니다. 출력이 길고 지저분한 일(테스트 실행, 문서 가져오기, 로그 읽기)을 맡기되, 작은 모델을 써야 이득이 됩니다.

팁

  • 가장 자주 돌리는 서브에이전트부터 바꾸세요. Claude Code의 /usage는 어느 서브에이전트가 가장 많이 쓰는지 보여 주며, 그것을 바꾸는 것이 효과가 가장 빠릅니다.
  • 검색, 파일 읽기, 테스트 실행, 로그 읽기는 작은 모델에 맡기세요. 판단이 필요한 일(아키텍처, 어려운 버그)은 메인 세션의 모델에 남겨 두세요.
  • 덜 띄우세요. Claude의 에이전트 팀은 일반 세션의 약 7배 토큰을 쓰며, 대규모 병렬 실행 한 번이면 5시간 한도가 리셋되기도 전에 주간 한도를 다 써 버릴 수 있습니다.
  • 일을 맡길 때는 범위와 돌려받을 내용을 분명히 적으세요. 예: "실패한 테스트와 오류만 보고해 줘". 자주 돌리는 서브에이전트에 대해 /usage 패널이 권하는 것도 바로 이것입니다. 더 작은 모델을 쓰거나 프롬프트를 더 좁히라는 것입니다.
  • 다 쓰면 종료하세요. 종료하지 않은 teammate는 계속 토큰을 씁니다.
  • Codex에서는 프롬프트에 모델을 직접 적어도 됩니다. 예: "이 서브에이전트는 gpt-5.6-terra, medium으로 돌려 줘". 띄울 때 지정한 모델이 기본값보다 우선합니다.
  • Claude Code의 서브에이전트는 effort(low, medium, high 등)도 따로 설정할 수 있으며, model과 같은 위치에 적습니다.

Codex 리셋 발표 기록 · Claude 리셋 발표 기록