YouClaw

English | 简体中文 | 日本語

由多提供商编码代理运行时驱动的桌面 AI 助手

如果 YouClaw 对您有帮助，请为它点亮一颗 GitHub 星标。
更多的星标将帮助更多人发现这个项目。

_{只需点击一下，就能帮助 YouClaw 不断改进。}

---

下载与安装

macOS

从 Releases 页面下载 .dmg 文件，打开后将 YouClaw 拖入“应用程序”文件夹。

同时支持 Apple Silicon (M1/M2/M3/M4) 和 Intel 处理器。

Windows

从 Releases 下载 .exe 安装程序并运行。

Linux

🚧 即将推出 — 敬请期待！

---

特性

• 多代理管理 — 通过 YAML 创建和配置多个 AI 代理，每个代理都有独特的个性、记忆和技能
• 多渠道连接 — 支持 Telegram、钉钉、飞书（Lark）、QQ 和企业微信等平台
• 浏览器自动化 — 内置 Playwright 技能，用于网页交互、爬取和测试
• 定时任务 — 支持 Cron、间隔和一次性任务，并具备自动重试和卡死检测功能
• 持久化内存 — 每个代理都拥有独立的对话记录存储系统
• 技能系统 — 兼容 OpenClaw SKILL.md 格式，采用三层优先级加载机制，支持热重载和技能市场
• 认证机制 — 内置认证系统，便于云端部署
• Web 界面 — 使用 React + shadcn/ui 构建，支持 SSE 流式传输和多语言切换（中文/英文）
• 轻量级桌面应用 — Tauri 2 打包大小约 27 MB（相比之下，Electron 大约为 338 MB），原生系统托盘集成

浏览器配置文件

YouClaw 支持三种浏览器配置文件驱动方式：

• Managed Chromium — 推荐给大多数用户
• Remote CDP — 适用于现有的高级自动化设置
• Extension Relay — 高级本地附加模式，适用于已暴露环回 CDP 端点的浏览器

详细指南：

• 英文：docs/browser-profiles.md
• 简体中文：docs/browser-profiles.zh.md

技术栈

层次	选择
运行时与包管理器	Bun
桌面壳层	Tauri 2 (Rust)
后端	Hono + bun:sqlite + Pino
代理	@mariozechner/pi-coding-agent + @mariozechner/pi-ai
前端	Vite + React + shadcn/ui + Tailwind CSS
通信渠道	grammY (Telegram) · dingtalk-stream (DingTalk) · @larksuiteoapi/node-sdk (Feishu) · QQ · WeCom
定时任务	croner
端到端测试	Playwright

架构

┌──────────────────────────────────────────────────────┐
│                Tauri 2 (Rust Shell)                   │
│   ┌──────────────┐    ┌────────────────────────────┐ │
│   │   WebView     │    │   Bun Sidecar              │ │
│   │  Vite+React   │◄──►  Hono API Server           │ │
│   │  shadcn/ui    │ HTTP│  Multi-provider Agent RT  │ │
│   │               │ SSE │  bun:sqlite               │ │
│   └──────────────┘    └────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
         │                        │
    Tauri Store              EventBus
   (settings)          ┌────────┴────────────┐
                        │                     │
                   Web / API         Multi-Channel
                              ┌───────┼───────┐
                           Telegram DingTalk Feishu
                              QQ    WeCom
                                     │
                              Browser Automation
                               (Playwright)

• 桌面模式：Tauri 启动一个 Bun 侧车进程；WebView 加载前端界面
• Web 模式：Vite 前端 + Bun 后端独立部署
• 三层设计：入口（Telegram/DingTalk/Feishu/QQ/WeCom/Web/API）→ 核心（代理/调度器/内存/技能）→ 存储（SQLite/文件系统）

快速入门前：如果您希望看到 YouClaw 不断进步，请先为其点亮一颗星。
这只是一个小小的点击，却能让项目更容易持续发展。

快速入门（开发）

前提条件

• Bun ≥ 1.1
• Rust（用于 Tauri 桌面构建）
• 您所选提供商的模型 API 密钥

设置步骤

git clone https://github.com/CodePhiliaX/youClaw.git
cd youClaw

# 安装依赖
bun install
cd web && bun install && cd ..

