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 是一个专注于隐私、安全和可扩展性的 Agent OS”：使用 Rust，未归档且不是 fork，拥有 12,626 个 stars，创建于 2026 年 2 月 3 日，最后一次推送于 2026 年 9 月 21 日（GitHub API，同日）。它不是同名的 Corsair 游戏鼠标、Sanguine Productions 桌面角色扮演游戏、IRONCLAW 加密代币，也不是无关的 JoasASantos/ironclaw 仓库——这些产品的价格或配置都不应出现在本页面附近。规范文档位于 docs.ironclaw.com 和仓库自己的 docs/ 目录；第三方 Mintlify 镜像会针对相同标题排名，但可能已经过时。
这里值得引用而不是转述归属信息，因为供应商自有页面的说法不同：ironclaw.com 在 NEAR 标志旁写着“Built by”，正文中写有“Near Foundation”，页脚写着“— 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 托管实例上运行——那里没有可供它们通信的用户服务管理器”，因此请通过 SSH 进入以执行 ironclaw config，然后从 Agent Dashboard 重启。所有引文均读取自 2026 年 9 月 21 日的 main 分支。
自定义端点无法触达的内容
以下是 IronClaw 自身关于其预期运行时行为的说明，内容来自 main 上的源代码和契约文件。它们并非实际运行结果；读取这些内容时，main 已领先于 1.4.0 发布标签——根据 GitHub Releases API，该版本于 2026 年 8 月 28 日发布。
| 能力 | 在自定义 OpenAI 兼容插槽上 | 相关说明所在位置 |
|---|---|---|
| 原生 SSE 流式传输 | 否——采用缓冲方式。仅在“IronClaw 能观察到权威终止事件的情况下”启用：NEAR AI、Anthropic OAuth 和 Codex Responses。Anthropic API 密钥传输方式和 OpenRouter 也采用缓冲方式 | ironclaw_llm/CONTRACT.md |
| 模型发现 | 否——can_list_models 对 openai_compatible 和 openrouter 均为 false，因此 ID 需要逐一手动填写，完全按原样填写 | assets/providers.json |
| 通过环境变量设置基础 URL | 此项可以——openai_compatible 声明了 LLM_BASE_URL。在 26 个目录条目中，只有 7 个声明了基础 URL 变量；openrouter、together、fireworks、groq、deepseek、mistral 以及其余条目必须使用 config.toml 字段 | assets/providers.json |
| 工具架构定义原样保留 | 否——在提供商边界处会重写为 OpenAI 严格模式：additionalProperties: false，强制所有属性纳入 required，并将可选项改为可空 | ironclaw_llm/CONTRACT.md |
| 提示缓存 | 情况混合，并非简单地不存在。Anthropic 的 cache_control 断点仅由两个 Anthropic 传输方式发出，因此 OpenAI 兼容插槽不会发送任何断点。但 OpenAI 的 prompt_cache_key 确实会传递到该插槽：该标志由“通用 OpenAI 兼容、DeepSeek 和 OpenRouter 工厂设置为 true”，其中循环主机网关是唯一提供值的接缝。至于你的端点随后是否缓存任何内容，则属于端点自身的行为，IronClaw 不会要求或观察该行为 | ironclaw_llm/CONTRACT.md |
| 跨提供商故障转移 | 否——故障转移装饰器通过 NEARAI_FALLBACK_MODEL 在 NEAR AI 模型之间切换；跨提供商类型的切换“需要手动构建” | ironclaw_llm/CONTRACT.md |
| 工具轮次响应缓存 | 从不缓存——由于存在副作用，complete_with_tools() 被排除在外 | ironclaw_llm/CONTRACT.md |
| 多用户安装时可由用户选择 | 不会自动提供——“仅配置提供商并不会向用户发布模型”；管理员需要在 Settings → Inference → User model access 下添加每个 ID | 提供商文档 |
IronClaw 的目录是聊天目录，而 Kunavo 不提供嵌入、文本转语音或语音转文本模型，因此你的配置中任何需要此类模型的部分都必须完全指向其他位置。
IronClaw 显示的成本不是你的账单
IronClaw 内部有两条分别计算金额的路径，两者彼此不一致，而且都不会读取你的提供商。price_usage() 在 ironclaw_common 中根据硬编码的每 token 表计算价格，并回退到 default_cost()——输入每 token 为 0.0000025、输出每 token 为 0.00001，即一个类似 GPT-4o 的每百万 token $2.50 / $10.00；其给出的理由是“新的付费模型不会在不知情的情况下被定价为零”。与此同时，循环主机的 StaticModelCostTable 在预算预留方面采取相反做法：表中缺少的配置文件“回退到 None，会计程序将其视为零成本”。而在 llm_costs 路径上，缓存读取折扣会根据模型名称通过子字符串猜测——claude 除以十，gpt 或以 o1/o3/o4 开头的名称除以二，其他全部除以一。
实际结果是，IronClaw 的 budget.user_daily_usd、budget.pause_at 以及其余 [budget] 键控制的是估算值，而不是收费金额。对于全天候运行的代理，它们仍值得设置——尽早停止失控循环正是其作用所在——但请以提供商记录的用量为准进行核对，而不是以屏幕上的数字为准。
代理一日运行的计算示例
这是token 算术，而不是经过测量的任务成本，也不是账单上限。假设代理运行一天，共计1,000,000 个未缓存输入 token和40,000 个输出 token——这只是用于说明的假设，之所以这样选择，是因为全天候运行时，输入会通过心跳周期和例程不断累积，而不是通过长篇回复累积。费率采用实时的每百万 token Kunavo 目录价格。
| 模型 | 每 1M 个令牌的输入 / 输出 | 代理一日估算成本 | 视觉模式是否匹配此 ID？ |
|---|---|---|---|
| Claude Haiku 4.5 | $0.70 / $3.50 | $0.840 | 是 |
| GPT-5.6 Terra | $0.70 / $4.20 | $0.868 | 否 |
| Claude Sonnet 4.6 | $2.10 / $10.50 | $2.520 | 是 |
| Claude Opus 5 | $3.50 / $17.50 | $4.200 | 是 |
最后一列是一个有用的意外：它取决于 ID 字符串，而不是模型本身。vision_models.rs 会对一个固定列表进行子字符串匹配，该列表包括 claude-opus-、claude-sonnet-、claude-haiku- 和 claude-fable-，因此这些 ID 会路由图像附件；上表中的其他 ID 均不匹配 gpt-4o、gemini-1.5、gemini-2 或列表中的其余项，因此会被分类为仅支持文本。匹配失败时，循环主机网关会在移除图像部分后发送消息文本，且不会报错——持久化转录会保留一个 <attachments> 指针，但模型永远看不到图像。在假设图像输入可用之前，请根据你打算填写的确切 ID 检查模式列表。将美元数字按你自己的运行天数进行缩放后，再把它们视为预算。Kunavo 的目录金额是计费下限，而不是上限：上游报告其费用时，账单金额取目录成本与上游成本乘以适用加价两者中的较高者。缓存费用和外部工具不包含在本示例中，最低充值金额为预付余额 $10 ——这是资金最低要求，而不是任务费用或订阅费。请参阅 计费详情。
哪条路径胜出，以及 IronClaw 本身的成本
软件免费：仓库根目录同时包含 LICENSE-APACHE 和 LICENSE-MIT，其 README 声明采用 MIT OR Apache 2.0 许可。该二进制没有付费版本，也没有许可费。你需要支付的是 token，以及在采用供应商托管方案时产生的托管费用。
| 方式 | 公布价格 | 适用场景 |
|---|---|---|
| 自托管 IronClaw | 软件成本 $0，MIT OR Apache-2.0 | 你已经运行着一台主机，并希望完全控制端点 |
| ironclaw.com Starter | 目前为 $0，标价 $5 划线显示；“包含 $5 额度” | 尝试托管路径。应将其视为促销信息，而不是永久性的 $0 方案 |
| ironclaw.com Basic | $20/月，“包含 $20 额度” | “最多 2 个代理实例”，跨部署共享用量 |
| ironclaw.com Pro+ | $200/月，“包含 $200 额度” | “最多 5 个代理实例”，提前体验高级模型，优先支持 |
| NEAR AI Cloud token | 每 1M token $0.15 / $0.50（GLM 5.3 Flash），最高为 $3.30 / $16.50（Kimi K3） | 供应商推荐的默认选项，也是内置故障转移会切换模型的唯一后端 |
| OpenAI 兼容网关 | 你的网关按 token 计费的费率 | 你希望按任务切换模型系列并使用一个密钥——接受缓冲式流传输和手动填写 ID |
| 通过 Ollama 使用本地模型 | 无单次请求费用 | 适用于小型或私有工作；按照 .env.example 的建议提高 LLM_REQUEST_TIMEOUT_SECS |
托管方案价格于 2026 年 9 月 21 日从 ironclaw.com 读取；不存在 /pricing 页面，方案位于主页上，渲染后的标记显示 $5 位于划线 span 内，而 $0 是当前价格。主页还声称“在受信任执行环境中启动最多 5 个代理，每月最多 130M token”——这句话位于三个卡片上方，没有指明任何方案，因此不要将其归属于某一个方案。本指南无法确定、也不会猜测以下三点：托管方案是否允许使用第三方密钥，包含的额度究竟可以购买什么或用完后会发生什么，以及 130M 数字属于哪个方案。token 费率于同日从 near.ai/pricing 读取，该页面声明“模型费率之外不收取平台费”，且仅涵盖其机密文本模型。
有一个隐私边界需要明确说明，因为这正是人们选择此运行时的原因。IronClaw 自身 README 和安全页面描述的控制措施——密钥“静态加密”并在主机边界注入、用于不受信任工具的 WASM 沙箱、端点允许列表、泄漏检测——都是对运行代理的机器实施的本地控制。硬件证明是 NEAR AI Cloud 的独立属性：near.ai 表示，其中的推理“在 Intel TDX + NVIDIA 机密 GPU enclave 中执行”，并且“每个响应都携带可验证的硬件证明”。将 IronClaw 指向第三方端点，会根据该端点的条款将提示内容发送到该端点；上述任一控制列表都不会随内容延伸到那里。ironclaw.com 上由供应商编写的“OpenClaw vs IronClaw”表格是单方面的营销材料，而非中立比较——还要谨慎对待搜索结果，因为在 2026 年 9 月 17 日获取的一个结果页样本中，四种查询形式 best api for ironclaw、cheapest api for ironclaw、best model for ironclaw 和 ironclaw custom provider 在前十名中各自返回了八个或更多 OpenClaw 结果，其模型排名描述的是另一款产品。
完成设置后，检查第一笔费用
Kunavo 在 https://api.kunavo.com/v1 提供OpenAI 形状的端点，并在 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 成本优化。
常见问题
如何在 IronClaw 中设置自定义供应商？
在 ~/.ironclaw/reborn/config.toml 中编写一个 [llm.default] 槽位，并填写 provider_id、base_url、model 和 api_key_env——这些是槽位结构接受的四个可选字段；对于任何供应商标识，base_url 都会覆盖供应商的 default_base_url，而不只适用于通用供应商。当你的端点没有专用目录条目时，使用 provider_id = "openai_compatible"；IronClaw 的供应商文档列出的适用场景包括 vLLM、LiteLLM、LM Studio 和内部网关。api_key_env 必须是环境变量的名称，因为将实际密钥直接粘贴到那里会在解析文件时被拒绝，而不是被静默接受。`ironclaw config set` 不是执行此操作的工具：配置文档将 `[llm.default]` 列在“直接在 config.toml 中编辑”的部分，并说明 `config set` 只接受具有路由目的地的键，遇到不支持的键会拒绝。编辑文件，或使用 `ironclaw models set-provider`；供应商文档称该命令会将选择作为模型槽位写入 config.toml。然后重启——在执行 `ironclaw service restart` 前不会应用任何更改。已根据 2026 年 9 月 21 日的 nearai/ironclaw main 分支核对。
IronClaw 支持 OpenRouter 吗？
支持，但两种有文档记录的做法彼此不一致。内置供应商目录包含一个专用的 openrouter 条目，使用其自身的 open_router 协议，并以 OPENROUTER_API_KEY 为键；供应商文档称 OpenRouter、Together AI 和 Fireworks 现在都有各自的 provider_id 条目，应直接使用，而不是通过通用适配器。仓库中的 .env.example 仍提供较早的方案，将 LLM_BACKEND 设置为 openai_compatible，并将 LLM_BASE_URL 指向 OpenRouter API。2026 年 9 月 21 日，两个文件都位于 main 分支。优先使用专用 ID；注意 openrouter 条目没有声明基础 URL 环境变量，因此如果要通过代理路由，应改用 config.toml 的 base_url 字段。价格方面，OpenRouter 自己的常见问题页面（openrouter.ai/docs/faq，读取于 2026 年 9 月 21 日）称，其按底层供应商价格原价转付、不加价；银行卡充值收取 5.5%，最低 $0.80；加密货币充值收取 5%；对于超过月度额度的自带密钥用量，按等值 OpenRouter 成本的 5% 收费，同一页面将按量付费额度列为 $25,000。
IronClaw 最好的 API 是什么？
没有唯一赢家；在这里寻找唯一答案尤其容易误导，因为搜索结果会改写这个品牌：在 2026 年 9 月 17 日获取的样本中，“best api for ironclaw”和“cheapest api for ironclaw”在前十名中各自返回了八个或更多 OpenClaw 结果，因此你在这些短语下找到的排名往往描述的是另一款产品。根据 IronClaw 自身代码的行为，可以清晰地区分四条路径。NEAR AI Cloud 是供应商推荐的默认选项，也是内置故障转移实际会切换模型的唯一后端。如果你整天使用同一家供应商并希望使用其原生缓存，直接供应商 API 更合适——IronClaw 仅在两个 Anthropic 传输中发出 Anthropic 的 cache_control 断点，不过 OpenAI 兼容槽位仍会携带 OpenAI 的 prompt_cache_key，因此支持自动前缀缓存的端点并未被排除。如果你希望在多个模型系列之间共用一个密钥和余额，OpenAI 兼容网关更合适，但代价是使用缓冲式而非原生流式传输，并且需要手动输入模型 ID。对于注重隐私且规模较小、无需按请求付费的工作，通过 Ollama 使用本地模型更合适。请根据自己能够承受的限制来选择，而不是根据醒目的费率。
IronClaw 最便宜的 API 是什么？
挂牌价最低与完成任务的总成本最低是不同的说法；对于始终运行的代理，差距会更大，因为心跳计时、例程和后台任务无论你是否正在输入都会计费。作为供应商推荐后端的价格参考，near.ai/pricing 在 2026 年 9 月 21 日列出的最便宜机密文本模型是 GLM 5.3 Flash，每百万 Token 的输入价格为 $0.15、输出价格为 $0.50；最贵的是 Kimi K3，价格分别为 $3.30 和 $16.50；模型费率之外不收平台费。无论选择哪个端点，都应依据供应商自己的用量报告进行预算，而不是依据 IronClaw 显示的成本；后者根据硬编码表计算，对于无法识别的模型 ID 会回退到类似 GPT-4o 的费率。
IronClaw 最好的模型是什么？
在考虑能力之前，IronClaw 会对这个选择施加两个机械性限制，而且两者都由模型 ID 的字面文本决定。图像附件通过与 vision_models.rs 中固定视觉模式列表的子字符串匹配来路由——源码注释警告说，匹配失败会使图像附件被静默丢弃——因此，如果 ID 被重命名或别名改成不符合 claude-sonnet-、gpt-4o、gemini-2 或 pixtral 等形式，就会在没有错误提示的情况下失去图像输入。思考提示更安全：对应的推理模式列表目前为空，因此未知名称、别名和原生思考模型都会回退到直接回答格式。除此之外，应优先选择工具调用表现稳定的模型，因为通过 RigAdapter 路径发送的工具定义会在供应商边界被重写为 OpenAI strict 模式。全部三种行为均来自 2026 年 9 月 21 日的 main 分支。
可以让 IronClaw 指向 Kunavo 吗？
Kunavo 在 https://api.kunavo.com/v1 提供 OpenAI 形状的端点，在 https://api.kunavo.com/v1/messages 提供 Anthropic 形状的端点，分别对应 IronClaw 的 openai_compatible 和 anthropic provider id。这是根据双方文档得出的协议匹配，而非经过测试的集成：Kunavo 没有运行过 IronClaw 到 Kunavo 的请求，也没有声称兼容性已验证。在依赖它之前，请自行检查两个具体事项。openai_compatible 条目设置了 base_url_required，因此没有基础 URL 时槽位无法解析模型。此外，本次研究未确认 IronClaw 在 anthropic 协议下追加的确切路径后缀——ANTHROPIC_BASE_URL 的文档默认值是裸主机 https://api.anthropic.com，这意味着运行时会追加路径，但请先用一个请求确认，再确定配置。Kunavo 的最低充值金额为预付余额 $10。
仓库元数据、providers.json、CONTRACT.md、llm_costs.rs、vision_models.rs、docs/ 目录树、ironclaw.com 和 near.ai/pricing 均于 2026 年 9 月 21 日从 main 分支读取，而非从 1.4.0 发布标签读取。没有任何 IronClaw 请求发送到 Kunavo 端点；此处的所有兼容性表述都来自对双方文档的阅读。Kunavo token 费率来自实时目录，所有美元示例均为说明性的 token 算术。