IronClaw 컨텍스트 예산 초과: 네 가지 오류, 하나의 하드코딩된 숫자

IronClaw에서 "Context budget exceeded"는 하나의 오류가 아닙니다. 서로 다른 네 가지 오류 변형이 해당 문구를 포함하며, 그 어느 것도 모델의 컨텍스트 윈도우가 아니고, 어떤 구성 파일, 환경 변수 또는 CLI 플래그도 그 배후의 수치를 변경하지 않습니다. 예산은 컴파일된 128,000토큰과 20,000토큰 예약분이며, 이를 압박하는 세 경로인 identity 파일, 스킬 스니펫 및 도구 스키마는 해당 허용량 위에 조립됩니다. 이는 이 페이지의 이론이 아니라 IronClaw 자체의 공개 결함 보고서에 명시된 내용입니다.

이름이 혼동될 수 있으므로 한 가지를 구분하겠습니다. 여기서 말하는 것은 NEAR AI의 Rust 에이전트 런타임인 github.com/nearai/ironclaw입니다. 해당 단어의 상업적 검색 결과를 압도하는 Corsair 게이밍 마우스도 아니고, 에이전트 소프트웨어를 판매하며 자신을 OpenClaw와 비교하기도 하는 관련 없는 ironclaw.tech 회사도 아닙니다. IronClaw와 OpenClaw 비교에서 이 차이를 자세히 설명합니다. 아래의 모든 소스 수준 수치는 2026년 9월 21일 GitHub contents API를 통해 2026년 9월 10일 커밋된 main의 커밋 b0b999d에서 확인했습니다. 해당 커밋은 2026년 8월 28일 게시된 ironclaw-v1.4.0 릴리스 태그보다 이후입니다. 2026년 10월 1일에는 더 최신인 ironclaw-v1.4.1 릴리스 바이너리(2026년 9월 29일 게시, Google OAuth 및 Wasmtime에 대한 패치이며 릴리스 노트에 예산 변경은 없음)를 로컬 테스트 엔드포인트에서 실행했습니다. 실행 결과는 아래에 기록되어 있으며 해당 버전에 한정되고, 소스 수치는 커밋에 한정됩니다.

어떤 "context budget exceeded"를 보고 있는지

이는 Rust thiserror 표시 문자열이며, 로그와 오류 세부 정보에 표시되는 내용입니다. 정확한 문구를 읽으면 어느 경로에서 실패했는지 알 수 있습니다.

실제 모델 오버플로에 대해 사용자가 보는 내용에는 이러한 단어가 전혀 없습니다. 호스트가 작성한 실패 투영 문장은 고정된 "The run failed because the model context was too large. Retry with a shorter request or start a new thread."이며, 모델 게이트웨이에서 매핑된 공급자 오류는 "model request exceeded its context budget"입니다. 두 가지 주의할 점이 있습니다. 이 페이지에서는 엔드투엔드 실행을 추적하지 않았으므로 스킬 경로의 실패가 궁극적으로 어떤 사용자 대상 문장으로 투영되는지는 확립되지 않았습니다. 또한 널리 반복되는 문자열인 "Model request context exceeds the available input budget"는 nearai/ironclaw 어디에도 나타나지 않습니다. 이는 다른 에이전트 프로젝트에 속하므로 이 프로젝트를 진단하는 데 사용해서는 안 됩니다.

구성할 수 없는 128,000

PromptContextTokenBudget는 세 가지 상수를 제공합니다. 128,000토큰의 컨텍스트 한도, 20,000토큰의 예약 공간, 그리고 0인 메인 루프 최대 출력 수치입니다. 표시되는 트랜스크립트 한도는 마지막 두 값 중 더 큰 값을 뺀 값이므로 108,000토큰입니다. 이는 파일에 기록된 리터럴 값이 아니라 기본값에서 계산한 결과입니다. 세 번째 항은 테스트 외부에서는 할당되지 않으므로 예약 공간은 항상 고정된 20,000입니다. 또한 저장소의 모든 비테스트 생성은 일반적인 PromptContextTokenBudget::default()뿐입니다. 압축 전략에 하나, 루프 드라이버 호스트의 TextOnlyLoopHostConfig 기본값에 하나가 있으며, 다른 숫자를 전달하는 모든 ::new(…) 호출은 #[cfg(test)] 모듈 안에 있습니다.

