IronClaw 맞춤 API 설정: 프로바이더, 키, 개인정보 보호 경계

IronClaw은 하나의 네 필드 블록에서 사용자 지정 API를 처리합니다. ~/.ironclaw/reborn/config.toml에 있는 [llm.default] 슬롯에 provider_id, base_url, model, api_key_env을 지정하거나, 슬롯이 없으면 대신 대체되는 LLM_BACKEND, LLM_BASE_URL, LLM_API_KEY 환경 변수를 사용합니다. 두 형식 모두 현재 문서화되어 있습니다. 그러나 구성 페이지에는 사용자 지정 엔드포인트에서 제공되지 않는 항목 목록이 한곳에 정리되어 있지 않습니다. 여기에는 네이티브 스트리밍, 모델 검색, Anthropic cache_control 중단점, 정확한 비용 표시 등이 포함됩니다. 제공자를 선택하기 전에 읽어 볼 가치가 있는 부분은 바로 이 목록입니다.

검색 결과가 다른 제품으로 가득 차 있으므로 먼저 구분해 두겠습니다. 이 페이지는 github.com/nearai/ironclaw을 다룹니다. 자체 저장소 메타데이터는 이를 "IronClaw는 개인정보 보호, 보안 및 확장성에 초점을 둔 에이전트 OS입니다"라고 설명합니다. Rust로 작성되었고 보관되지 않았으며 포크도 아닙니다. 별은 12,626개이고 2026년 2월 3일에 생성되었으며 2026년 9월 21일에 마지막으로 푸시되었습니다(GitHub API, 같은 날). 이 제품은 해당 이름의 Corsair 게이밍 마우스, Sanguine Productions의 테이블톱 RPG, IRONCLAW 암호화폐 토큰, 또는 관련 없는 JoasASantos/ironclaw 저장소가 아닙니다. 이들의 가격이나 구성은 이 페이지에 포함되어서는 안 됩니다. 공식 문서는 docs.ironclaw.com과 저장소 자체의 docs/ 트리입니다. 동일한 제목으로 순위에 나타나는 서드파티 Mintlify 미러는 오래된 내용일 수 있습니다.

제공업체 자체의 화면이 서로 다르므로, 여기서는 의역보다 출처를 그대로 인용할 가치가 있습니다. ironclaw.com은 본문에서 NEAR 로고와 "Near Foundation"이라는 문구 옆에 "Built by"를 표시하고, 푸터에는 "— by NEAR AI"를 표시합니다. 한편 GitHub 조직은 nearai입니다.

최소 IronClaw 사용자 지정 제공자 구성

ironclaw_config의 슬롯 구조체는 정확히 네 개의 선택적 필드를 허용하며, 자체 문서 주석은 이를 카탈로그 항목의 재정의로 설명합니다. model은 제공자의 default_model를 재정의하고, api_key_env은 api_key_env를 재정의하며, base_url는 default_base_url을 재정의합니다. 제공자 문서에는 base_url이 "프록시 또는 지역 엔드포인트를 통해 라우팅해야 할 때 다른 모든 제공자에서도 작동한다"고 추가로 설명되어 있습니다. 따라서 이는 일반 어댑터만의 기능이 아닙니다.

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

주의해야 할 세 가지 규칙입니다. base_url을 생략하면 기본값이 적용되지 않고 치명적입니다. 문서에는 "슬롯이 아무것도 가리키지 않게 되어 모델 확인이 실패한다"고 되어 있으며, openai_compatible 카탈로그 항목에는 base_url_required: true가 포함되어 있습니다. api_key_env에는 키가 아니라 변수 이름을 입력해야 합니다. 붙여 넣은 비밀값은 "파싱 시점에 거부되며 조용히 허용되지 않습니다". 대신 ironclaw config set <provider>.api_key은 입력 내용을 숨긴 채 요청합니다. 재시작하기 전에는 아무것도 적용되지 않습니다. config set은 "아무것도 재시작하지 않으며", 여전히 실행해야 하는 ironclaw service restart 단계를 출력합니다. 또한 config set이 슬롯을 대신 작성해 줄 것이라고 기대하지 마세요. 구성 페이지에는 [llm.default]이 "config.toml에서 직접 편집"하는 섹션 중 하나로 나와 있으며, config set은 "지원되지 않는 키를 조용히 무시하지 않고 거부"합니다.

