解密OpenClaw系列11-OpenClaw AI模型API

AI模型API

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录
    

简介

本文件为AI模型API的完整参考文档，基于仓库中的自动生成模型清单，系统梳理了支持的AI模型接口（Claude、GPT、Llama系列等），并给出请求与响应的数据结构规范、成本计算与上下文窗口管理机制。文档同时提供调用示例与最佳实践建议，帮助开发者在不同场景下高效、稳定地集成与使用。

项目结构

该仓库中与AI模型API直接相关的核心文件位于资源目录中，主要包括：

• 模型清单：models.generated.js（自动维护的模型能力、成本、上下文窗口等）
• 工具显示配置：tool-display.json（工具与动作的可视化与细节键位）
• 设备型号映射：ios-device-identifiers.json、mac-device-identifiers.json（设备识别与兼容性）

图表来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L38)
• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)
• [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L177)
• [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L215)

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L38)
• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)
• [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L177)
• [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L215)

核心组件

• 模型清单（MODELS）：集中定义各提供商的模型能力，包括：
  • 基础信息：id、name、provider、baseUrl、api
  • 输入类型：input（text、image等）
  • 推理能力：reasoning（是否具备推理能力）
  • 成本结构：cost（输入单价、输出单价、缓存读写单价）
  • 上下文与输出限制：contextWindow、maxTokens
• 工具显示配置：用于前端或工具面板展示工具标题、表情符号、动作标签及详情键位
• 设备型号映射：用于识别iOS与macOS设备，辅助兼容性判断与功能适配

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L38)
• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)

架构总览

AI模型API的调用流程可抽象为以下序列：

[此图为概念性流程图，不直接映射具体源码文件]

详细组件分析

模型清单结构与字段说明

• 模型对象字段
  • id：模型唯一标识符
  • name：模型名称
  • provider：提供商（如 amazon-bedrock、anthropic、openai 等）
  • baseUrl：提供商基础URL
  • api：API类型（如 bedrock-converse-stream、anthropic-messages、openai-responses 等）
  • reasoning：是否具备推理能力
  • input：支持的输入类型数组（text、image等）
  • cost：成本结构（输入单价、输出单价、缓存读单价、缓存写单价）
  • contextWindow：上下文窗口大小
  • maxTokens：最大生成tokens
• 示例路径
  • [Claude Haiku 3.5（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L4-L21)
  • [Claude Sonnet 3.5（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L22-L38)
  • [Claude Haiku 3（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L56-L72)
  • [Claude Opus 3（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L73-L89)
  • [Claude Sonnet 3（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L90-L106)
  • [Llama 3.1 70B Instruct（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L328-L344)
  • [Llama 3.1 8B Instruct（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L345-L361)
  • [GPT-4o（Azure OpenAI Responses）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1403-L1419)
  • [GPT-5.2 Pro（Azure OpenAI Responses）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1726-L1742)
  • [Gemini 1.5 Flash（Google）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L2270-L2286)
  • [Groq Code Fast 1（GitHub Copilot）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L2249-L2267)

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L4-L21)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L22-L38)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L56-L72)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L73-L89)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L90-L106)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L328-L344)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L345-L361)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1403-L1419)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1726-L1742)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L2270-L2286)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L2249-L2267)

请求格式规范

• 模型选择
  • 使用模型ID在清单中定位提供商、API类型与基础URL
  • 参考路径：[模型清单入口](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L3-L940)
• 输入数据结构
  • 文本输入：按 provider/input 支持情况传入
  • 图像输入：部分模型支持 image 类型
  • 示例路径：
    • [支持 text 的模型示例](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L107-L140)
    • [支持 text/image 的模型示例](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L38)
• 参数选项与配置
  • 不同 provider 的 API 类型（如 bedrock-converse-stream、anthropic-messages、openai-responses 等）决定请求体与头部差异
  • 参考路径：[API类型分布](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L940)

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L940)

响应数据结构

• 流式/非流式响应
  • 具体响应格式取决于所选 API 类型（provider/api）
  • 建议在客户端解析时保留原始响应以便调试与扩展
• 元数据
  • 上下文窗口与最大生成tokens：用于控制与优化
  • 成本：用于计费与预算控制
• 错误信息
  • 建议统一捕获提供商返回的错误码与消息，结合模型ID进行日志追踪

[本节为通用说明，未直接分析具体源码文件]

API调用示例与最佳实践

• Claude（Anthropic）
  • 场景：多模态对话、推理增强
  • 最佳实践：优先选择具备 reasoning 的模型；合理设置 maxTokens 以平衡质量与成本
  • 示例路径：
    • [Claude Haiku 3.5（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L4-L21)
    • [Claude Sonnet 3.5（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L22-L38)