IronClaw 자체의 이슈 #5739 제목에 그대로 나와 있습니다. "모델의 context_length를 무시하는 유효 컨텍스트 예산이 하드코딩된 128K이며 구성 재정의가 없음". 이 이슈는 2026년 7월 6일부터 열려 있으며 2026년 9월 21일에도 여전히 열려 있었습니다. 여기서 세 가지 함정이 따릅니다.

• budget.* 키는 이것이 아닙니다. IronClaw의 구성 페이지는 "budget — cost controls"라는 제목의 섹션 아래 budget.user_daily_usd, budget.pause_at 및 관련 키를 문서화하며, 이를 에이전트 지출을 제한하는 설정으로 설명합니다. 이들은 금액 설정입니다. 그중 두 개(budget.overestimate_factor 및 budget.default_tz)는 달러 금액이 아니라 배수와 시간대입니다. 어떤 수준의 키도 컨텍스트 한도, 예약 공간, ID 한도 또는 스킬 예산을 설정하지 않으며, 공개된 우선순위 순서는 "컴파일된 기본값 < config.toml < 환경 변수 < CLI 플래그"입니다. 따라서 없는 키는 어디에도 없습니다.
• PR #5790은 잘못된 단서입니다. 제목은 "호스트 팩토리를 통한 프롬프트 컨텍스트 예산 재정의"를 제시합니다. API에는 2026년 8월 27일에 종료되었으며 merged: false라고 표시됩니다.
• 수정 사항은 모두 제안 단계입니다. 동일한 20,000 예약 공간을 유지하면서 모델이 광고하는 윈도우의 90%를 사용하도록 하는 #8053과 #7976 및 #5435는 확인 당시 모두 열려 있었습니다.

타사 엔드포인트에는 추가 단계가 있으며, 이것이 결정적입니다. ModelMetadata.context_length는 Option이고, LlmProvider 트레이트의 기본 구현은 None을 반환합니다. 즉, "기본값은 크기 정보 없이 모델 이름을 반환"합니다. 일반적인 OpenAI 호환 어댑터에는 재정의가 없으므로 이 기본값을 상속합니다. 따라서 사용자 지정 엔드포인트는 윈도우를 전혀 알리지 않습니다. 모델이 100만 토큰을 수용하든 32,000토큰을 수용하든 IronClaw는 108,000개의 트랜스크립트 토큰을 기준으로 계획하며, #8053은 이 경로에서 설정되지 않는 필드를 정확히 읽게 됩니다. 해당 엔드포인트를 구성하는 방법은 IronClaw 사용자 지정 API 설정을 참조하세요. 이 페이지에서는 예산에 집중합니다.

예산을 건드리지 않고 프롬프트를 채우는 레인

IronClaw의 개선 이슈 #8057은 2026년 9월 3일에 등록되었고 확인 당시에도 열려 있었으며, 공급업체가 직접 사용한 표현으로 메커니즘을 설명합니다. 프롬프트 예산은 "트랜스크립트의 크기만 산정"하고, 정체성 콘텐츠, 스킬 및 메모리 스니펫, 채널 컨텍스트와 도구 스키마는 "트랜스크립트 허용량을 줄이지 않은 채 그 위에 추가되므로, 공급자가 받는 요청이 루프가 준수한다고 여기는 예산을 초과할 수 있습니다." 이는 출시된 동작에 대한 문서가 아니라 결함 보고서입니다. 그러나 각 레인이 모두 한도를 지키는 것처럼 보여도 실행이 크기 초과로 실패할 수 있는 이유가 바로 여기에 있습니다.

도구 레인은 측정 가능하며 IronClaw는 이를 측정합니다. 합성 93개 도구 픽스처에 대한 커밋된 벤치마크는 22개 도구가 광고된 상태에서 추정 스키마 토큰 21,355개에서 3,843개로 감소했음을 기록합니다. 감소율은 82.0%이며, 저장소 내부에서 2.0포인트 드리프트 허용 오차와 50.0% 하한으로 검증됩니다. 이 수치는 여기서 실행한 결과가 아니라 테스트 파일에서 읽은 것입니다. 릴리스된 바이너리의 측정 페이로드는 위 섹션에 있으며 형태가 다릅니다. 93개 도구 픽스처가 아니라 기본 도구 세트입니다. 이 수치는 픽스처의 문자 수에 기반한 IronClaw 내부 추정치로 이해해야 합니다. 여러분의 도구 프롬프트가 아니며, 공급자 토크나이저의 토큰 수도 아닙니다. 여기서 정확히 읽어야 할 것은 전체적인 양상입니다. 점진적 공개는 스키마 대부분을 제거하지만 어떤 설정으로도 제거할 수 없는 몇 천 토큰의 하한은 여전히 남습니다. 27개 핵심 이름이 모든 공개 모드에서 광고되기 때문입니다.

