爪爪

English | 中文

## 为什么需要 RivonClaw？ [OpenClaw](https://github.com/openclaw/openclaw) 是一个强大的 Agent 运行时——但它是为工程师设计的。使用它意味着编辑配置文件、管理进程、在终端中操作 API 密钥。对于非程序员（设计师、运营、财务、小企业主）来说，这个门槛太高了。 RivonClaw 把 OpenClaw 封装成一个**人人都能用的桌面应用**：安装后从系统托盘启动，通过本地 Web 面板管理一切。用自然语言写规则而不是写代码，点几下就能配置 LLM 服务商和消息通道，让 Agent 在交互中逐渐理解你的偏好。无需终端。 **一句话：** OpenClaw 是引擎，RivonClaw 是驾驶舱。 ## 功能特性 - **自然语言规则**：用自然语言编写规则——它们会编译为策略、守卫或技能，并立即生效（无需重启） - **多服务商 LLM 支持**：支持 20+ 个服务商（OpenAI、Anthropic、Google Gemini、DeepSeek、智谱/Z.ai、Moonshot/Kimi、通义千问、Groq、Mistral、xAI、OpenRouter、MiniMax、Venice AI、小米/MiMo、火山引擎/豆包、Amazon Bedrock、NVIDIA NIM 等），另有订阅/编程计划（Claude、Gemini、智谱编程、通义编程、Kimi Code、MiniMax 编程、火山编程）以及 Ollama 本地模型支持 - **OAuth 与订阅计划**：使用 Google 账号登录即可免费使用 Gemini，或连接 Claude/Anthropic 订阅——无需 API 密钥。自动检测或安装 CLI 凭据 - **按服务商配置代理**：为每个 LLM 服务商或 API 密钥配置 HTTP/SOCKS5 代理，支持自动路由和热重载——对受限地区至关重要 - **多账号通道支持**：通过界面配置 Telegram、WhatsApp、Discord、Slack、Google Chat、Signal、iMessage、飞书/Lark、LINE、Matrix、Mattermost、Microsoft Teams 等，密钥安全存储（Keychain/DPAPI） - **Token 用量追踪**：按模型和服务商实时统计，自动从 OpenClaw 会话文件刷新 - **语音消息支持**：根据地区自动选择合适的语音识别服务（Groq / 火山引擎） - **可视化权限控制**：通过界面控制文件读写权限 - **零重启更新**：API 密钥、代理和通道变更通过热重载立即生效——无需重启网关 - **本地优先与隐私保护**：所有数据保存在本地；密钥永不以明文存储 - **与 Agent 对话**：基于 WebSocket 的实时聊天，支持 Markdown 渲染、Emoji 选择器、图片附件、模型切换和持久化对话历史 - **技能市场**：内置技能市场，可浏览、搜索和一键安装社区技能，轻松管理已安装技能 - **自动更新**：客户端更新检查器，静态清单托管 - **隐私优先遥测**：可选的匿名使用分析——不收集个人身份信息 ### 文件权限的工作原理 RivonClaw 通过 OpenClaw 插件在工具调用*执行前*拦截并验证文件路径。具体保护范围： - **文件访问工具**（`read`、`write`、`edit`、`image`、`apply-patch`）：完全受保护——路径会根据你配置的权限进行验证 - **命令执行工具**（`exec`、`process`）：验证工作目录，但无法检查命令字符串*内部*的路径（如 `cat /etc/passwd`） **覆盖率**：约 85-90% 的文件访问场景。如需最大安全性，可考虑通过规则限制或禁用 `exec` 工具。 **技术说明**：文件权限插件使用 OpenClaw 的 `before_tool_call` 钩子——无需修改上游源代码，因此 RivonClaw 可以干净地拉取 OpenClaw 更新。 ## 环境要求 | 工具 | 版本 | | ------- | ---------- | | Git | 任意 | | Node.js | >= 24 | | pnpm | 10.6.2 | ## 快速开始 ```bash # 1. 克隆仓库 git clone https://github.com/nicepkg/rivonclaw.git cd rivonclaw # 2. 克隆并构建内置的 OpenClaw 运行时（自动应用 vendor 补丁） ./scripts/setup-vendor.sh # 3. 安装工作区依赖并构建 pnpm install pnpm build # 4. 以开发模式启动 pnpm --filter @rivonclaw/desktop dev ``` 启动 Electron 托盘应用后，它会拉起 OpenClaw 网关并在动态分配的本地端口上提供管理面板。 ## 仓库结构 ``` rivonclaw/ ├── apps/ │ ├── desktop/ # Electron 托盘应用（主进程） │ └── panel/ # React 管理界面（由 desktop 提供服务） ├── packages/ │ ├── core/ # 共享类型、Zod schemas、API 契约、MST 模型 │ ├── device-id/ # 设备指纹（用于设备标识） │ ├── gateway/ # 网关生命周期、配置写入、密钥注入、OAuth 流程 │ ├── logger/ # 结构化日志（tslog），支持 DEBUG_* 开关 │ ├── plugin-sdk/ # RivonClaw 自研 OpenClaw 插件的薄 SDK │ ├── storage/ # SQLite 持久化（better-sqlite3） │ ├── rules/ # 规则编译 & Skill 文件写入 │ ├── secrets/ # Keychain / DPAPI / 文件密钥存储 │ ├── updater/ # 自动更新客户端 │ ├── stt/ # 语音转文字抽象层（Groq / 火山引擎） │ ├── proxy-router/ # HTTP CONNECT 代理复用器（用于受限地区） │ ├── telemetry/ # 隐私优先的匿名分析客户端 │ └── policy/ # 策略注入器 & 守卫评估器逻辑 ├── extensions/ │ ├── rivonclaw-policy/ # OpenClaw 策略注入插件壳 │ ├── rivonclaw-tools/ # 仅限所有者的自定义工具插件 │ ├── rivonclaw-file-permissions/ # 文件访问控制插件 │ ├── rivonclaw-mobile-chat-channel/ # 移动端消息中继插件 │ ├── rivonclaw-browser-profiles-tools/ # 浏览器 Profile CDP 工具集成 │ ├── rivonclaw-capability-manager/ # 工具能力 / Surface 可用性 │ ├── rivonclaw-event-bridge/ # 将网关 agent 事件桥接到 Chat UI │ └── rivonclaw-search-browser-fallback/ # 网页搜索的无头浏览器兜底 ├── scripts/ │ ├── test-local.sh # 本地测试流程（构建 + 单元测试 + E2E 测试） │ ├── publish-release.sh # 发布 GitHub Release 草稿 │ └── rebuild-native.sh # 预编译 better-sqlite3（Node.js + Electron） └── vendor/ └── openclaw/ # 内置的 OpenClaw（gitignored） ``` ## 工作区 Monorepo 使用 pnpm workspaces（`apps/*`、`packages/*`、`extensions/*`），通过 [Turbo](https://turbo.build) 编排构建。所有包通过 [tsdown](https://github.com/nicolo-ribaudo/tsdown) 输出 ESM。 ### 应用 | 包 | 说明 | | ------------------------ | -------------------------------------------------------------------------------------- | | `@rivonclaw/desktop` | Electron 40 托盘应用。管理网关生命周期，在动态端口上托管面板服务，数据存储于 SQLite。 | | `@rivonclaw/panel` | React 19 + Vite 6 SPA。包含聊天、规则、服务商、通道、权限、语音转文字、用量、技能市场页面，以及首次启动引导向导。 | ### 扩展 | 包 | 说明 | | -------------------- | -------------------------------------------------------------------------------------------- | | `@rivonclaw/rivonclaw-policy` | 薄 OpenClaw 插件壳，将策略注入接入网关的 `before_agent_start` 钩子。 | | `@rivonclaw/rivonclaw-tools` | 仅限所有者的自定义工具插件（如系统控制、桌面集成）。 | | `@rivonclaw/rivonclaw-file-permissions` | 通过在工具调用执行前拦截和验证来强制执行文件访问权限。 | | `@rivonclaw/rivonclaw-mobile-chat-channel` | 移动端 PWA 消息中继 — 通过 WebSocket 将移动端聊天客户端桥接到网关。 | | `@rivonclaw/rivonclaw-browser-profiles-tools` | 基于 CDP 的浏览器 Profile 工具集成。 | | `@rivonclaw/rivonclaw-capability-manager` | 工具能力和 Surface 可用性解析器。 | | `@rivonclaw/rivonclaw-event-bridge` | 将部分网关 agent 事件镜像到 Chat UI 流。 | | `@rivonclaw/rivonclaw-search-browser-fallback` | 当搜索 API 失败时使用无头浏览器兜底。 | ### 包 | 包 | 说明 | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `@rivonclaw/core` | Zod 校验类型：`Rule`、`ChannelConfig`、`PermissionConfig`、`ModelConfig`，LLM 服务商定义（20+ 服务商，含订阅/编程计划及 Ollama），区域感知默认值。 | | `@rivonclaw/gateway` | `GatewayLauncher`（支持指数退避的启动/停止/重启）、配置写入器、从系统密钥链注入密钥、Gemini CLI OAuth 流程、认证配置同步、Skills 目录监听实现热重载。 | | `@rivonclaw/logger` | 基于 tslog 的日志模块。写入 `~/.rivonclaw/logs/`。通过 `createQuietLogger` 支持 `DEBUG_*` 环境变量开关（见 [Debug 开关](#debug-开关)）。 | | `@rivonclaw/plugin-sdk` | RivonClaw 自研 OpenClaw 插件（`extensions/` 下）共享的运行时 helper 和类型。 | | `@rivonclaw/storage` | 基于 better-sqlite3 的 SQLite 存储。包含规则、产物、通道、权限、设置的 Repository，内置迁移系统。数据库位于 `~/.rivonclaw/db.sqlite`。 | | `@rivonclaw/rules` | 规则编译、Skill 生命周期（激活/停用）、Skill 文件写入器（将规则具象化为 OpenClaw 的 SKILL.md 文件）。 | | `@rivonclaw/secrets` | 平台感知的密钥存储。macOS Keychain、文件回退方案、测试用内存存储。 | | `@rivonclaw/updater` | 检查网站上的 `update-manifest.json`，通知用户新版本。 | | `@rivonclaw/device-id` | 设备指纹（硬件 UUID 的 SHA-256 哈希），用于设备标识和配额管理。 | | `@rivonclaw/stt` | 语音转文字服务商抽象层（国际用 Groq，国内用火山引擎）。 | | `@rivonclaw/proxy-router` | HTTP CONNECT 代理，根据服务商域名配置将请求路由到不同的上游代理。 | | `@rivonclaw/telemetry` | 隐私优先的遥测客户端，支持批量上传和重试机制；不收集个人身份信息。 | | `@rivonclaw/policy` | 策略注入器 & 守卫评估器 — 将策略编译为提示词片段，将守卫编译为执行检查。 | ## 脚本 大部分根目录脚本通过 Turbo 运行： ```bash pnpm build # 构建所有包（遵循依赖图） pnpm dev # 以开发模式运行 desktop + panel pnpm test # 运行所有测试（vitest） pnpm lint # 检查所有包（oxlint） pnpm format # 检查格式（oxfmt，直接运行） pnpm format:fix # 自动修复格式（oxfmt，直接运行） ``` ### 单包命令 ```bash # Desktop pnpm --filter @rivonclaw/desktop dev # 以开发模式启动 Electron pnpm --filter @rivonclaw/desktop build # 打包主进程 pnpm --filter @rivonclaw/desktop test # 运行 desktop 测试 pnpm --filter @rivonclaw/desktop dist:mac:arm64 # 构建 macOS DMG（arm64） pnpm --filter @rivonclaw/desktop dist:mac:x64 # 构建 macOS DMG（x64） pnpm --filter @rivonclaw/desktop dist:win # 构建 Windows NSIS 安装包 # Panel pnpm --filter @rivonclaw/panel dev # Vite 开发服务器 pnpm --filter @rivonclaw/panel build # 生产构建 # 任意包 pnpm --filter @rivonclaw/core test pnpm --filter @rivonclaw/gateway test ``` ## 架构 ``` ┌─────────────────────────────────────────┐ │ 系统托盘（Electron 主进程） │ │ ├── GatewayLauncher → vendor/openclaw │ │ ├── 面板 HTTP 服务器（动态端口） │ │ │ ├── 静态文件（panel dist/） │ │ │ └── REST API（/api/*） │ │ ├── SQLite 存储 │ │ ├── 认证配置同步 │ │ └── 自动更新 │ └─────────────────────────────────────────┘ │ ▲ ▼ │ ┌─────────────┐ ┌─────────────────┐ │ OpenClaw │ │ 面板（React） │ │ 网关进程 │ │ 面板（React） │ └─────────────┘ └─────────────────┘ ``` 桌面应用以**纯托盘模式**运行（macOS 下隐藏 Dock 图标）。它会： 1. 从 `vendor/openclaw/` 启动 OpenClaw 网关 2. 在动态分配的本地端口上提供面板 UI 和 REST API 3. 将网关配置和认证配置写入 `~/.rivonclaw/openclaw/` 4. 运行时从系统密钥链注入密钥（API 密钥 + OAuth 令牌） 5. 监听 `~/.rivonclaw/openclaw/skills/` 目录以热重载规则生成的 Skill 文件 6. 关闭时将刷新后的 OAuth 令牌同步回密钥链 ### REST API Desktop ↔ Panel 的全部 REST 端点、SSE 流及路径参数以单一类型化契约声明在 [`packages/core/src/api/api-contract.ts`](packages/core/src/api/api-contract.ts)。Desktop（路由注册）和 Panel（`fetchJson` / `EventSource`）都从该文件导入，作为唯一事实来源。 当前端点按类别分布如下： | 类别 | 示例 | | ---------------------- | ---------------------------------------------------------------------------- | | 鉴权 & 会话 | `/api/auth/login`、`/api/auth/refresh`、`/api/auth/session` | | 规则 & 技能 | `/api/rules`、`/api/skills` | | 服务商 & OAuth | `/api/providers`、`/api/provider-keys`、`/api/oauth/*` | | 通道 & 移动聊天 | `/api/channels/*`、`/api/channels/accounts`、`/api/mobile/*` | | 浏览器 Profile | `/api/browser-profiles/*`（托管启动/连接、会话、代理测试） | | 客服桥接 | `/api/cs-bridge/*`（绑定、升级、对话） | | 聊天 & 流 | `/api/chat/events`（SSE）、`/api/chat-sessions` | | 设置 & 状态 | `/api/settings`、`/api/agent-settings`、`/api/status`、`/api/doctor/*` | | 用量、遥测、STT | `/api/usage`、`/api/telemetry`、`/api/stt` | | 应用生命周期 | `/api/app/update/*`、`/api/app/changelog`、`/api/app/api-base-url` | | 云端 GraphQL 代理 | `/api/cloud/graphql`、`/api/cloud/*` | ### 数据目录 下列为默认路径；每个路径都可通过对应的 `RIVONCLAW_*` / `OPENCLAW_*` 环境变量覆写（详见 `packages/core/src/node-utils/paths.ts`）。 | 路径 | 用途 | | ----------------------------------------------------- | -------------------------------------------------------- | | `~/.rivonclaw/db.sqlite` | SQLite 数据库（规则、通道、服务商 Key、设置） | | `~/.rivonclaw/logs/` | 应用日志（5 MB 滚动） | | `~/.rivonclaw/secrets/` | 文件密钥存储（非 macOS 回退方案） | | `~/.rivonclaw/openclaw/` | OpenClaw 状态目录 | | `~/.rivonclaw/openclaw/openclaw.json` | 网关配置（由 `@rivonclaw/gateway` 写入） | | `~/.rivonclaw/openclaw/agents//sessions/` | Agent 会话日志（JSONL） | | `~/.rivonclaw/openclaw/skills/` | 规则具象化产生的 Skill 文件 | | `~/.rivonclaw/openclaw/credentials/` | OAuth 凭据缓存（Gemini CLI、Codex） | ## 构建安装包 `dist:mac` 和 `dist:win` 脚本会在打包前自动剪裁并打包 `vendor/openclaw`。通过 esbuild 打包和 node_modules 裁剪来减少 vendor 文件数量和体积。Vendor 通过 `extraResources` 复制进安装包——源目录 `vendor/openclaw/` 不会被修改。 ### macOS（DMG，按架构分别构建） ```bash pnpm build pnpm --filter @rivonclaw/desktop dist:mac:arm64 # Apple Silicon pnpm --filter @rivonclaw/desktop dist:mac:x64 # Intel # 输出：apps/desktop/release/RivonClaw--arm64.dmg # apps/desktop/release/RivonClaw--x64.dmg ``` 代码签名和公证需设置以下环境变量： ```bash CSC_LINK=<.p12 证书路径> CSC_KEY_PASSWORD=<证书密码> APPLE_ID=<你的 Apple ID> APPLE_APP_SPECIFIC_PASSWORD=<应用专用密码> APPLE_TEAM_ID=<团队 ID> ``` ### Windows（NSIS 安装包，x64） ```bash pnpm build pnpm --filter @rivonclaw/desktop dist:win # 输出：apps/desktop/release/RivonClaw.Setup..exe # apps/desktop/release/RivonClaw--portable.exe ``` 支持从 macOS 交叉编译（NSIS 无需 Wine）。Windows 代码签名需设置： ```bash CSC_LINK=<.pfx 证书路径> CSC_KEY_PASSWORD=<证书密码> ``` ### 本地测试 `scripts/test-local.sh` 脚本运行完整的本地测试流程： ```bash ./scripts/test-local.sh 1.2.8 # 完整流程 ./scripts/test-local.sh --skip-tests # 仅构建 + 打包 ``` 它会： 1. 预编译 Node.js + Electron 的原生模块 2. 构建所有工作区包 3. 运行单元测试和 E2E 测试（开发 + 生产模式） 4. 打包应用（electron-builder --dir） ### 发布 CI 构建完成且本地测试通过后： ```bash ./scripts/publish-release.sh # 发布草稿 Release ``` ## 注意：better-sqlite3 原生模块 better-sqlite3 运行在两个 ABI 不兼容的运行时下（Node.js 用于测试，Electron 用于应用）。`scripts/rebuild-native.sh` 会为两者编译并将二进制文件放在 `lib/binding/` 中。这通过根目录的 `postinstall` 钩子自动运行。 如果 Electron 升级后测试出现 `NODE_MODULE_VERSION` 不匹配错误： ```bash bash scripts/rebuild-native.sh # 为两种 ABI 重新编译 ``` ## 测试 测试使用 [Vitest](https://vitest.dev/)。运行所有测试： ```bash pnpm test ``` 运行指定包的测试： ```bash pnpm --filter @rivonclaw/storage test pnpm --filter @rivonclaw/gateway test ``` ## Debug 开关 噪音较多的模块默认只输出 INFO+ 级别日志，只有当对应的 `DEBUG_*` 环境变量被设为 `1` 时才会打开 DEBUG 输出。所有开关集中注册在 [`packages/logger/src/debug-flags.ts`](packages/logger/src/debug-flags.ts)，通过 `createQuietLogger(name, DEBUG_FLAGS.X)` 消费。 | 开关 | 启用 DEBUG 的模块 | | --------------- | ------------------------------------------------------------ | | `DEBUG_PROXY` | `proxy-router`、`proxy-manager`（系统代理发现、上游连接） | | `DEBUG_SECRETS` | `secrets:keychain`、`gateway:secret-injector`（密钥读取、环境变量注入） | ```bash DEBUG_PROXY=1 pnpm dev # 追踪代理路由 DEBUG_SECRETS=1 pnpm dev # 追踪密钥读取 DEBUG_PROXY=1 DEBUG_SECRETS=1 pnpm dev # 两个都开 ``` 新增开关的步骤：在 `DEBUG_FLAGS` 里加一个条目，然后把相关的 `createLogger(...)` 改成 `createQuietLogger(name, DEBUG_FLAGS.NEW_FLAG)`。 ## 代码风格 - **Lint**：[oxlint](https://oxc-project.github.io/)（基于 Rust，速度快） - **格式化**：[oxfmt](https://oxc-project.github.io/)（基于 Rust，速度快） - **TypeScript**：严格模式，ES2023 目标，NodeNext 模块解析 ```bash pnpm lint pnpm format # 检查 pnpm format:fix # 自动修复 ``` ## 社区讨论 - **海外 Telegram 群**：[加入讨论群](https://t.me/+IN_vVZxckbgxODIx) - **中国大陆微信群**：扫码加入 微信讨论群二维码 ## 许可证 详见 [LICENSE](LICENSE)。