@idao-cube/bunclaw

v0.3.0

Published

5 days ago

Pure Bun local agent control plane inspired by OpenClaw

Downloads

2,129

0High
0Medium
0Low

daoxin

bun agent gateway openclaw cli

BunClaw

纯 Bun 的本地 Agent 控制面，设计灵感来自 OpenClaw。
A pure-Bun local agent control plane inspired by OpenClaw.

为什么是 BunClaw

BunClaw 是一个面向本地开发与自动化的 Agent 内核，目标是：

保留 OpenClaw 的核心思想（Gateway 控制面、会话一等对象、工具调用循环、流式事件）
收敛实现范围，先把单机可用性做扎实
全面去掉 Node 依赖链，仅使用 Bun 内建能力

适合人群：

需要一个可控、可二开、可本地部署的 AI 助手内核
希望通过 WebSocket 协议接入自定义前端/终端客户端
想要“先本地跑通、再逐步扩展渠道/插件/设备能力”

安装方式（开箱即用）

1) npm 安装（推荐）

npm i -g @idao-cube/bunclaw

安装后可直接使用：

bunclaw --help
bunclaw onboard
bunclaw gateway

说明：包地址在 npm 组织 idao-cube 下。
https://www.npmjs.com/org/idao-cube

2) 二进制安装（无需 npm）

从 GitHub Releases 下载对应平台二进制后执行：

# Windows
./bunclaw-bun-windows-x64.exe gateway

# Linux
chmod +x ./bunclaw-bun-linux-x64
./bunclaw-bun-linux-x64 gateway

# macOS
chmod +x ./bunclaw-bun-darwin-arm64
./bunclaw-bun-darwin-arm64 gateway

2.1) Linux/macOS 一键安装（GitHub Releases）

发布后可直接执行安装脚本（自动识别平台与架构）：

curl -fsSL https://github.com/idao-cube/bunclaw/releases/latest/download/install-unix.sh | sh

指定版本示例：

curl -fsSL https://github.com/idao-cube/bunclaw/releases/latest/download/install-unix.sh | sh -s -- v0.2.5

说明：

优先安装到 /usr/local/bin（可写时）
无权限时自动回退到 ~/.local/bin
回退场景会自动写入 shell rc（如 ~/.bashrc / ~/.zshrc）以补全 PATH

3) MSI 安装（Windows）

从 Releases 下载 BunClaw-<version>-x64.msi，双击安装后使用：

bunclaw --help

OpenClaw 对比

| 项目 | OpenClaw | BunClaw | | --- | --- | --- | | 技术栈 | Node/TS 生态 | 纯 Bun | | 控制面 | Gateway + 多模块 | Gateway + Agent + CLI（v1） | | 渠道接入 | 丰富（IM/设备等） | 本地 Web UI + CLI | | 目标 | 全栈 Agent 平台 | 轻量、可维护、可扩展内核 | | 默认部署 | 可远程与组网 | 本地单用户优先 |

核心特性

纯 Bun：Bun.serve / WebSocket / bun:sqlite / Bun.spawn / fetch
控制面协议：connect + req/res/event 三类帧
幂等保障：agent.run、message.send 支持 idemKey
会话模型：SQLite 持久化 + JSONL 事件流
工具策略：profile + allow + deny（deny 优先）
Agent 循环：OpenAI-compatible + tool call 回填迭代
内置 UI：聊天、日志、系统配置、统计（PC/H5 自适应）
打包发布：单文件二进制 + GitHub Actions 多平台构建

架构（v1）

CLI / Web UI
     |
 WebSocket (connect, req/res/event)
     |
   Gateway  -------------------> Event JSONL
     | \
     |  \--> Process Manager
     |
   Agent Runtime ---> OpenAI-compatible API
     |
   Tool Registry + Policy
     |
   SQLite (sessions/messages/idempotency)

快速开始

1) 运行环境

通过 npm 安装：无需额外准备 Bun
从源码运行：Bun >= 1.3.x

2) 初始化

bun run bin/bunclaw.ts onboard