릴리스된 1.4.1 바이너리가 수행한 작업

2026년 10월 1일, 체크섬 검증을 마친 ironclaw-v1.4.1 릴리스 바이너리를 일회성 컨테이너에서 실행했습니다. openai_compatible 공급자를 대상으로 하는 [llm.default] 슬롯이 각 요청을 기록하는 로컬 테스트 서버를 가리키도록 했습니다. ironclaw repl를 통해 실행할 때마다 짧은 메시지 하나를 보냈습니다.

따라서 릴리스된 빌드에서 하한은 실제입니다. 어떤 공개 모드에서도 26개보다 적은 스키마를 보내지 않았으며, IronClaw 자체의 토큰당 4자 추정치를 적용하면 35,703바이트는 여러분의 단어가 하나도 들어가기 전에 대략 8,900토큰에 해당합니다. 시스템 및 정체성 메시지는 여기에 약 24,000바이트를 더합니다. 이는 바이트에 대한 산술이지 공급자의 토큰 수가 아닙니다. 아래에 설명한 오타 위험도 추론이 아니라 확인되었습니다. true는 정확히 off 페이로드를 생성해 도구 프롬프트를 거의 두 배로 늘렸지만, 화면에는 이를 알리는 표시가 전혀 없었습니다.

하드 예산은 소스에서 설명한 대로 작동했습니다. 약 380,000자의 메시지는 엔드포인트로 전송되었지만, 약 460,000자의 메시지는 토큰당 4자로 계산할 때 108,000토큰을 초과하므로 컴퓨터 밖으로 나가지 않았습니다. REPL은 단계 Prompt, 종류 BudgetExceeded 및 요약 승인된 작업이 프롬프트 컨텍스트 토큰 예산을 초과함을 표시하는 경고 로그 줄만 출력했습니다. 구성이나 환경에서 해당 한도를 변경하는 설정은 발견되지 않았습니다. 스킬 레인 오류, 실제 모델의 오버플로 및 Kunavo를 통한 요청은 실행하지 않았습니다.

재시도는 해결책이 아니며 오타 하나가 상황을 악화시킵니다

기본 복구 전략은 반복 범위에서 컨텍스트 오버플로를 정확히 한 번 재시도하고, ShrinkContext 변경을 적용한 다음 중단합니다. 공급업체 자체 테스트 이름은 model_context_overflow_compacts_once_then_aborts 및 second_model_context_overflow_aborts_without_another_compaction입니다. 따라서 동일하게 너무 큰 요청을 재시도해도 성공할 수 없습니다. 규모를 비교하면 같은 전략의 기본값은 max_model_availability_attempts: 12 및 max_attempts_per_class: 2를 허용하며, 이 유형에는 단일 ShrinkContext 시도만 적용됩니다.

압축도 더 이른 시점에 해결해 주지는 않습니다. 트리거 임계값이 동일한 108,000이므로 트랜스크립트가 그 값에 도달하기 전에는 압축을 강제하는 것이 없습니다. 강제 압축과 복구 압축은 회로 차단기를 우회하며, 이는 재시도 전에 너무 큰 프롬프트를 줄이는 루프의 유일한 방법입니다. 대체 전략에 관한 주의 사항으로, 2026년 7월 3일부터 열린 이슈 #5582는 ActiveTaskPreservingCompactionStrategy가 오버플로 플래그를 전혀 읽지 않는다고 보고합니다. 특정 배포가 어떤 전략을 선택하는지는 여기서 추적하지 않았습니다.

무엇보다 먼저 확인할 가치가 있는 구성 위험이 하나 있습니다. 점진적 도구 공개는 REBORN_TOOL_DISCLOSURE에서 읽고, off | compact | signatures | namespaces | bridged을 허용하며, 설정되지 않았거나 비어 있으면 namespaces로 기본 설정됩니다. 오타, 오래된 true 또는 on 같은 다른 비어 있지 않은 값은 조용히 Off로 해석됩니다. 같은 파일에는 이를 "대조군: 권한이 부여된 모든 스키마를 알림"으로 문서화합니다. UTF-8이 아닌 값도 동일하게 처리됩니다. 유일한 신호는 tracing::debug! 줄이며, 결과적으로 도구 프롬프트가 크게 커집니다. 철자를 추측하지 말고 변수를 설정 해제하세요.