• GPT系列（OpenAI/Azure OpenAI）
  • 场景：通用对话、代码生成、多模态
  • 最佳实践：根据任务复杂度选择合适尺寸模型；注意上下文窗口上限
  • 示例路径：
    • [GPT-4o（Azure OpenAI）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1403-L1419)
    • [GPT-5.2 Pro（Azure OpenAI）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1726-L1742)
• Llama系列（Meta，Bedrock）
  • 场景：企业级部署、隐私敏感任务
  • 最佳实践：根据硬件与延迟要求选择合适规模的Llama模型
  • 示例路径：
    • [Llama 3.1 70B Instruct（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L328-L344)
    • [Llama 3.1 8B Instruct（Bedrock）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L345-L361)
• Gemini（Google）
  • 场景：多模态理解、快速推理
  • 最佳实践：利用高上下文窗口模型处理长文档；注意成本控制
  • 示例路径：
    • [Gemini 1.5 Flash（Google）](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L2270-L2286)

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L4-L21)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L22-L38)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L328-L344)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L345-L361)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1403-L1419)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1726-L1742)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L2270-L2286)

成本计算接口与令牌计费机制

• 成本结构
  • 输入单价、输出单价、缓存读单价、缓存写单价
  • 单价单位与货币：以模型清单中的 cost 字段为准
• 计费流程
  • 在请求完成后统计实际输入/输出tokens，乘以对应单价得出费用
  • 可选：计入缓存读写消耗
• 优化建议
  • 合理设置 maxTokens，避免超限重试
  • 使用更高上下文窗口但更经济的模型以降低单位成本
  • 对重复查询启用缓存策略（若提供商支持）

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L12-L20)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L30-L38)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L48-L55)

上下文窗口管理

• 上下文窗口（contextWindow）
  • 决定单次请求可承载的最大上下文长度
• 最大生成tokens（maxTokens）
  • 控制生成长度，避免超出限额
• 管理策略
  • 长文档：分段处理或采用更高上下文窗口模型
  • 多轮对话：精简历史消息，保留关键摘要

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L18-L21)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L36-L38)
• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L52-L55)

依赖关系分析

• 模型清单对调用链的影响
  • provider/api/baseUrl 决定请求构造方式
  • input/reasoning 决定输入类型与推理能力
  • cost/contextWindow/maxTokens 决定计费与容量规划
• 工具显示配置与设备映射
  • tool-display.json 用于界面展示与交互
  • 设备映射用于运行环境适配与兼容性检查

图表来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L940)
• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)
• [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L177)
• [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L215)

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L940)
• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)
• [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L177)
• [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L215)

性能考量

• 选择合适的模型
  • 高上下文窗口模型适合长文档；小模型适合低延迟场景
• 控制生成长度
  • 合理设置 maxTokens，避免不必要的开销
• 成本优化
  • 利用缓存与复用策略减少重复计算
  • 在保证质量前提下选择性价比更高的模型

[本节为通用指导，未直接分析具体源码文件]

故障排查指南

• 常见问题
  • 模型ID不存在：检查模型清单中的 id 是否正确
  • 上下文超限：缩短输入或改用更高上下文窗口模型
  • 成本异常：核对 cost 字段与实际tokens统计
• 日志与追踪
  • 记录请求ID、模型ID、输入/输出tokens与费用
  • 结合工具显示配置中的 detailKeys 进行问题定位

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L940)
• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)

结论

通过模型清单的标准化定义，本项目实现了对多提供商、多模型的统一接入与管理。开发者可依据模型的能力与成本特性，在不同业务场景中灵活选择最优方案，并结合上下文窗口与计费机制实现高效、可控的AI服务集成。

[本节为总结性内容，未直接分析具体源码文件]

附录

A. 模型清单字段速查

• 基础信息：id、name、provider、baseUrl、api
• 能力：input（text、image）、reasoning
• 成本：cost（输入、输出、缓存读、缓存写）
• 限制：contextWindow、maxTokens

章节来源

• [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L940)

B. 工具显示配置键位参考

• fallback.detailKeys：默认详情键位集合
• tools.*.detailKeys：各工具详情键位
• tools..actions..detailKeys：各动作详情键位

章节来源

• [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L198)

C. 设备型号映射参考

• iOS设备型号映射：用于识别模拟器与真机设备
• macOS设备型号映射：用于识别不同代际与规格的Mac设备

章节来源

• [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L177)
• [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L215)