# 配置环境
cp .env.example .env
# 编辑 .env 并设置 MODEL_API_KEY

Web 模式

# 终端 1 — 后端
bun dev

# 终端 2 — 前端
bun dev:web

打开 http://localhost:5173 · API 地址为 http://localhost:62601

桌面模式（Tauri）

bun dev:tauri

构建桌面应用

bun build:tauri

输出路径：src-tauri/target/release/bundle/（DMG / MSI / AppImage）

命令列表

bun dev              # 后端开发服务器（热重载）
bun dev:web          # 前端开发服务器
bun dev:tauri        # Tauri 开发模式（前端 + 后端 + WebView）
bun start            # 生产环境后端
bun typecheck        # TypeScript 类型检查
bun test             # 运行测试
bun build:sidecar    # 编译 Bun 侧车二进制文件
bun build:tauri      # 构建 Tauri 桌面应用
bun build:tauri:fast # 不打包的构建（更快的开发版本）
bun test:e2e         # 运行端到端测试（Playwright）
bun test:e2e:ui      # 带 UI 的端到端测试

环境变量

变量	是否必填	默认值	描述
MODEL_PROVIDER	否	builtin	默认模型提供者或运行模式
MODEL_ID	否	minimax/MiniMax-M2.7-highspeed	默认模型引用
MODEL_API_KEY	是	—	模型 API 密钥
MODEL_BASE_URL	否	—	自定义模型 API 基础 URL
PORT	否	62601	后端服务器端口
DATA_DIR	否	开发环境下为 ./data，桌面生产环境下为 ~/.youclaw	数据存储目录。在开发环境中，若希望使用独立的用户主目录数据目录，可设置为 DATA_DIR=~/.youclaw-dev
LOG_LEVEL	否	info	日志级别
TELEGRAM_BOT_TOKEN	否	—	启用 Telegram 频道
DINGTALK_CLIENT_ID	否	—	钉钉应用客户端 ID
DINGTALK_SECRET	否	—	钉钉应用密钥
FEISHU_APP_ID	否	—	飞书（Lark）应用 ID
FEISHU_APP_SECRET	否	—	飞书（Lark）应用密钥
QQ_BOT_APP_ID	否	—	QQ 机器人应用 ID
QQ_BOT_SECRET	否	—	QQ 机器人密钥
WECOM_CORP_ID	否	—	微信企业号企业 ID
WECOM_CORP_SECRET	否	—	微信企业号企业密钥
WECOM_AGENT_ID	否	—	微信企业号应用 ID
WECOM_TOKEN	否	—	微信企业号回调令牌
WECOM_ENCODING_AES_KEY	否	—	微信企业号回调 AES 密钥
YOUCLAW_WEBSITE_URL	否	—	云服务网站 URL
YOUCLAW_API_URL	否	—	云服务 API URL
MINIMAX_API_KEY	否	—	MiniMax 网络搜索 API 密钥
MINIMAX_API_HOST	否	—	MiniMax API 主机

项目结构

src/
├── agent/          # AgentManager、AgentRuntime、AgentQueue、PromptBuilder
├── channel/        # 多渠道支持
│   ├── router.ts   # 消息路由
│   ├── telegram.ts # Telegram (grammY)
│   ├── dingtalk.ts # 钉钉 (dingtalk-stream)
│   ├── feishu.ts   # 飞书 / Lark (@larksuiteoapi/node-sdk)
│   ├── qq.ts       # QQ
│   └── wecom.ts    # 微信企业号
├── config/         # 环境变量验证、路径常量
├── db/             # bun:sqlite 初始化、CRUD 操作
├── events/         # EventBus（stream/tool_use/complete/error）
├── ipc/            # Agent 进程与主进程之间的文件轮询 IPC
├── logger/         # Pino 日志记录器
├── memory/         # 内存辅助工具，包括根目录下的 MEMORY.md 文件以及每个代理的日志和归档
├── routes/         # Hono API 路由 (/api/*)
├── scheduler/      # Cron/间隔/一次性任务调度器
├── skills/         # 技能加载器、监视器、Frontmatter 解析器
src-tauri/
├── src/            # Rust 主进程（sidecar、窗口、托盘、更新程序）
agents/             # 代理工作区（agent.yaml + 引导文档 + MEMORY.md + 技能）
skills/             # 项目级技能（SKILL.md 格式）
e2e/                # 端到端测试（Playwright）
web/src/
├── pages/          # 聊天、代理、技能、记忆、任务、频道、浏览器配置文件、日志、系统、登录
├── components/     # 布局 + shadcn/ui
├── api/            # HTTP 客户端 + 传输层
├── i18n/           # 国际化（中文 / 英文）