~/.bunclaw/bunclaw.json
~/.bunclaw/bunclaw.db
~/.bunclaw/events.jsonl
~/.bunclaw/skills
~/.bunclaw/agents
~/.bunclaw/channels

3) 启动网关

bun run bin/bunclaw.ts gateway

默认入口：

ws://127.0.0.1:16789/ws
http://127.0.0.1:16789/

4) CLI 调用

# 发送消息
bun run bin/bunclaw.ts message send --session main --message "你好"

# 运行一次 Agent
bun run bin/bunclaw.ts agent --session main --message "总结当前仓库"

# 健康检查
bun run bin/bunclaw.ts doctor

Web UI

/chat：IM 风格会话、流式输出、消息 token 显示、清空聊天
/logs：系统/事件日志（不展示聊天正文）
/config：表单配置 + 原始 JSON 配置切换编辑
/stats：会话/消息/token/事件 + 系统信息面板

配置说明

配置文件：~/.bunclaw/bunclaw.json

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 16789,
    "token": "",
    "allowExternal": false
  },
  "model": {
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "",
    "model": "gpt-4.1-mini",
    "maxToolRounds": 4
  },
  "tools": {
    "profile": "coding",
    "allow": [],
    "deny": [],
    "webSearch": {
      "provider": "",
      "providers": ["news", "media", "bing", "google", "duckduckgo", "baidu", "sogou", "so", "github"],
      "categories": ["tech", "research", "media"],
      "endpoint": "",
      "apiKey": "",
      "timeoutMs": 8000,
      "customScript": ""
    }
  },
  "sessions": {
    "dbPath": "~/.bunclaw/bunclaw.db",
    "eventsPath": "~/.bunclaw/events.jsonl",
    "workspace": "~/.bunclaw/workspace"
  },
  "storage": {
    "baseDir": "~/.bunclaw",
    "skillsDir": "~/.bunclaw/skills",
    "agentsDir": "~/.bunclaw/agents",
    "channelsDir": "~/.bunclaw/channels"
  },
  "security": { "workspaceOnly": true },
  "ui": { "brandName": "BunClaw" }
}

TypeScript 类型（零三方依赖）

项目默认不依赖 @types/bun / @types/node。类型支持由仓库内置声明文件提供：

src/bun-ambient.d.ts：Bun、process、bun:test、bun:sqlite 等最小类型声明
tsconfig.json：types 为空数组，避免外部类型包耦合

这保证了“纯 Bun + 零第三方类型依赖”的开发体验。

自定义搜索脚本（Bun）

web_search 支持 custom provider，可通过 Bun 脚本接入自定义搜索逻辑：

配置 tools.webSearch.customScript，例如：scripts/custom-web-search.ts 或配置 tools.webSearch.endpoint（HTTP JSON 接口）。
调用时传入 providers: ["custom"] 或 providers: ["custom", "github", "bing"]
脚本通过 stdin 接收 JSON：{ query, count, timeoutMs }
脚本通过 stdout 返回 JSON：

{
  "results": [
    { "title": "...", "url": "https://...", "snippet": "...", "source": "..." }
  ]
}

项目内提供示例：scripts/custom-web-search.ts

custom provider 优先级：endpoint > customScript。任一失败时，会继续执行后续内置 provider（如 github/bing）。

搜索聚合与专业性策略

多引擎并行聚合：news/media/bing/google/duckduckgo/baidu/sogou/so/github
任一引擎不可用自动跳过，不影响其余引擎结果
站点分类支持（每类 15+）：government / education / research / media / forum / social / tech
基于查询意图自动重排引擎优先级：
- 源码 / code / github：优先 github
- 官网 / official：优先通用网页引擎并附带 site: 提示
- 最新 / 今日 / release：优先 news/media
结果输出包含检索时间戳与意图标签，降低时效误判风险

web_search 常用参数：

providers: 指定引擎集合
strictProviders: true 时严格按 providers 执行；false 时允许按意图自动重排
sites: 专业站点定向域名数组，例如 ["github.com", "openclaw.ai"]
categories: 站点分类数组，例如 ["tech", "research", "media"]

如果不在每次调用里传 categories，系统会默认使用配置中的 tools.webSearch.categories。

CLI 命令

