开发者空间

扩展 RClaw，打造属于你的生态

🔌

RClaw SDK

SDK 随 Connector 自动注入主题，提供 API 调用、WebSocket 通信、资源加载、UI 组件等全部能力。仅主题开发需要 SDK，工具、技能、模型适配器均无需 SDK。

ApiClient WebSocket ResourceLoader UIManager ComponentManager

🔍 概述

主题是 HTML/CSS/JS 的资源包，由 SDK 的 ResourceLoader 统一加载和调度。主题通过 manifest.json 声明所有资源，按依赖顺序加载。

📁 目录结构

📄 manifest.json

主题清单文件，SDK 据此加载所有 CSS、JS 和 HTML 组件。加载顺序即声明顺序，JS 依赖靠前的先执行。

📄 index.html 入口

主题必须包含等待 SDK 就绪并加载 manifest 的逻辑。路径相对于主题目录（不要包含主题名前缀）。

📄 main.js 初始化

main.js 在所有资源加载完成后执行，只需等待 App 类就绪并调用 init()。推荐使用 App 类模式管理视图切换。

📈 SDK API 速查

ApiClient

  • api.getAgents()
  • api.getSessions(jid)
  • api.getMessages(jid, sessionId, limit, offset)
  • api.getTasks(jid)
  • api.getTokenUsage(jid)
  • api.testModel(provider, apiKey, model, baseUrl)
  • api.saveInitStep(jid, step)
  • api.registerAgentStep(jid, phase)
  • api.getPluginList(type)
  • api.installPlugin(type, id, url)
  • api.getFiles(jid, subpath)
  • api.readFile(jid, filename)
  • api.writeFile(jid, filename, content)

WebSocketClient

  • ws.send(content, jid)
  • ws.sendFile(name, base64, i, total, jid)
  • ws.readFiles(files)
  • ws.on('message', fn)
  • ws.on('process', fn)
  • ws.on('thinking', fn)
  • ws.switchAgent(jid)

ResourceLoader

  • loader.loadManifest(url)
  • loader.loadAll()
  • loader.loadCSS(url)
  • loader.loadJS(url)
  • loader.getComponentHTML(name)
  • loader.loadMedia(theme, path)
  • loader.writeThemeFile(theme, path, content)
  • loader.readThemeFile(theme, path)

UIManager & 工具函数

  • ui.showToast(msg, type, duration)
  • ui.showModal(title, body, footer)
  • ui.confirm(msg, onOK, onCancel)
  • ui.showLoading(el, msg)
  • sdk.formatDate(ts)
  • sdk.escapeHtml(str)
  • sdk.copyToClipboard(text)
  • sdk.setStorage(key, val)
  • sdk.getStorage(key, def)

🔄 全局状态管理

使用 StateManager 管理全局状态，支持 get/set/subscribe。

🎨 CSS 变量

在 variables.css 中定义所有设计 token，主题中直接引用。

📞 向导系统

向导有 8 个步骤（0-7），每步填写后调 saveInitStep() 保存进度，Step 7 点唤醒时调 registerAgentStep() 分步注册。

Step 0 皮肤选择
Step 1 名称 & ID
Step 2 身份设定
Step 3 灵魂
Step 4 规则
Step 5 长期记忆
Step 6 模型配置
Step 7 唤醒

👤 皮肤系统

每个皮肤是一个子目录，包含 skin.json 和 avatar.png。在 manifest.skins 中声明后会被自动预加载。

⚡ 完整示例：最小主题

🔍 概述

RClaw 工具基于 MCP（Model Context Protocol）协议，每个工具是独立的 Node.js 模块，放到 Agent 的 plugins/tools/ 目录后 MCP 服务器自动加载。工具开发无需 SDK。

📁 目录结构

📄 tool.json — 工具元数据

tool.json 供前端展示工具信息，也是向量库搜索的来源。每个字段都有明确用途。

📄 index.js / index.ts — 工具入口

导出 metadata 元数据和 execute 执行函数。execute 接收 params，返回结构化结果。MCP 服务器自动捕获错误并格式化返回。

💻 browser 工具 — action 速查表

browser 是 RClaw 内置的浏览器自动化工具，支持 21 种 action。统一入口，通过 action + payload 参数驱动。