오늘 실제로 변경할 수 있는 것

컨텍스트 예산, 압축 또는 이 네 가지 오류를 다루는 공개 IronClaw 문서 페이지는 없습니다. 따라서 아래의 조정 수단은 공급업체가 보증한 해결책이 아니라 문서와 코드가 함께 뒷받침하는 내용입니다.

스킬 컨텍스트 부담을 줄이는 문서화된 유일한 수단은 환경 변수가 아닌 구성 플래그입니다. IronClaw의 스킬 페이지는 [skills] 아래에 이를 설정하라고 안내하며, 키워드 및 태그 활성화와 명시적인 $my-skill 언급도 여전히 스킬을 주입한다고 설명합니다.

[skills]
# Documented lever: stops regex auto-activation from loading full skill
# context. Keyword/tag activation and $my-skill mentions still inject skills.
regex_activation_enabled = false

제한 사항이 명시된 세 가지 수단이 더 있습니다. 스킬의 max_context_tokens 프런트매터 필드는 같은 문서 페이지에 따라 기본값이 2000이지만, 여기에 작은 숫자를 적어도 큰 스킬이 줄어들지는 않습니다. 본문 추정치가 선언된 값의 두 배를 초과하면 선택기는 "실제 추정치 사용"을 기록하고 측정된 크기를 계산합니다. 반응형 루틴은 allowed_tools를 통해 도구 범위를 좁힐 수 있지만, 이는 해당 루틴에만 적용되며 대화형 턴에는 적용되지 않습니다. 파일 도구는 ALLOW_LOCAL_TOOLS=true일 때만 활성화됩니다. IronClaw의 파일 도구 문서에 따르면 호스팅 또는 공유 환경에서 "실수로 파일 시스템에 접근하는 것을 방지하기 위해" 기본적으로 비활성화되어 있으므로, 비활성 상태로 두면 프롬프트의 스키마 집합 하나가 줄어듭니다. 이 세 가지 모두 128,000을 건드리지는 않습니다.

마지막으로 더 이상 사용되지 않는 숫자를 기준으로 계획하지 마세요. 이슈 #7485는 ASCII 콘텐츠에서 108,000토큰 예산이 "실질적으로 약 54k 실제 토큰"이며 압축이 "대략 2배 일찍" 실행된다고 보고했습니다. 이는 두 토큰 추정기 중 하나의 이중 계산 때문이었습니다. PR #7502는 이를 통합했으며 2026년 8월 11일에 병합되었습니다. GitHub 비교 API에 따르면 병합 커밋은 v1.3.0 및 v1.4.0 태그 내부이자 main 내부에 있습니다. v1.2.0 및 v1.1.0와 비교하면 결과는 "diverged"이므로 이를 포함하는 가장 이른 릴리스는 확정되지 않았습니다. v1.3.0 이상이라고 표현하세요. 현재의 단일 추정기는 ASCII를 토큰당 4자로 계산하고, 3바이트 비ASCII 문자는 대략 1.5토큰으로 계산합니다. 따라서 CJK가 많은 트랜스크립트는 영어 트랜스크립트보다 훨씬 빠르게 108,000을 채웁니다.

턴당 한도 비용과 어느 경로가 유리한가

이는 측정된 작업 비용이나 청구 한도가 아닌, 예시용 토큰 산술입니다. 최대로 채워진 턴 하나를 가정해 보겠습니다. 트랜스크립트는 108,000토큰 한도까지 차 있고, ID 8,000개, 스킬 컨텍스트 4,000개(선택기의 기본 예산이며, 구성된 런타임에서 6,000으로 연결하면 증가), 위에 기록된 벤치마크의 광고된 도구 스키마 3,843개가 있습니다. 여기에 123,843개의 추정 입력 토큰과 2,000개의 출력 토큰이 더해집니다. 이는 합성 픽스처에 대한 IronClaw 자체의 추정치이므로 실제 공급자 토크나이저와는 다릅니다. 요금은 백만 토큰당 실시간 Kunavo 카탈로그 가격입니다.