贡献

1. 分支仓库并从 main 创建你的分支
2. 进行更改，并确保 bun typecheck 和 bun test 测试通过
3. 提交拉取请求

许可证

MIT © CHATDATA

YouClaw 快速上手指南

YouClaw 是一款由多提供商编码代理运行时驱动的桌面 AI 助手，支持多智能体管理、多渠道接入（微信、钉钉、飞书等）及浏览器自动化。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS (Intel/Apple Silicon), Windows, 或 Linux
• 运行时依赖：
  • Bun >= 1.1 (推荐国内用户通过镜像安装)
  • Rust (用于构建 Tauri 桌面应用)
• API 密钥：您需要一个大模型提供商的 API Key (如 MiniMax, OpenAI 等)

国内加速建议： 安装 Bun 时若下载缓慢，可配置国内镜像源或使用如下命令：

curl -fsSL https://bun.sh/install | bash
# 若网络受阻，请尝试设置 BUN_INSTALL_MIRROR 或使用国内开源镜像站提供的安装脚本

安装步骤

方式一：直接使用桌面版（推荐普通用户）

1. 访问 Releases 页面。
2. macOS: 下载 .dmg 文件，打开并将 YouClaw 拖入“应用程序”文件夹。
3. Windows: 下载 .exe 安装程序并运行安装。
4. Linux: 目前即将支持，敬请期待。

方式二：源码部署（开发者模式）

适合需要定制功能或贡献代码的开发者。

1. 克隆项目

   git clone https://github.com/CodePhiliaX/youClaw.git
   cd youClaw
   

2. 安装依赖

   bun install
   cd web && bun install && cd ..
   

3. 配置环境变量 复制示例配置文件并编辑：

   cp .env.example .env
   

   使用编辑器打开 .env 文件，填入您的模型 API Key：

   MODEL_API_KEY=your_api_key_here
   # 可选：指定模型提供商和 ID
   # MODEL_PROVIDER=minimax
   # MODEL_ID=minimax/MiniMax-M2.7-highspeed
   

基本使用

1. 启动开发服务

您可以根据需求选择启动 Web 模式或桌面调试模式。

Web 模式（前后端分离启动） 需要开启两个终端窗口：

# 终端 1: 启动后端服务
bun dev

# 终端 2: 启动前端界面
bun dev:web

启动后，在浏览器访问 http://localhost:5173 即可使用，后端 API 运行在 http://localhost:62601。

桌面调试模式（Tauri） 在一个终端中直接启动包含前端的桌面应用：

bun dev:tauri

2. 创建第一个 AI 智能体 (Agent)

YouClaw 的核心是基于 YAML 配置的多智能体系统。

1. 在项目根目录下的 agents/ 文件夹中创建一个新的文件夹，例如 my-assistant。
2. 在该文件夹内创建 agent.yaml 文件，定义智能体的个性与技能：

   name: my-assistant
   description: 我的个人编程助手
   personality: 你是一位经验丰富的资深工程师，擅长解决复杂问题。
   skills:
     - browser # 启用内置的浏览器自动化技能
   

3. （可选）创建 MEMORY.md 文件以保存该智能体的长期记忆。
4. 重启服务或在 Web UI 的 "Agents" 页面刷新，即可看到新创建的智能体。

3. 连接即时通讯渠道 (可选)

若需将智能体接入钉钉、飞书或微信，请在 .env 文件中配置对应的凭证，例如接入钉钉：

DINGTALK_CLIENT_ID=your_dingtalk_client_id
DINGTALK_SECRET=your_dingtalk_secret

配置完成后重启服务，智能体即可在相应的 IM 软件中响应消息。

4. 构建生产版桌面应用

完成开发和测试后，可打包为本地安装包：

bun build:tauri

构建产物位于 src-tauri/target/release/bundle/ 目录下（包含 .dmg, .msi 或 AppImage 文件）。