API参考文档

**本文档引用的文件** - [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist) - [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js) - [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json) - [scaffold.html](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/scaffold.html) - [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json) - [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json) - [NOTICE.md](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/NOTICE.md) - [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

目录

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

简介

本文件为OpenClaw的完整API参考文档，覆盖以下方面：

  • 深度链接协议openclaw://的URL模式、参数传递与回调机制
  • AI模型API（基于Amazon Bedrock）的调用方法、请求格式、响应结构与错误码
  • 权限管理API（系统权限声明与使用说明）
  • 设备识别API（iOS与macOS设备型号映射）
  • 更新系统API（基于Sparkle框架的自动更新机制）

本参考文档以仓库中现有资源为依据，提供可操作的规范说明与最佳实践建议。
在这里插入图片描述

项目结构

OpenClaw应用通过Info.plist声明深度链接协议，通过Resource目录下的JSON与JS文件提供模型、工具显示与设备识别等数据；通过Sparkle框架实现自动更新。

应用包结构

Info.plist
声明openclaw://协议

scaffold.html
状态展示API

models.generated.js
AI模型清单

tool-display.json
工具动作定义

ios-device-identifiers.json
iOS设备映射

mac-device-identifiers.json
macOS设备映射

Sparkle.framework
自动更新

appcast.xml
更新源

图表来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [scaffold.html](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/scaffold.html#L197-L221)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L26)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L1-L82)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L1-L26)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)

核心组件

  • 深度链接协议：在Info.plist中声明openclaw://，用于从外部应用或浏览器唤起OpenClaw并传递参数。
  • AI模型API：通过models.generated.js提供可用模型清单，支持Bedrock Converse Stream API。
  • 工具与动作：tool-display.json定义了各类工具（如browser、nodes、cron等）的动作与参数键。
  • 设备识别：ios-device-identifiers.json与mac-device-identifiers.json提供设备型号到人类可读名称的映射。
  • 更新系统：Sparkle框架通过appcast.xml进行自动更新检查与安装。

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

架构总览

OpenClaw的API层由以下模块组成：

  • 协议层：openclaw://深度链接协议
  • 工具层：工具动作定义与参数键
  • 数据层：模型清单、设备映射
  • 更新层：Sparkle自动更新

更新层

数据层

工具层

协议层

openclaw://<动作>?<参数>

tool-display.json
动作与参数键

models.generated.js
模型清单

ios-device-identifiers.json
iOS映射

mac-device-identifiers.json
macOS映射

Sparkle
SUFeedURL/appcast.xml

图表来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

详细组件分析

深度链接协议 openclaw://

  • 协议声明：在Info.plist中声明CFBundleURLTypes，scheme为openclaw。
  • URL模式：openclaw://<动作>?<参数键>=<参数值>&<参数键>=<参数值>
  • 参数传递：支持查询字符串形式的键值对，参数键集合由各工具定义。
  • 回调机制：应用启动后解析URL，根据动作与参数执行相应流程。
"工具层" "OpenClaw应用" "系统浏览器" "外部应用" "工具层" "OpenClaw应用" "系统浏览器" "外部应用" 打开 "openclaw : //<动作>?<参数>" 调起应用并传递URL 解析URL与参数 匹配动作与参数键 返回执行结果 返回回调结果

图表来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)

AI模型API（Amazon Bedrock Converse Stream）

  • 提供方：amazon-bedrock
  • API类型：bedrock-converse-stream
  • 基础URL：https://bedrock-runtime.us-east-1.amazonaws.com
  • 支持输入类型：text、image
  • 模型清单：models.generated.js中包含多个具体模型条目，每个条目包含id、name、reasoning、input、cost、contextWindow、maxTokens等字段。
  • 请求格式：基于Converse Stream API的流式请求，需携带模型ID、消息历史、推理开关等。
  • 响应结构：流式响应，包含内容块与元数据；错误时返回标准HTTP错误码与错误信息。
  • 错误码：HTTP 4xx/5xx表示请求失败；具体错误原因见响应体或日志。

是

否

开始

解析模型ID与输入

构建Converse请求

发送流式请求到Bedrock

收到响应?

处理流式响应

返回HTTP错误

结束

图表来源

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

章节来源

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

权限管理API

  • 系统权限声明：在Info.plist中声明了多项系统权限用途描述，包括自动化(Automation)、相机、麦克风、屏幕截图、语音识别、通知等。
  • 使用说明：应用在需要时会请求对应权限；用户可在系统设置中管理权限。

是

否

应用请求权限

系统已授权?

允许访问

拒绝访问或引导用户授权

执行受保护操作

提示用户前往系统设置授权

图表来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L53-L70)

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L53-L70)