이 섹션의 핵심은 마지막 열입니다. 오타가 난 REBORN_TOOL_DISCLOSURE는 17,512개의 추정 입력 토큰을 모든 턴에 추가합니다. Claude Sonnet 4.6에서는 이것이 $0.037이며 다른 변화가 전혀 없어도 턴당 발생하는 비용입니다. 항상 실행되는 에이전트는 하루에 여러 턴을 수행합니다. 두 번째로, 이를 피하기 위해 긴 컨텍스트 모델에 비용을 지불해도 효과가 없습니다. IronClaw는 모델 윈도우와 관계없이 자체 수치까지 조립하므로 추가 윈도우는 아무것도 사지 못하고, 더 높은 요금은 모든 123,843 토큰에 부과됩니다. 이를 예산으로 취급하기 전에 하루의 실제 턴 수를 곱하세요.

호스팅 요금제 정보는 2026년 9월 21일 ironclaw.com에서 읽었습니다. ironclaw.com/pricing는 HTTP 404를 반환하므로 요금제는 홈 페이지에 있습니다. 세 카드 위의 제목은 "신뢰 실행 환경에서 최대 5개의 에이전트를 월 최대 130M 토큰으로 실행"입니다. 5개 에이전트는 Pro+의 최대값이므로 이 제목은 어느 한 카드가 아니라 최상위 요금제의 한도를 나타냅니다. 또한 130M 토큰 수치는 어떤 카드에도 표시되지 않습니다. 포함된 크레딧이 토큰으로 얼마에 해당하는지와 모두 소진되면 어떻게 되는지는 공개되지 않았으며 여기서 추측하지 않습니다.

Kunavo는 임베딩, 텍스트 음성 변환 또는 음성 텍스트 변환 모델을 제공하지 않으므로, 설정에서 검색 또는 음성 단계를 사용하려면 외부 공급자를 호출해야 합니다.

시도한 다음 요금을 확인하세요

IronClaw를 OpenAI 호환 게이트웨이로 라우팅하는 경우 Kunavo의 chat-completions 엔드포인트가 openai_compatible 공급자 ID가 기대하는 형태입니다. 이는 양측 문서에서 확인한 프로토콜 일치입니다. 위의 10월 1일 실행은 로컬 테스트 서버를 사용했으며 Kunavo를 사용하지 않았으므로 Kunavo는 호환성을 주장하지 않습니다. 작동하는 경로를 유지하고, 하나의 제한된 작업을 실행한 다음, IronClaw가 표시하는 자체 산술 비용이 아니라 계정에 기록된 사용량과 대조하세요. Kunavo 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림이 요금을 보고하면 청구액은 카탈로그 비용과 업스트림 비용에 적용 가능한 마크업을 곱한 값 중 더 큰 금액입니다. 최소 충전 금액은 선불 크레딧 $10입니다. 이는 자금 충전 최소액이지 작업 요금이나 구독료가 아닙니다. 결제 세부 정보를 참조하고 키에 자금을 충전할 준비가 되면 계정을 생성하세요. 관련 선택지는 AI 비용 최적화에서 완료된 작업당 비용 측정을 다루며, PicoClaw와 ZeroClaw에서는 루프 길이가 동일한 방식으로 비용 조정 수단인 두 자매 런타임을 다룹니다.

자주 묻는 질문

2026년 10월 1일 실행: ironclaw-v1.4.1 릴리스 바이너리를 로컬 테스트 서버에 연결해 실행했습니다. 위의 공개 표와 예산 프로브를 확인했고, #5739, #8053, #8057, #7976 및 #5435의 이슈 상태를 같은 날 다시 확인했으며 모두 여전히 열려 있었습니다. 2026년 9월 21일 확인. 소스 상수, 오류 문자열, 복구 전략, 토큰 추정기, 공개 모드 및 벤치마크 기준선은 GitHub contents API를 통해 커밋 b0b999d의 nearai/ironclaw main에서 읽었습니다. 이슈 및 풀 리퀘스트 상태는 GitHub issues API를 통해 확인했고, 스킬, 구성, 저장소 및 파일 도구 페이지는 docs.ironclaw.com에서, 요금제 카드는 ironclaw.com에서 직접 가져왔습니다. v1.4.0 릴리스 태그는 체크아웃하지 않았고, IronClaw 인스턴스를 실행하지 않았으며, 저장소의 테스트를 실행하지 않았습니다. 네 가지 오류 중 어느 것도 실제로 발생하는지 재현하지 않았고, Kunavo도 IronClaw를 런타임 테스트하지 않았습니다. Kunavo 토큰 요금은 실시간 카탈로그에서 가져왔으며 모든 달러 수치는 예시용 토큰 산술입니다.