OpenClaw

~/.openclaw/openclaw.json의 models.providers 항목 하나에 baseUrl https://api.kunavo.com, api "anthropic-messages"를 설정하면 상시 실행되는 OpenClaw 에이전트가 Claude를 사용하게 됩니다. cacheRetention도 그 옆에 설정합니다. 사용자 지정 Anthropic 엔드포인트는 이 설정이 이루어지기 전까지 캐시 마커를 받지 못하기 때문입니다.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. Gateway가 사용할 키를 설정하세요. KUNAVO_API_KEY=sk-kn-...를 ~/.openclaw/.env에 추가하거나 Gateway가 시작될 때 사용하는 환경에 키를 내보내세요. 설정을 불러올 때 해당 위치의 값으로 블록 안의 ${KUNAVO_API_KEY}가 대체됩니다.
3. 기존 providers, agents, channels 설정은 유지하면서 블록을 ~/.openclaw/openclaw.json에 병합하세요. 파일은 JSON5 형식이므로 주석도 그대로 둘 수 있습니다.
4. openclaw config validate을 실행하세요. 파일에 인식할 수 없는 설정이 있으면 OpenClaw는 시작을 거부하므로, 오타는 다음 재시작 때보다 여기서 찾는 편이 낫습니다.
5. openclaw models list --provider kunavo를 실행해 두 ID가 모두 표시되는지 확인하세요. 실행 중인 Gateway가 변경 사항을 반영하지 않았다면 openclaw gateway restart를 실행하세요.
6. /new로 새 세션을 여세요. 기존 세션은 이미 사용 중인 모델을 계속 사용합니다. 메시지 두 개를 보낸 다음 /usage tokens를 확인하세요. 두 번째 차례에 cacheRead가 표시되어야 합니다.