환경 형식은 [llm.default]이 없을 때 사용하는 문서화된 대체 방식이며, 문서에는 선택지가 명확히 정리되어 있습니다. "둘 다 작동합니다. 영구 설치에는 TOML 슬롯을, 일회성 실행 및 컨테이너에는 환경 형식을 우선 사용하세요."

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

설정값의 적용 우선순위는 compiled defaults < config.toml < environment variables < CLI flags이므로, 내보낸 변수가 방금 편집한 파일보다 조용히 우선합니다. CLI 경로를 사용하면 직접 편집할 필요가 없습니다. 먼저 ironclaw models list, 다음으로 ironclaw models set-provider <id> --model <model>, 그다음 ironclaw models status을 실행하세요. 문서에 적힌 두 경로 중 어느 것도 그대로 신뢰하지 말고 ironclaw config path로 실제 경로를 확인하세요. 빠른 시작 페이지는 모든 항목이 ~/.ironclaw 아래에 있다고 설명하지만, 구성 및 온보딩 페이지는 ~/.ironclaw/reborn이라고 설명합니다. 호스팅 사용자가 주의할 운영상의 함정도 있습니다. 구성 페이지에 따르면 ironclaw service 명령은 "NEAR AI 호스팅 인스턴스에서는 작동하지 않습니다. 명령을 처리할 사용자 서비스 관리자가 없기 때문입니다." 따라서 ironclaw config을 위해 SSH로 접속하고 Agent Dashboard에서 재시작하세요. 모든 인용은 2026년 9월 21일 main 브랜치에서 확인했습니다.

사용자 지정 엔드포인트가 도달하지 못하는 기능

이는 main의 소스 코드와 계약 파일에서 확인한 IronClaw의 의도된 런타임 동작에 대한 자체 설명입니다. 실제 실행 결과가 아니며, 이를 확인했을 당시 main은 2026년 8월 28일에 게시된 1.4.0 릴리스 태그보다 앞서 있었습니다(GitHub releases API 기준).

IronClaw의 카탈로그는 채팅 카탈로그이며, Kunavo는 임베딩, 텍스트 음성 변환 또는 음성 텍스트 변환 모델을 제공하지 않습니다. 따라서 이러한 기능이 필요한 설정의 어떤 부분이든 완전히 다른 곳을 가리켜야 합니다.

IronClaw의 비용 표시는 실제 청구서가 아닙니다

IronClaw 내부에서 비용을 계산하는 경로는 서로 다른 두 가지이며 서로 일치하지 않고, 어느 경로도 사용자의 제공자를 읽지 않습니다. ironclaw_common의 price_usage()은 하드코딩된 토큰당 표를 사용해 가격을 계산하고 default_cost()로 대체합니다. 즉, 토큰당 입력 0.0000025, 토큰당 출력 0.00001이며, 이는 100만 토큰당 $2.50 / $10.00인 GPT-4o와 같은 요율입니다. 그 이유는 "새로운 유료 모델이 조용히 0으로 가격이 매겨지지 않도록 하기 위해서"라고 명시되어 있습니다. 한편 loop host의 StaticModelCostTable는 예산 예약에 대해 반대로 동작합니다. 표에 없는 프로필은 "None로 대체되며, 회계 시스템은 이를 비용 0으로 처리합니다." 또한 llm_costs 경로에서는 캐시 읽기 할인이 모델 이름의 부분 문자열로 추정됩니다. 이름에 claude이 포함되면 10으로 나누고, gpt가 포함되거나 o1, o3, o4 중 하나로 시작하면 2로 나누며, 나머지는 1로 나눕니다.

