RunClaw

基于 Claude Code CLI 的飞书 AI 助手机器人。通过飞书 WebSocket 长连接接收消息，调用 Claude Code 处理，以流式卡片形式回复。

特性

• Claude Code 驱动 — 以 Claude Code CLI 作为 AI 后端，支持工具调用、文件读写、联网搜索等全部能力
• 飞书原生集成 — WebSocket 长连接，支持私聊和群聊（@机器人触发），流式卡片回复（thinking / 工具步骤 / 正文分层展示）
• 多轮对话 & 会话恢复 — 每个对话独立子进程，空闲 20 分钟自动回收，下次消息自动恢复 session
• 持久记忆系统 — 双层记忆架构：MEMORY.md（全局长期记忆）+ memory/ 目录（每日对话日志），支持自动摘要整合
• 定时任务调度 — 支持 cron 表达式和一次性定时任务，通过自然语言或 MCP 工具创建
• MCP 扩展 — 内置 MCP Server（记忆搜索 + 任务调度），支持配置外部 MCP Server
• 人格系统 — 通过模板文件（SOUL.md / IDENTITY.md / AGENTS.md）定义机器人人格、行为准则和操作手册
• 交互式引导 — bun run onboard 一键完成配置

前置依赖

• Bun >= 1.0
• Claude Code CLI (npm install -g @anthropic-ai/claude-code)
• 飞书开放平台自建应用（需启用机器人能力）

快速开始

# 克隆项目
git clone <repo-url> && cd runclaw

# 安装依赖
bun install

# 交互式配置（创建 ~/.runclaw/config.json）
bun run onboard

# 启动
bun start

配置

配置优先级：环境变量 > ~/.runclaw/config.json > 默认值。

配置文件

~/.runclaw/config.json 示例：

{
  "agent": {
    "model": "claude-opus-4-6",
    "allowedTools": []
  },
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "xxx",
    "domain": "feishu",
    "groupAutoReply": []
  },
  "mcpServers": {},
  "workspacesDir": "~/.runclaw/workspaces",
  "skillsDir": "~/.runclaw/skills",
  "logLevel": "info"
}

环境变量

变量	说明
FEISHU_APP_ID	飞书应用 App ID
FEISHU_APP_SECRET	飞书应用 App Secret
FEISHU_DOMAIN	feishu 或 lark
RUNCLAW_MODEL	Claude 模型名称
RUNCLAW_LOG_LEVEL	日志级别 (debug / info / warn / error)
RUNCLAW_CONFIG	自定义配置文件路径

飞书应用配置

1. 在 飞书开放平台 创建自建应用
2. 开启「机器人」能力
3. 添加事件订阅：im.message.receive_v1
4. 发布应用版本

命令

聊天中可使用的斜杠命令：

命令	说明
/clear 或 /new	清除当前上下文，触发记忆摘要整合
/status	查看系统状态
/schedule list	列出定时任务
/schedule remove <id>	删除定时任务
/help	显示帮助

架构

飞书 WebSocket ──→ FeishuGateway ──→ Dispatcher ──→ ClaudeCodeAgent
                                         │                  │
                                    斜杠命令处理       Claude Code CLI
                                    记忆日志追加       (stream-json 协议)
                                         │                  │
                                    Scheduler          MCP Server
                                   (定时任务轮询)     (记忆搜索 + 调度)

目录结构

src/
├── index.ts            # 入口
├── agent.ts            # Claude Code CLI 子进程管理
├── dispatcher.ts       # 消息路由 & 斜杠命令
├── config.ts           # 配置加载
├── types.ts            # 类型定义
├── onboard.ts          # 交互式配置向导
├── utils.ts            # 工具函数
├── gateway/
│   └── feishu.ts       # 飞书网关（WebSocket + 流式卡片）
├── memory/
│   ├── index.ts        # 记忆模块公共 API
│   ├── daily.ts        # 每日对话日志
│   ├── global.ts       # 全局记忆读写
│   └── db.ts           # 全文搜索（SQLite FTS）
├── mcp/
│   ├── server.ts       # MCP Server 入口
│   ├── memory.ts       # 记忆相关 MCP 工具
│   └── scheduler.ts    # 调度相关 MCP 工具
├── scheduler/
│   ├── index.ts        # 调度器主循环
│   ├── store.ts        # 任务持久化
│   └── types.ts        # 调度类型
templates/
├── AGENTS.md           # 操作手册模板
├── SOUL.md             # 人格定义模板
├── IDENTITY.md         # 身份信息模板
├── USER.md             # 用户档案模板
└── MEMORY.md           # 长期记忆模板

License

MIT