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：在 ~/.openclaw/.env 中加入 KUNAVO_API_KEY=sk-kn-...，或者在启动 Gateway 的环境里导出它。配置加载时，配置块里的 ${KUNAVO_API_KEY} 会被替换成那里的值。
3. 把配置块合并进 ~/.openclaw/openclaw.json，保留你已有的 providers、agents 和 channels。这个文件是 JSON5，注释可以留着。
4. 运行 openclaw config validate。文件里只要有它不认识的设置，OpenClaw 就会拒绝启动，所以拼写错误在这里发现，好过等到下次重启。
5. 运行 openclaw models list --provider kunavo，确认两个模型 ID 都在列表里。如果正在运行的 Gateway 还没有读到改动，就执行 openclaw gateway restart。
6. 用 /new 开一个新会话——已有的会话会沿用原来的模型——发送两条消息，然后查看 /usage tokens：第二轮应当显示 cacheRead。

已于 2026年10月5日 对照 OpenClaw 的自定义提供商参考文档 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 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"}]}'

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

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 保留 /v1，OpenClaw 自己的自定义提供商示例用的就是这种写法。api 为 openai-completions——自定义提供商只给了 baseUrl 而没有 api 时，OpenClaw 默认的也是它。此外，maxTokens 在实际使用中不再是可选的：模型的输出上限未知时，OpenClaw 在这种协议下根本不发送上限，Kunavo 就会让 Claude 的回复在 4,096 个 token 处结束。

Claude 的模型 ID 在这里同样可用；如果你想用一个条目接所有模型，就该用这种协议。对 Claude 来说有两点不同：在 chat completions 上，思考级别不会被转发；缓存断点由 Kunavo 放置，而不是 OpenClaw。

两种协议下的提示缓存

在 Anthropic 协议下，缓存断点由 OpenClaw 自己放置，但对自定义端点来说，只有设置了 cacheRetention 才会放。它的提示缓存参考文档对此写得很具体：默认值 short 只会预置给 anthropic 和 anthropic-vertex 这两个提供商，其他所有 Anthropic 系的路由都需要显式写出取值。Kunavo 的 /v1/messages 会原样转发请求体，不添加任何断点，所以没有这两行的配置什么都不会缓存。

short 请求的是五分钟的条目，long 请求的是一小时的。两种标记 Kunavo 都会转发，并按同一费率对写入计费。下一次心跳到来时，一小时的条目是否还在，值得先用你自己的用量确认，再据此安排心跳的节奏：显示 cacheRead 的那一轮保住了缓存，再次显示 cacheWrite 的那一轮则没有。/usage tokens 和 /status 都会显示这两个计数。

在 OpenAI 兼容协议下则正好相反。OpenClaw 不会向代理（proxy）端点发送任何缓存提示，Claude 模型的断点由 Kunavo 自己放置——在系统提示词、工具定义和对话末尾——只要提示词长到可以缓存。这里没有需要配置的东西；GPT 模型则由其厂商隐式缓存。

不管断点由哪一端放置，账单的算法都一样。在 Claude Sonnet 5 上，缓存读取是每 1M token $0.14，而新输入是 $1.40；缓存写入是 $1.75——这是 Claude 在输入价之上的写入溢价，条目要求一小时有效期时也按这同一费率收取。一个条目保留五分钟，每次读取都会给它续期，所以智能体要付多少，与其说取决于模型，不如说取决于它的下一个请求能否在这个窗口内到达。每个模型的缓存费率见提示缓存页面。

OpenClaw 可以在本地显示同样的算术。它的 /usage cost 汇总和 /status 里的费用行，都需要每个模型行上有一个 cost 对象；没有的话，它们显示为零，而 Kunavo 照常计费。下面这些行是从实时的模型目录生成的：

// 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 个 token，改成独立会话后则只有几千个。三十分钟比五分钟的缓存窗口长，所以每次运行都要为整个提示词重新计费：按输入费率，或者在放了断点的地方按更高的写入费率。下表按输入费率计算空闲一天的费用，独立运行按 5,000 个 token 计：