실질적인 결과는 IronClaw의 budget.user_daily_usd, budget.pause_at 및 나머지 [budget] 키가 청구 금액이 아니라 추정치를 관리한다는 것입니다. 항상 실행되는 에이전트에서는 여전히 이 값을 설정할 가치가 있습니다. 폭주하는 루프를 조기에 중단하는 것이 목적이기 때문입니다. 그러나 화면에 표시된 숫자가 아니라 제공자가 기록한 사용량을 기준으로 대조하세요.

에이전트 하루 사용량의 계산 예시

이는 측정된 작업 비용이 아니며 청구 한도도 아닌 토큰 산술입니다. 에이전트 활동이 하루 동안 총 캐시되지 않은 입력 토큰 1,000,000개와 출력 토큰 40,000개를 사용한다고 가정합니다. 이는 설명을 위한 가정이며, 항상 실행되는 런타임이 긴 응답이 아니라 하트비트 틱과 루틴을 통해 입력을 누적하기 때문에 선택한 수치입니다. 요율은 100만 토큰당 실시간 Kunavo 카탈로그 가격입니다.

마지막 열이 유용한 의외의 정보이며, 이는 모델 자체가 아니라 id 문자열의 속성입니다. vision_models.rs은 claude-opus-, claude-sonnet-, claude-haiku-, claude-fable-를 포함한 고정 목록과 부분 문자열을 비교하므로 해당 id는 이미지 첨부를 라우팅합니다. 위 표의 다른 id는 gpt-4o, gemini-1.5, gemini-2 또는 나머지 목록과 일치하지 않으므로 텍스트 전용으로 분류됩니다. 일치하지 않으면 loop-host 게이트웨이는 이미지 부분 없이 메시지 텍스트만 전송하고 오류를 발생시키지 않습니다. 영구 트랜스크립트에는 <attachments> 포인터가 남지만 모델은 이미지를 보지 못합니다. 이미지 입력이 작동한다고 가정하기 전에 입력하려는 정확한 id를 패턴 목록과 대조하세요. 금액을 예산으로 보기 전에 자신의 사용 일수에 맞게 조정하세요. Kunavo의 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림이 요금을 보고하면 청구액은 카탈로그 비용과 업스트림 비용에 해당 마크업을 곱한 금액 중 더 큰 값입니다. 캐시 요금과 외부 도구는 이 예시에 포함되지 않으며, 최소 충전액은 선불 크레딧 $10입니다. 이는 자금 충전 최소액이지 작업 요금이나 구독료가 아닙니다. 청구 세부 정보를 참조하세요.

어떤 경로가 더 적합한가, 그리고 IronClaw 자체의 비용은 얼마인가

소프트웨어는 무료입니다. 저장소 루트에는 LICENSE-APACHE과 LICENSE-MIT이 모두 있으며 README에는 MIT OR Apache 2.0이라고 명시되어 있습니다. 바이너리의 유료 버전이나 라이선스 비용은 없습니다. 지불하는 비용은 토큰 비용과 공급업체의 호스팅을 이용할 경우의 호스팅 비용입니다.

호스팅 요금제 가격은 2026년 9월 21일에 ironclaw.com에서 확인했습니다. /pricing 페이지는 없으며, 요금제는 홈페이지에 나와 있습니다. 렌더링된 마크업에서는 $5가 취소선이 적용된 span 안에 표시되고, $0가 현재 가격으로 표시됩니다. 홈페이지에는 "Trusted Execution Environment에서 최대 5개의 에이전트를 실행하고 매월 최대 130M 토큰을 사용할 수 있습니다"라는 주장도 있습니다. 이 문장은 세 요금제 카드 모두의 위에 있으며 특정 요금제를 명시하지 않으므로, 어느 한 요금제에 해당하는 내용으로 간주하지 마세요. 이 가이드에서 확인하지 못했으며 추측하지 않을 사항은 세 가지입니다. 호스팅 요금제에서 타사 키 사용을 허용하는지, 포함된 크레딧으로 실제로 무엇을 구매할 수 있는지 또는 크레딧이 소진되면 어떻게 되는지, 그리고 130M이라는 수치가 어느 요금제에 해당하는지입니다. 토큰 요금은 같은 날 near.ai/pricing에서 확인했습니다. 해당 페이지에는 "모델 요금 외에 추가 플랫폼 수수료는 없습니다"라고 명시되어 있으며, 기밀성을 보장하는 자사의 텍스트 모델만 다룹니다.

