상주 컨텍스트 비용
세션이 보내는 모든 요청은 대화 이전에 동일한 접두사를 전달합니다. 시스템 프롬프트, 선언된 모든 도구의 스키마, 컨텍스트(QWEN.md) 파일, 그리고 skill 목록이 그것입니다. 이 접두사에 대한 비용을 모든 턴에서 지불하며, 단순히 질문에 답하는 턴에서도 마찬가지입니다. 이 페이지는 이를 측정하고 줄이는 방법에 대해 다룹니다.
토큰 캐싱은 접두사의 _가격_을 낮춥니다. 이 페이지는 _접두사 자체_를 줄입니다. 둘은 함께 작동합니다 — 더 작은 접두사는 캐싱되었을 때 역시 더 저렴합니다.
무엇을 위해 비용을 지불하는지 확인하기
/context detail/context는 카테고리별 분석을 출력합니다. detail은 항목별 행을 추가합니다 — 각 내장 도구, 각 MCP 도구, 각 컨텍스트 파일, 각 나열된 skill — 어떤 단일 항목이 비용이 많이 드는지 확인할 수 있습니다. 세션의 첫 번째 턴에서 읽어보세요. 대화가 아직 비어 있고 보이는 모든 것이 접두사인 상태입니다.
카테고리는 /context가 보고하는 항목에 두 가지 계산 행을 더한 것입니다: startupContext(첫 번째 사용자 턴으로 전송되는 환경 블록)와 카테고리가 할당하지 않는 나머지에 대한 명시적 잔차로, 부분들이 항상 합계와 일치합니다.
창의 백분율이 아닌 유휴 비용 사용하기
컨텍스트 창의 백분율은 유지할 수 있는 목표가 아닙니다. 분모가 임의적이기 때문입니다. 동일한 구성이 1M 컨텍스트 모델에서는 6.5%로, 128k 모델에서는 37%로 표시됩니다 — 동일한 텍스트, 동일한 비용인데 숫자만 크게 다릅니다. 대신 다음을 사용하세요:
유휴 비용 — 하나의 질문을 하고 도구를 호출하지 않는 세션의 입력 토큰.
이것은 모델과 창에 독립적이며, 도구 스키마에서 컨텍스트 파일로 텍스트를 옮겨서 숫자를 좋게 보이게 할 수 없습니다. 또 다른 유용한 측정값은 대화가 접두사를 따라잡는 데 몇 턴이 걸리는지입니다: 압축 비용을 상각하는 데 20턴이 걸리는 접두사는 5턴 세션에서는 결코 상각되지 않습니다.
레버, 효과 순서
1. 사용하지 않는 기능 끄기
모델에 선언된 각 도구는 모든 요청에 해당 스키마를 추가합니다. 따라서 상주 도구가 큰 선택적 기능을 끄면 요청 토큰을 절약할 수 있습니다. 반면 지연 도구는 짧은 카탈로그 항목만 기여하며, 실제 발견이나 호출 시점의 비용만 부담합니다. 기능을 비활성화하면 서브에이전트에서도 해당 도구가 제거되지만, 다음 레버가 항상 그렇게 하지는 않습니다.
2. 지연 도구 표면을 실제로 사용하는 것으로 유지하기
tools.eager는 초기 요청에 스키마가 유지되는 내장 도구의 허용 목록입니다. 나머지는 모두 **지연(deferred)**됩니다: 여전히 등록되어 있고, /tools에 나열되며, 호출 가능합니다 — 모델이 실제로 필요할 때 tool_search로 로드합니다.
{
"tools": {
"eager": [
"read_file",
"write_file",
"edit",
"glob",
"grep_search",
"run_shell_command",
"skill",
],
},
}허용 목록을 올바른 기준선과 비교하여 측정하세요. 자체 기본값으로 온디맨드인 도구는 이미 첫 요청에 없으며, tools.toolSearch.threshold가 기본값 0으로 설정된 이후로는 아무것도 이를 미리 로드하지 않으므로, 허용 목록이 절약하는 것은 보류하는 eager-by-default 도구들의 스키마뿐입니다 — 전체 내장 표면이 아닙니다. 목록에 숫자를 할당하기 전에 실제로 실행하는 버전에서 /context를 새로 읽어보세요.
사용하기 전에 알아야 할 네 가지:
- 비활성화가 아닙니다. 강등된 도구는 여전히 도달 가능합니다. 도구를 제거하려는 의도였다면 전체 도구
permissions.deny규칙이나tools.disabled를 사용하세요. - 일부 도구는 제외됩니다 그리고 목록의 내용과 관계없이 정상적인 로드 동작을 유지합니다:
tool_search와tool_call(보류된 도구에 도달하는 브리지의 두 절반),structured_output, 계획 모드 수명 주기 도구(enter_plan_mode,exit_plan_mode,ask_user_question),task_stop, MCP 도구(mcp__*), 그리고 Computer Use 도구(computer_use__*).task_stop과 Computer Use 패밀리는 기본적으로 온디맨드이므로 이들을 게이팅해도 절약되는 것이 없습니다. MCP 도구는tools.toolSearch.*와 서버별includeTools/excludeTools필터에 의해 관리되며,tools.eager의 어떤 것으로도 나머지를 제거할 수 없습니다: 전체 도구permissions.deny규칙,tools.disabled항목, 또는--exclude-tools가 필요합니다. 브리지 쌍의 경우tools.toolSearch.enabled: false가 두 절반을 한 번에 제거합니다. 브리지 절반을 제거하는 것이 허용 목록에서 벗어나는 중립적인 방법은 아닙니다: 모든 일반 지연 도구(모든 MCP 도구, 지연 Computer Use 패밀리)가 그때 모든 요청에 강제 선언되지만, 보류된 도구는 모델에 제공되지 않으며 브리지를 통해 다시 로드할 수 없습니다 — 여전히 등록되어 있으므로 이름으로의 직접 호출은 여전히 정상 승인을 거칩니다. permissions.allow은 절약되지 않습니다. 이것은 순수한 자동 승인입니다: 도구를 강등, 숨김, 제거하지 않습니다. 승인 모드도 마찬가지입니다.- 브리지의 두 절반 모두 필요합니다. 보류된 도구는
tool_search로 검토되고tool_call을 통해 호출됩니다.tool_searchalone는 호출할 수 없는 스키마를 읽을 수 있습니다. 둘 중 하나가 등록 해제된 경우 —tools.toolSearch.enabled: false는 둘 다 거부합니다.tool_search/tool_call거부 규칙,--exclude-tools항목, 또는tools.disabled항목이 하나를 제거합니다 — 허용 목록은 여전히 스키마를 보류하지만 아무것도 다시 로드할 수 없으며, 강등된 도구는 해당 세션에서 모델에 제공되지 않습니다(경고가 기록됨). 여전히 등록되어 있으므로 이름으로의 직접 호출은 여전히 정상 승인을 거칩니다. 일반 지연 도구는 그 경우 eager하게 선언되는 것으로 폴백합니다.tools.eager로 강등한 도구는 그렇지 않습니다.
tools.visible은 기본적으로 지연되더라도 미리 선언하고 싶은 하나의 도구를 위한 탈출구입니다.
Agent 및 Goal 조정(agent, list_agents, get_goal, update_goal, propose_goal)은 기본적으로 지연됩니다. tools.eager 구성은 필요하지 않습니다. 모델은 전체 스키마 대신 짧은 발견 항목을 봅니다. 이들의 첫 사용은 브리지를 통한 발견이 필요하므로, 전체 작업 비용과 성공적인 위임/Goal 완료를 첫 요청과 함께 비교하세요. 이들은 일반 지연 도구입니다. tools.visible, 미리 로드, 그리고 위에서 설명한 불완전 브리지 eager 폴백이 여전히 적용됩니다. 미리 로드는 전체 지연 후보 풀에 대해 모두 또는 전혀 방식이며, 이 다섯 선언은 크므로, 세션 시작 시 모든 지연 도구를 공개하던 tools.toolSearch.threshold가 이제 이 중 어느 것도 공개하지 않을 수 있습니다. 둘 중 하나를 변경한 후 /context를 다시 읽어보세요.
3. 시나리오 가이드를 컨텍스트 파일에서 skill로 옮기기
컨텍스트 파일은 해당 파일이 적용되는 모든 세션의 모든 요청에 관련성 게이팅 없이 연결됩니다. skill은 이름과 설명만 나열됩니다 — 측정된 샘플에서 84개의 skill은 평균 약 55토큰씩이었습니다 — 그리고 호출될 때 본문이 로드되며, paths:로 게이팅된 skill은 일치하는 파일이 건드려질 때까지 나열조차 되지 않습니다.
컨텍스트 파일에는 항상 참인 것만 유지하세요 — 정체성, 어휘, 하드 제약 — 그리고 “X를 할 때 Y를 하라”는 skill 또는 paths: 게이팅 규칙에 넣으세요. /context detail은 각 컨텍스트 파일의 이름을 표시하며, extension의 파일인 경우 해당 extension의 이름을 표시합니다.
4. 시스템 프롬프트, 마지막에
기본 프롬프트는 이미 상주 카테고리 중 가장 작으며, 그 중 약 3분의 1은 편집하면 안 되는 안전 및 권한 텍스트입니다. 게이팅된 도구 가이드는 선언된 집합을 따르며, 브리지로 도달 가능한 Agent에 대한 예외가 있습니다. 해당 항목이 이름하는 다른 도구들은 여전히 선언이 필요합니다. 따라서 도구 표면을 줄이면 해당 가이드도 축소될 수 있습니다. --system-prompt로 전체를 교체하는 것이 가능하며 이 페이지에서 가장 위험도가 높은 변경입니다. 만약 한다면, 모든 업그레이드에서 업스트림 프롬프트를 diff하세요.
함정
- 서브에이전트도 지연 도구를 받습니다. 명시적 도구 목록을 선언하지 않는 서브에이전트는 등록된 모든 도구의 스키마를 지연 도구를 포함해 수신하며, ToolSearch를 거치지 않습니다.
tools.eager와permissions.deny만이 여기에 도달하는 유일한 조절 수단이며, 프리로드 임계값은 그렇지 않습니다. - 백그라운드 메모리 에이전트는 전체 도구 목록이 필요하며, 두 목록이 다릅니다. 프로젝트 Dream 워커는 여섯 개의 도구(
read_file,grep_search,glob,run_shell_command,write_file,edit)가 필요합니다. 자동 추출은 다섯 개가 필요합니다 —run_shell_command를 제외한 동일한 집합이며, 이는 설계상 거부합니다. 실제로 보유하는 도구를 거부하면 오류 대신 조용히 성능이 저하됩니다. 따라서 선언을 제거하려고run_shell_command를 전역적으로 거부하지 마세요. Dream은 여전히 이것이 필요합니다. - 토큰은 사라지지 않고 이동할 수 있습니다.
grep_search와glob을 제거하면 모델이 셸을 통해grep과find를 사용할 수 있으며, 그 출력은 대화에 포함됩니다. 새 출력은 처음 전송될 때 입력 토큰을 추가하며, 이를 포함하는 변경되지 않은 역사는 이후 요청에서 제공자의 접두사 캐시에 도달할 수 있습니다. 변경을 접두사만이 아닌 작업당 총 입력 토큰, 제공자가 보고한 캐시된 및 캐시되지 않은 입력, 그리고 실제 청구서로 판단하세요. - 재개된 세션은 필요한 것을 다시 전송합니다. 강등된 도구가 재개된 세션의 역사에 나타나면 스키마가 자동으로 복원됩니다. 거부된 도구는 그렇지 않습니다.
- 보류된 도구에 도달하는 것이 더 이상 접두사를 다시 작성하지 않습니다 — 하지만 예전에는 그랬고, 오래된 조언은 그렇다고 가정합니다. 발견은
tool_search→tool_call브리지를 통해 이루어지며, 이는 선언된 도구 목록을 바이트 단위로 안정적으로 유지하므로, 프롬프트 캐시 접두사는 세션 중간 발견에서도 생존합니다. 비용은 보류된 도구의 첫 사용 전 추가 라운드 트립 한 번입니다. 이것이tools.toolSearch.threshold가 이제 기본값0인 이유입니다: 매 턴 지연 집합을 유지하는 것이 더 이상 더 저렴한 쪽이 아닙니다. 임계값을 올리는 것은 일반 지연 도구(MCP 도구와 온디맨드 내장 도구)를 확실히 필요로 할 세션에서 해당 라운드 트립을 되찾기 위해서만입니다.tools.eager로 강등한 도구는 절대 미리 로드하지 않습니다. 어떤 임계값에서도 브리지 뒤에 남습니다. 미리 로드는 세션 시작 시 실행되며, MCP 서버는 보통 그 이후에 연결되므로, 새 출시는 임계값과 관계없이 MCP 도구를 선언하지 않습니다. 다음 세션 시작(CLI에서/clear이후) 또는QWEN_CODE_LEGACY_MCP_BLOCKING=1에서 즉시 미리 로드에 도달합니다. - 접두사 캐싱 모델은 트레이드를 반전시켰습니다. 지연에 대해서는 더 이상 그렇지 않습니다. 할인이 변경되지 않은 접두사에 의존하는 모델의 경우, 선언 목록을 동일하게 유지하는 것이 작게 유지하는 것보다 더 중요했던 적이 있습니다 — 이것이 일부 배포가 ToolSearch를 수동으로 비활성화한 이유입니다. 보류된 도구에 도달하는 것이 이제 해당 목록을 바이트 단위로 안정적으로 유지하므로, 그 특정 이유는 만료되었습니다 — 단 하나의 예외가 있으며, 이는
tool_search설명 자체에 명시되어 있습니다: 도구 집합 새로 고침이 활성 역사에 직접 호출이 있을 때 보류된 도구를 다시 선언할 수 있으며, 이는 접두사를 이동시킵니다. 접두사 안정성은 여전히 세션 중간에 접두사를 다시 작성하는 다른 것(예: 턴 사이 컨텍스트 파일 편집)에 반대하는 논거입니다. - 범위가 유출됩니다. 설정은 이를 읽는 모든 클라이언트(CLI, Web Shell, serve)에 적용되므로, 배포별 도구 표면에는 자체 설정 범위가 필요합니다.
절약 확인하기
- 변경 전 유휴 비용을 기록합니다: 새 세션, 간단한 질문 하나, 첫 번째 턴에서
/context. - 한 번에 하나의 레버를 적용하고 반복합니다. 세션을 재시작하세요 — 이러한 설정의 대부분은 시작 시 읽힙니다.
- 자체 작업 세트에서 기능이 유지되었는지 확인합니다: 도구 호출 성공률,
tool_search가 호출되는 빈도, 그리고 작업 결과. 모델이 찾지 않는 강등된 도구는 크게 실패하지 않습니다. 그냥 사용되지 않을 뿐입니다. - 접두사뿐만 아니라 청구서를 확인하세요 — 토큰이 대화로 이동하는 것에 대한 함정을 참조하세요.