下面的配置块对应这张表中费用较低的配置：心跳使用 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 个 token 的上下文，外加 2,000 个新 token，并返回 800 个 token 的输出。在 Claude Sonnet 5 上，上下文从缓存读取时约为 $2.31；每个请求都把它当作新输入计费时约为 $14.84。同样的工作，同样的模型：差别只在于断点有没有放，以及请求之间的间隔是否不到五分钟。

再给一个量级，这是实测而非假设：在运行常驻智能体的 Kunavo 账户中，活跃日的花费中位数是 $12.67，第 90 百分位的一天约为 $163。这些是截至 2026年10月5日 实际计费的金额，按各自当天生效的费率计算。这组账户数量不多，所以请把它看作范围有多宽，而不是对你的智能体的预测。

余额用完时

Kunavo 是预付费的：每次调用都从钱包里扣，而一个在你睡觉时干活的智能体，也会在你睡觉时把钱包花空。钱包付不起的请求会被拒绝，返回 HTTP 402 和错误码 insufficient_balance，两种协议都一样，并且不为它收取任何费用。拒绝会在钱包归零之前就出现：每个请求都要先预留它在最坏情况下的费用，也就是提示词加上它被允许生成的最长回复，所以智能体要求的输出上限越大，它的调用就越早开始被退回。错误信息会用 balance_usd 和 needed_usd 说明还差多少。

OpenClaw 根据 402 的消息内容来判断它意味着什么。按OpenClaw 2026.9.8 的规则，这种来自钱包的拒绝属于计费失败，而它的故障转移参考文档说明了接下来会发生什么：凭据被停用十分钟，这次运行转到 agents.defaults.model.fallbacks 里的下一个模型，而且充值并不会解除这段停用——所以充值之后，智能体仍可能用不上 kunavo/…，直到停用期结束。密钥月度上限的拒绝则会被另作解读：它的消息提到的是一个会重置的上限，同一套规则把这当作速率限制——OpenClaw 会先重试，然后让凭据冷却，起初 30 秒，最长五分钟。openclaw models status 会列出被停用的凭据及其恢复时间。

有两项设置能让无人值守的智能体不落到这种境地，它们各管各的事：

• 自动充值，在充值与账单页面里。保存一次银行卡，再设三个数：余额低于多少时充值、每次充多少，以及月度上限。此后，只要某次调用让余额跌破阈值，钱包就会在几秒内自动补上。钱包仍然不够时到达的请求，会等这笔扣款完成后照常得到处理，而不是被拒绝。扣不了款（银行卡被拒、月度上限已到）时，或者单个请求要预留的金额超过充值后的钱包余额时，仍会返回 402。它需要银行卡或 Link——Alipay、WeChat Pay、Pix 等本地支付方式无法自动扣款。
• 密钥的月度上限，在API 密钥页面里。给智能体单独一个密钥，并设定这个密钥在一个自然月里最多能花多少。超过这个数之后，它的调用会被拒绝并返回 402，不收取任何费用，而你的其他密钥照常可用。失控的循环需要的正是这样一个上限，而钱包给不了，因为所有密钥用的是同一个钱包。

把充值阈值设在单个请求的预留金额之上，充值金额则按你的智能体一天的花费来定，而不是按最低额：最小充值额是 $10，而上文常驻智能体的日花费中位数是 $12.67。自动充值的各项限制见计费页面，完整的错误响应体见错误码页面。

相关指南

• OpenClaw 的最佳 API——为每一类任务选择提供商和模型。
• OpenClaw 定价——完整的运行账单：软件、托管、模型和工具。
• OpenClaw 多代理与多模型——把每个智能体路由到各自的模型，并按路由归集账单。
• Hermes 与 OpenClaw 对比——另一个智能体的同样配置，见 Hermes Agent 页面。