设备识别API

  • iOS设备映射：ios-device-identifiers.json提供设备型号到人类可读名称的映射。
  • macOS设备映射：mac-device-identifiers.json提供设备型号到一个或多个名称的映射。
  • 使用场景：用于在工具动作中识别目标设备，例如nodes工具的camera_list、camera_clip等。

设备型号标识符

查找映射表

返回人类可读名称

在工具动作中使用

图表来源

  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [NOTICE.md](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/NOTICE.md#L1-L10)

章节来源

  • [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)
  • [NOTICE.md](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/NOTICE.md#L1-L10)

更新系统API（Sparkle）

  • 自动更新：应用内置Sparkle框架，通过SUFeedURL指向appcast.xml进行更新检查。
  • 更新流程：应用启动时检查appcast.xml，下载新版本并提示安装。
  • 版本兼容：更新源由appcast.xml定义，遵循Sparkle的版本比较协议。
"SUFeedURL/appcast.xml" "Sparkle框架" "OpenClaw应用" "SUFeedURL/appcast.xml" "Sparkle框架" "OpenClaw应用" 启动时触发检查 请求更新信息 返回版本信息与下载地址 显示更新提示 用户确认后下载并安装

图表来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L75-L81)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L75-L81)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

依赖关系分析

  • 协议依赖：openclaw://依赖Info.plist中的URL Scheme声明。
  • 工具依赖：工具动作依赖tool-display.json中的动作与参数键定义。
  • 数据依赖：AI模型API依赖models.generated.js中的模型清单。
  • 设备依赖：设备识别依赖ios-device-identifiers.json与mac-device-identifiers.json。
  • 更新依赖：自动更新依赖Sparkle框架与appcast.xml。

Info.plist

openclaw://

tool-display.json

models.generated.js

AI模型API

ios-device-identifiers.json

设备识别API

mac-device-identifiers.json

Sparkle框架

自动更新

图表来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

性能考虑

  • 模型选择：根据上下文窗口与最大令牌数选择合适模型，平衡成本与性能。
  • 输入优化：优先使用文本输入，必要时加入图像输入以提升理解能力。
  • 流式响应：合理处理流式响应，避免阻塞主线程。
  • 设备映射缓存：在频繁使用设备识别时缓存映射表，减少重复解析。

故障排除指南

  • 深度链接无法打开：检查Info.plist中的URL Scheme是否正确；确认系统已注册openclaw://。
  • 工具动作参数无效：核对tool-display.json中的动作与参数键，确保传入的键值存在且类型正确。
  • AI模型调用失败：检查模型ID是否存在于models.generated.js；确认网络可达与认证配置。
  • 设备识别异常：核对设备型号标识符是否在ios-device-identifiers.json或mac-device-identifiers.json中存在映射。
  • 自动更新失败：检查SUFeedURL与appcast.xml的有效性；确认网络连接与签名完整性。

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L21-L31)
  • [tool-display.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/OpenClawKit_OpenClawKit.bundle/tool-display.json#L27-L196)
  • [models.generated.js](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/models.generated.js#L1-L20)
  • [ios-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/ios-device-identifiers.json#L1-L20)
  • [mac-device-identifiers.json](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/mac-device-identifiers.json#L1-L20)
  • [appcast.xml](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/appcast.xml)

结论

本文档基于仓库中的现有资源，提供了OpenClaw的深度链接协议、AI模型API、权限管理、设备识别与更新系统的完整参考。建议在集成时严格遵循参数键与URL模式，并结合工具动作定义与模型清单进行开发与测试。

附录

  • 版本兼容性：应用版本号与构建号在Info.plist中定义；更新源由SUFeedURL与appcast.xml决定。
  • 许可与致谢：设备映射数据来源于第三方开源项目，详见DeviceModels目录下的NOTICE与LICENSE文件。

章节来源

  • [Info.plist](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Info.plist#L19-L33)
  • [NOTICE.md](file://OpenClaw-2026.1.30/OpenClaw.app/Contents/Resources/DeviceModels/NOTICE.md#L1-L10)
# macos # AI智能体 # 人工智能 # 软件工程
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区