사람들이 이 런타임을 선택하는 이유이므로, 한 가지 개인정보 보호 경계를 분명히 밝혀야 합니다. IronClaw의 README와 보안 페이지가 설명하는 제어 기능, 즉 “저장 시 암호화”되고 호스트 경계에서 주입되는 시크릿, 신뢰할 수 없는 도구를 위한 WASM 샌드박스, 엔드포인트 허용 목록, 유출 감지 기능은 에이전트를 실행하는 머신에 대한 로컬 제어입니다. 하드웨어 증명은 별개의 NEAR AI Cloud 속성입니다. near.ai는 그곳의 추론이 “Intel TDX + NVIDIA 기밀 GPU 인클레이브에서 실행”되며 “각 응답에 검증 가능한 하드웨어 증명값이 포함된다”고 설명합니다. IronClaw를 타사 엔드포인트로 지정하면 해당 엔드포인트의 약관에 따라 프롬프트 내용이 그 엔드포인트로 전송되며, 어느 목록의 기능도 그곳까지 따라가지는 않습니다. ironclaw.com의 벤더 작성 “OpenClaw vs IronClaw” 표는 한쪽이 작성한 마케팅 자료이지 중립적인 비교가 아닙니다. 또한 검색 결과에 주의하세요. 2026년 9월 17일에 수집한 결과 페이지 표본에서는 네 가지 검색어 형식 best api for ironclaw, cheapest api for ironclaw, best model for ironclaw, ironclaw custom provider 각각의 상위 10개 결과에 OpenClaw 결과가 8개 이상 포함되어 있었고, 해당 모델 순위는 다른 제품을 설명합니다.

설정한 다음 첫 번째 청구 금액을 확인하세요

Kunavo는 OpenAI 형식의 엔드포인트를 https://api.kunavo.com/v1에, Anthropic 형식의 엔드포인트를 제공하며, 이는 openai_compatible 및 anthropic 공급자 ID에 매핑됩니다. Kunavo는 IronClaw을 런타임에서 테스트하지 않았으므로 위 블록을 호환성 주장으로 보지 말고 문서화된 프로토콜을 시작하는 지점으로 취급하세요. 작동하는 경로를 유지하고, 제한된 작업 하나를 실행한 뒤, 계정에 실제로 기록된 청구 금액을 확인하세요. ACP를 통해 IronClaw에서 Goose를 구동하는 경우 — .env.example는 Agent Client Protocol 샌드박스와 ironclaw acp add goose 명령을 설명합니다 — Goose 통합에서 해당 측면을 별도로 다루며, 준비가 되면 Kunavo 계정을 생성하여 키에 자금을 충전할 수 있습니다. 주변 선택 사항은 OpenAI 호환 API 참조, OpenRouter 대안 및 AI 비용 최적화를 참고하세요.

자주 묻는 질문

저장소 메타데이터, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, docs/ 트리, ironclaw.com 및 near.ai/pricing은 모두 2026년 9월 21일에 1.4.0 릴리스 태그가 아닌 main 브랜치에서 확인했습니다. IronClaw 요청을 Kunavo 엔드포인트로 전송한 적은 없으며, 여기의 모든 호환성 설명은 양측 문서를 읽고 정리한 것입니다. Kunavo 토큰 요금은 현재 카탈로그에서 가져왔고, 모든 달러 예시는 토큰 산술을 설명하기 위한 것입니다.