OpenClaw 사용자 지정 공급자 참조 문서에서 확인했습니다(2026년 10월 5일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.

클라이언트를 디버깅하기 전에 확인할 사항

한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base URL과 키가 OpenClaw에서 작동합니다.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

필드에 입력할 model id

모든 텍스트 모델은 model id로 접근할 수 있습니다. 현재 목록은 GET /v1/models이며, 가격이 포함된 카탈로그는 모델 페이지에서 확인할 수 있습니다. 요금은 토큰 100만 개당 USD 기준이며 입력 / 출력 순서입니다.

OpenAI 호환 프로토콜

같은 키로 /v1/chat/completions를 통해 다른 모든 모델 제품군에도 연결할 수 있습니다. 두 프로토콜을 분리하려면 두 번째 공급자 항목으로 등록하고, 해당 모델은 kunavo-openai/<id> 형식으로 참조하세요.

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

위 블록과 다른 점은 세 가지입니다. 기본 URL에는 OpenClaw 자체의 사용자 지정 공급자 예시에서 사용하는 /v1가 포함됩니다. api는 openai-completions이며, 사용자 지정 공급자에 baseUrl가 있고 api가 없을 때 OpenClaw가 기본으로 사용하는 값이기도 합니다. 또한 실제로는 maxTokens를 생략할 수 없습니다. 모델의 출력 한도를 알 수 없으면 이 프로토콜에서 OpenClaw는 한도를 전송하지 않으며, 이 경우 Kunavo는 Claude 응답을 4,096 토큰에서 종료합니다.

여기서도 Claude ID를 사용할 수 있으므로, 모든 모델에 하나의 항목을 쓰려면 이 프로토콜을 사용하세요. Claude 모델에는 두 가지 차이가 있습니다. chat completions에서는 사고 수준이 전달되지 않으며, 캐시 중단 지점은 OpenClaw가 아니라 Kunavo가 설정합니다.

각 프로토콜의 프롬프트 캐싱

Anthropic 프로토콜에서는 OpenClaw가 캐시 중단 지점을 설정하지만, 사용자 지정 엔드포인트의 경우 cacheRetention를 설정해야만 그렇게 합니다. OpenClaw의 프롬프트 캐싱 참조 문서에는 기본값 short가 anthropic 및 anthropic-vertex 공급자에만 지정되어 있으며, 그 외의 모든 Anthropic 계열 경로에는 명시적인 값이 필요하다고 나와 있습니다. Kunavo의 /v1/messages는 요청 본문을 받은 그대로 전달하며 중단 지점을 추가하지 않으므로, 이 줄을 설정하지 않은 구성에서는 캐시가 작동하지 않습니다.

short는 5분 항목을, long는 1시간 항목을 요청합니다. Kunavo는 두 마커를 모두 전달하고 쓰기 요금을 같은 요율로 청구합니다. 다음 하트비트가 도착했을 때 1시간 항목이 여전히 유지되는지는 주기를 계획하기 전에 직접 사용량으로 확인하는 것이 좋습니다. 차례에 cacheRead가 표시되면 캐시가 유지된 것이고, 다시 cacheWrite가 표시되면 유지되지 않은 것입니다. /usage tokens 및 /status에서 두 카운터를 모두 확인할 수 있습니다.

OpenAI 호환 프로토콜에서는 반대입니다. OpenClaw는 프록시 엔드포인트에 캐시 힌트를 보내지 않으며, Kunavo가 Claude 모델의 중단 지점을 직접 설정합니다. 프롬프트 길이가 캐싱에 충분해지면 시스템 프롬프트, 도구 정의, 대화 끝에 중단 지점을 둡니다. 별도로 설정할 항목은 없으며, GPT 모델은 공급업체에서 암묵적으로 캐시됩니다.

중단 지점을 어느 쪽에서 설정하든 청구 금액은 같습니다. Claude Sonnet 5에서 캐시 읽기 요금은 토큰 100만 개당 $0.14이며, 새 입력 요금은 $1.40입니다. 캐시 쓰기 요금은 $1.75입니다. 이는 Claude의 입력 요금보다 높은 쓰기 요금이며, 항목의 수명이 1시간으로 설정된 경우에도 같은 요율로 청구됩니다. 항목은 5분 동안 유지되고 읽을 때마다 수명이 갱신되므로, 에이전트의 지출은 모델보다 다음 요청이 이 시간 내에 도착하는지에 더 크게 좌우됩니다. 각 모델의 캐시 요금은 프롬프트 캐싱 페이지에서 확인할 수 있습니다.

OpenClaw에서 같은 계산 내역을 확인할 수 있습니다. /usage cost 요약과 /status의 비용 항목을 표시하려면 각 모델 행에 cost 객체가 필요합니다. 이 객체가 없으면 Kunavo에서 정상적으로 요금이 청구되어도 OpenClaw에는 비용이 0으로 표시됩니다. 다음 행은 실시간 카탈로그에서 생성됩니다.

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

상시 실행 에이전트의 일일 비용

OpenClaw 에이전트는 아무도 대화하지 않을 때도 하트비트 때문에 비용이 발생합니다. 하트비트는 기본적으로 30분마다 실행되는 예약 에이전트 턴으로, 하루에 48회 실행됩니다. 별도 지시가 없으면 주 세션에서 실행되며 대화 내용을 다시 전송합니다. OpenClaw 참고 문서에 따르면 이 실행은 약 100,000개의 토큰을 사용하며, 세션을 격리하면 몇천 개로 줄어듭니다. 30분은 5분 캐시 유효 시간보다 길기 때문에 매 실행마다 전체 프롬프트가 다시 과금됩니다. 입력 요율이 적용되거나 브레이크포인트가 설정된 경우 더 높은 쓰기 요율이 적용됩니다. 아래 표에서는 격리된 실행에 5,000개의 토큰을 사용한다고 가정하고 입력 요율로 하루 동안 유휴 상태일 때의 비용을 계산합니다.

아래 설정은 표에서 비용이 낮은 경우에 해당합니다. Haiku에서 격리된 세션으로, 워크스페이스 부트스트랩 파일 없이, 깨어 있는 시간에만 하트비트를 실행합니다. 여기에 사용된 각 설정은 OpenClaw 하트비트 참고 문서에서 가져왔습니다. every 간격을 늘리는 것도 비용을 줄이는 방법이며, "0m"을 설정하면 반복 실행이 중지됩니다.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

에이전트가 실제로 작동하는 시간은 청구액의 나머지 한 축이며, 이때는 캐시가 비용을 좌우합니다. 연속해서 100회 요청을 보내고, 매번 100,000개 토큰의 컨텍스트를 다시 전송하면서 여기에 2,000개의 새 토큰을 추가하고, 800개의 출력 토큰을 반환한다고 가정해 보겠습니다. Claude Sonnet 5에서는 컨텍스트를 캐시에서 읽는 경우 비용이 약 $2.31이고, 모든 요청에서 해당 컨텍스트가 새 입력으로 과금되는 경우에는 약 $14.84입니다. 작업도 모델도 동일합니다. 차이는 브레이크포인트를 설정했는지, 그리고 요청 간격이 5분 미만인지에 달려 있습니다.

규모를 가늠할 수 있도록 추정이 아닌 실제 측정값을 제시합니다. 상시 실행 에이전트를 운영하는 Kunavo 계정의 경우, 활성 상태인 날의 비용 중앙값은 $12.67이고 90백분위수에 해당하는 날은 약 $163입니다. 이는 각 날짜에 적용된 요율로 2026년 10월 5일까지 청구된 금액입니다. 표본이 적으므로 에이전트의 예측 비용이 아니라 범위의 폭을 보여 주는 값으로 봐 주세요.

잔액이 소진되면

Kunavo는 선불 방식입니다. 모든 호출 비용은 지갑 잔액에서 차감되며, 사용자가 자는 동안 작동하는 에이전트는 그 시간에도 잔액을 소진합니다. 지갑 잔액으로 감당할 수 없는 요청은 어느 전송 방식에서든 HTTP 402 및 insufficient_balance 코드와 함께 거부되며, 해당 요청에는 요금이 청구되지 않습니다. 거부는 지갑 잔액이 0이 되기 전에 발생합니다. 각 요청에서 먼저 최악의 경우에 드는 비용, 즉 프롬프트와 허용된 최대 응답의 비용을 예약하기 때문입니다. 따라서 에이전트가 더 큰 출력 한도를 요청할수록 호출이 더 일찍 거부되기 시작합니다. 오류에는 balance_usd 및 needed_usd 필드를 통해 금액이 얼마나 부족했는지 표시됩니다.

OpenClaw는 402의 의미를 메시지에서 판단합니다. OpenClaw 2026.9.8의 규칙에 따르면 지갑 잔액 부족으로 인한 거부는 결제 실패에 해당하며, 페일오버 참고 문서에는 이후 동작이 설명되어 있습니다. 인증 정보가 10분 동안 비활성화되고, 실행은 agents.defaults.model.fallbacks에 지정된 다음 모델로 넘어가며, 충전해도 대기 시간은 해제되지 않습니다. 따라서 충전 후에도 대기 시간이 끝날 때까지 에이전트가 kunavo/…에서 작동하지 않을 수 있습니다. 키의 월간 한도로 인한 거부는 다르게 처리됩니다. 오류 메시지에 재설정되는 한도가 표시되므로, 같은 규칙에 따라 속도 제한으로 간주됩니다. OpenClaw는 재시도한 다음 인증 정보를 처음에는 30초, 최대 5분 동안 대기 상태로 둡니다. openclaw models status에는 비활성화된 인증 정보와 복구 시점이 표시됩니다.

에이전트가 무인 상태에서 이 상황에 빠지지 않도록 하는 설정은 두 가지이며, 각각 다른 역할을 합니다.

• 자동 충전, 결제 아래에서 설정하세요. 카드를 한 번 저장한 다음 세 가지 금액을 설정합니다. 이 잔액 아래로 내려가면 충전할 기준 금액, 매번 추가할 금액, 월간 한도입니다. 그러면 API 호출로 잔액이 기준 금액 아래로 내려간 뒤 몇 초 안에 지갑이 충전됩니다. 지갑 잔액이 부족한 동안 도착한 요청은 해당 결제가 완료될 때까지 대기한 다음 거부되지 않고 처리됩니다. 결제를 진행할 수 없는 경우(카드 승인 거절, 월간 한도 도달) 또는 한 번의 요청에서 충전 후 지갑 잔액보다 많은 금액을 예약하는 경우에는 402가 계속 반환됩니다. 자동 결제를 이용하려면 카드 또는 Link가 필요합니다. Alipay, WeChat Pay, Pix 및 기타 현지 결제 수단은 자동으로 청구할 수 없습니다.
• 키별 월간 한도는 API 키 아래에서 설정하세요. 에이전트 전용 키를 발급하고 해당 키가 매월 1일부터 말일까지 사용할 수 있는 최대 금액을 설정합니다. 그 금액을 초과하면 해당 키의 호출은 402와 함께 거부되고 요금이 청구되지 않으며, 다른 키는 계속 작동합니다. 이는 폭주하는 루프를 제한하기 위해 필요한 상한이며, 모든 키가 같은 지갑을 사용하므로 지갑만으로는 설정할 수 없습니다.

충전 기준액은 요청 하나에 예약되는 금액보다 높게 설정하고, 충전액은 최소 금액이 아니라 에이전트의 하루치 비용을 기준으로 정하세요. 최소 충전액은 $10이며, 위에 제시된 상시 실행 에이전트의 하루 비용 중앙값은 $12.67입니다. 자동 충전 한도는 결제 페이지에서, 전체 오류 본문은 오류 페이지에서 확인할 수 있습니다.

관련 가이드

• OpenClaw에 가장 적합한 API — 작업 유형별 공급자와 모델 선택
• OpenClaw 요금 — 소프트웨어, 호스팅, 모델 및 도구를 포함한 전체 운영 비용
• 여러 에이전트 및 모델과 함께 사용하는 OpenClaw — 각 에이전트를 자체 모델로 라우팅하고 경로별로 비용을 집계하는 방법
• Hermes와 OpenClaw 비교 — 다른 에이전트에 같은 설정을 적용하는 방법은 Hermes Agent 페이지를 참고하세요.