navigate 导航到 URL — payload: {"url": "https://..."}
click 点击页面元素 — payload: {"target": "按钮文字或CSS选择器"}
input_text / type 输入文本 — payload: {"target": "...", "text": "要输入的内容"}
snapshot 获取页面可访问性树（推荐，比截图更适合 LLM）— payload: {}
screenshot 截取页面截图（返回 base64）— payload: {}
fetch 轻量 HTTP 请求（无需打开浏览器）— payload: {"url": "...", "options": {...}}
scroll_up / scroll_down 滚动页面 — payload: {}
scroll_to 滚动到坐标 — payload: {"x": 0, "y": 300}
js_click / js_get_text / js_get_attribute 执行 JS 操作 DOM — payload: {"target": "选择器"}
tabs 标签页管理（list/new/close/select）— payload: {"action": "...", "tabId": "..."}
wait 等待 — payload: {"time": 3} 或 {"text": "等待文字出现"}
list_tools 列出所有可用浏览器工具 — payload: {}
close 关闭浏览器会话（释放资源）— payload: {}

📄 内置工具完整示例

browser 完整工具定义

send_message 完整工具定义

browser/index.ts 核心代码

📥 安装工具

开发完成后，将工具目录放入 Agent 的 plugins/tools/ 目录。MCP 服务器启动时自动扫描并加载所有工具。

💡 也可以通过插件市场一键安装，工具会自动下载并安装到正确目录。

🔍 概述

Skill 是封装好的工作流，由 SKILL.md 文件定义，可被 Agent 通过 load_skill 工具加载执行。放入 skills/ 目录后自动被向量化和检索。无需 SDK。

📁 目录结构

📄 SKILL.md 格式

SKILL.md 由 YAML frontmatter 元数据和 Markdown 执行步骤两部分组成。Agent 加载后逐条解析并执行，支持调用工具和条件分支。

📊 元数据字段说明

name 技能唯一标识（英文小写+下划线，如 fetch_weather）
description 一句话描述，用于向量化和 search_skills 检索
overview 详细概述，说明技能能做什么、关键约束。Agent 通过 search_skills 匹配后，以此做 L2 渐进披露，快速判断是否加载
use_cases 典型使用场景列表（YAML 数组，每项以 - 开头）。补充语义检索关键词，帮助 Agent 判断何时适用

📋 执行步骤语法

执行步骤使用 Markdown 标题（H2/H3）分层，支持工具调用、条件判断、多轮交互。

## 第 N 步 定义一个执行步骤，Agent 按顺序逐条执行，不允许跳过或合并
调用 tool_name 调用指定工具，工具参数以 key: value 格式列出
如果 ... 则 ... 条件分支，根据上一步结果决定下一步行为
然后立即停止 强制停止，后续步骤不再执行（如初始化检查通过时）

📄 真实技能示例

fetch_weather — 查询全球城市天气

setup — Agent 初始化（自动创建定时任务）

📥 安装技能

将技能目录放入 Agent 的 skills/ 目录，系统会自动向量化 SKILL.md 内容，之后可通过 search_skills 发现并通过 load_skill 加载。

🔍 概述

模型适配器是连接 RClaw 与大语言模型的桥梁。每个适配器是一个 Node.js 模块，实现统一的 callModel 接口。无需 SDK，直接在 Agent 工作区编写即可。

📁 目录结构

📄 适配器接口

每个模型适配器必须导出 callModel 函数，接收标准参数，返回统一格式。RClaw 内置了 OpenAI 兼容、Claude、DeepSeek、Gemini 等多种协议的实现参考。

📄 config.json — 适配器配置

config.json 供前端展示适配器信息，也用于默认配置填充。

📄 完整适配器示例

DeepSeek — 国产旗舰大模型（OpenAI 兼容 + Thinking Mode）

OpenAI — GPT 系列（OpenAI 协议）

💬 Thinking / Reasoning 字段透传

不同模型的推理过程字段不同，适配器需统一返回并在文档中注明处理方式。

reasoning_content DeepSeek V4 推理过程（多轮对话必须原样传回，否则 400 错误）
thoughts Gemini 2.5 Thinking 思考内容（不需回传，仅用于展示）

📥 安装模型适配器

将适配器目录放入 Agent 的 plugins/models/ 目录，然后在 Agent 配置中选择对应的模型 Provider。RClaw 会自动加载并使用该适配器。

🔔 插件市场即将开放，届时开发者可一键上传和分发工具、技能包、模型适配器和主题。