onboard：初始化配置与目录
gateway：启动网关
agent --message "..." [--session main]
message send --message "..." [--session main]
doctor：配置/网关/模型/SQLite 检查
clean：清空聊天相关数据

打包与发布

本地打包

# 当前平台
bun run package

# 多平台
bun run package:all

# 生成 npm 安装包（tgz）
bun run pack:npm

# 生成 MSI（需 Windows + WiX 3）
bun run package:msi

github 构建

git tag v0.1.0

git push origin v0.1.0

产物启动示例

# Windows
./dist/bunclaw-bun-windows-x64.exe gateway

# Linux
chmod +x ./dist/bunclaw-bun-linux-x64
./dist/bunclaw-bun-linux-x64 gateway

# macOS
chmod +x ./dist/bunclaw-bun-darwin-arm64
./dist/bunclaw-bun-darwin-arm64 gateway

注意：二进制需要跟随子命令运行（如 gateway），仅执行 --help 不会启动服务。

GitHub Actions

工作流：.github/workflows/build-package.yml

三平台矩阵测试（Windows/macOS/Linux）
Ubuntu 执行 package:all + pack:npm
Ubuntu 额外产出 Unix 安装资产（install-unix.sh + bunclaw-*.tar.gz）
Windows 执行 package:msi
仅在推送 v* 标签（或手动触发）时执行
推送 v* 标签后自动发布到 GitHub Releases（包含二进制、.tgz、.msi）

npm / MSI 发布说明

npm

# 先检查 tgz
bun run pack:npm

# 正式发布
bun run publish:npm

组织发布目标：

npm scope：@idao-cube
包名：@idao-cube/bunclaw
地址：https://www.npmjs.com/org/idao-cube

GitHub Action 自动发布 npm 的前置条件：

在仓库 Secrets 配置 NPM_TOKEN
NPM_TOKEN 对 @idao-cube 组织具备发布权限
推送版本标签（如 v0.1.1）后触发自动发布

MSI

依赖：WiX Toolset 3（candle.exe / light.exe）
本地构建：

bun run package:msi

GitHub 开源发布流程（建议）

1) 准备仓库信息

package.json 包名使用组织作用域：@idao-cube/bunclaw
仓库建议：https://github.com/idao-cube/bunclaw

2) 配置 Secrets

NPM_TOKEN：npm 发布 token（对 @idao-cube 有 publish 权限）

3) 发布版本

git tag v0.1.1
git push origin v0.1.1

触发后 workflow 会自动：

三平台跑测试
构建多平台二进制
构建 npm tarball
构建 Windows MSI
发布到 GitHub Releases
发布到 npm（@idao-cube/bunclaw）

常见问题（安装/发布）

ENEEDAUTH：通常是 NPM_TOKEN 缺失或权限不足（组织权限不够）。
No files were found with dist/*.msi：MSI 构建失败，查看 Build MSI 步骤日志。
Linux/macOS 二进制不可执行：先 chmod +x。
双击二进制没启动网关：需要带子命令（如 gateway）。
未知命令: getaway：命令拼写错误，正确是 bun start gateway。
EADDRINUSE (port 16789 in use)：端口已占用。可先停止旧进程，或改配置里的 gateway.port 后重启。

开发与测试

bun test

当前测试覆盖：

协议校验
幂等与存储
工具策略
Gateway 集成
Web UI 页面契约
打包命名逻辑
纯 Bun 约束（禁止 node:*）

路线图

[ ] 插件化工具注册与权限分层
[ ] 渠道适配（IM/Webhook）
[ ] 更细粒度的统计与审计回放
[ ] 多用户/多工作区隔离策略

贡献

欢迎 Issue / PR。建议提交前执行：

bun test

License

MIT

English (Brief)

BunClaw is a pure-Bun local agent core inspired by OpenClaw, focusing on a stable v1 control plane:

Gateway + WebSocket protocol (connect, req/res/event)
Agent runtime with OpenAI-compatible backend and tool loop
SQLite sessions/messages/idempotency + JSONL events
Built-in Web UI (/chat, /logs, /config, /stats)
Single-binary packaging and GitHub Actions CI