MagiClaw 入门：飞书里的 AI 科研智能体团队，让协作自然发生

15 分钟配置完成｜飞书原生体验｜科研 Agent 编排｜EvoMaster 基座一键扩展

---

项目简介

MagiClaw 是一个运行在飞书里的 AI 智能体平台。它的核心思路是：不做另一个需要你专门打开的独立工具，而是直接把 AI 智能体嵌入到你每天都在用的飞书里——在群聊或私聊里描述需求，智能体团队就开始运转。

MagiClaw 背后依赖的是 EvoMaster 框架，一个轻量级的 Agent 基础设施，负责工具调用、Skills 技能、记忆管理和会话接线。这意味着你可以把精力放在「让智能体做什么」上，而不是重复搭建工程层。整个项目开源，Apache 2.0 许可证，代码量小，容易二次开发。

---

目标读者画像

本文面向以下开发者：

• 有 Python 基础，熟悉飞书或 Lark 协作工具，希望把 AI 能力直接引入团队日常沟通
• 对 AI for Science 场景感兴趣，想找可扩展的科研智能体框架
• 已经在用 EvoMaster 或类似 Agent 框架，想扩展飞书作为前端交互层

如果你在找一个独立的科研智能体全家桶，MagiClaw 不是那个答案——它是把 EvoMaster 生态接入飞书，让科研工作流在你的团队沟通工具里自然跑起来。

---

核心依赖与环境

---

完整项目结构树

MagiClaw/
├── evomaster/                    # 核心框架库
│   ├── agent/                   # Agent 基类与运行时
│   ├── core/                    # 核心工具调用、任务调度
│   ├── interface/
│   │   └── feishu/             # 飞书接口实现（长连接、Webhook）
│   ├── memory/                  # 持久化记忆存储
│   ├── skills/                  # 可复用技能包
│   └── scheduler/               # 多任务调度器
├── playground/
│   ├── magiclaw/               # 默认飞书对话智能体
│   ├── agent_builder/           # 元智能体：设计 / 生成新 Agent
│   ├── coding_agent/            # 代码编写专项 Agent
│   ├── report_writer_agent/     # 报告撰写专项 Agent
│   └── web_search_agent/        # 网页搜索专项 Agent
├── configs/
│   ├── feishu/                  # 飞书 Bot 连接凭证
│   │   └── config.yaml
│   ├── magiclaw/               # LLM、工具、MCP、记忆配置
│   │   └── config.yaml
│   └── agent_builder/           # 规划 + 构建双智能体配置
├── run.py                       # CLI 快速启动入口
├── requirements.txt
└── pyproject.toml

---

手把手安装步骤

第一步：克隆代码

git clone https://github.com/sjtu-sai-agents/MagiClaw.git
cd MagiClaw

第二步：安装依赖

pip install -r requirements.txt

或者用 uv（更快）：

uv pip install -r requirements.txt

第三步：创建飞书应用

1. 打开 飞书开放平台，登录你的团队账号
2. 点击 创建企业自建应用，填写名称和描述
3. 进入应用后，左侧菜单选择 添加应用能力，勾选 机器人

第四步：配置应用凭证

复制环境变量模板：

cp .env.template .env

在 .env 中填入飞书开放平台提供的凭证：

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第五步：导入权限范围

在飞书开放平台，进入 权限管理 → 批量导入/导出权限，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "im:resource",
      "docx:document",
      "docx:document:readonly",
      "drive:drive",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "wiki:wiki:readonly"
    ],
    "user": [
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive.version",
      "drive:drive.version:readonly"
    ]
  }
}

第六步：配置事件订阅

在 事件与回调 → 事件配置 中，选择 使用长连接接收事件，添加以下事件：

在 回调配置 中，同样选择长连接，订阅：

第七步：配置 LLM

编辑 configs/magiclaw/config.yaml，填入你的 LLM 凭证：

llm:
  provider: openai              # 或 anthropic / custom
  model: gpt-4o
  api_key: sk-...               # 从 .env 或直接写在配置文件
  base_url: https://api.openai.com/v1  # 可选，自定义端点

第八步：发布应用并启动

在飞书开放平台 版本管理与发布 中创建版本并发布，使 Bot 生效。

然后启动机器人：

python -m evomaster.interface.feishu --config configs/feishu/config.yaml

启动成功后，在飞书里给 Bot 发一条消息，它会回复。初始状态它是一个通用的会话智能体，具备多轮上下文和记忆能力。

---

双核心 Agent 架构

MagiClaw 真正的能力来自两个内置 Playground 的配合：magiclaw 处理日常会话，agent_builder 帮你创建新的专项智能体。

magiclaw：飞书会话编排器

magiclaw 是默认激活的飞书对话智能体，它的核心能力是编排与委托。

当你发送一个复杂请求时，magiclaw 不会试图一个人搞定，而是会识别这个任务需要什么专项能力，然后通过工具调用把工作委托给其他已注册的 Playground：

你在飞书里：「帮我调研一下 RAG 架构在金融领域的最新进展，写一份报告」

→ magiclaw 接收请求
→ 判断需要：文献调研（web_search_agent）+ 报告撰写（report_writer_agent）
→ 分别调用这两个 Agent
→ 汇总结果，返回飞书消息

这种委托机制让 magiclaw 保持简洁——它不需要什么都会，只需要知道什么时候该调用谁。所有专项 Agent 的能力通过 Skills 和工具接口来扩展。

agent_builder：元智能体

agent_builder 是 MagiClaw 里最有意思的部分：它本身也是一个 Agent，但它的职责是设计并生成新的 Agent。

你告诉它你想做什么类型的任务，它会：

1. 分析需求，提取 Agent 需要的核心能力
2. 生成 Agent 的技能文件（YAML frontmatter + Markdown 描述）
3. 写入 playground/ 目录，注册到 MagiClaw
4. 新 Agent 立即可用，magiclaw 就可以委托它了

你在飞书里：「我需要一个专门处理代码审查的 Agent」

→ agent_builder 分析需求
→ 生成 `code_reviewer_agent.py` + 对应配置文件
→ 注册到系统
→ 回复：「已创建 code_reviewer，magiclaw 现在可以委派代码审查任务给它了」

这个自举能力让团队可以根据自己的科研方向不断扩展 Agent 库，而不是一次性定义完所有场景。

---

工具配置与 Skills / 记忆机制

工具层配置

在 configs/magiclaw/config.yaml 中可以配置多类工具：

tools:
  mcp:
    # MCP 协议工具（如文件系统、Git、数据库等）
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # 可选：bing / google / serpapi

  feishu:
    read_document: true           # 读取飞书文档
    send_file: true               # 发送文件

工具配置决定了 Agent 能「做什么」，而 Skills 决定了 Agent「怎么做得好」。

Skills 技能系统

Skills 是封装好的结构化提示词，让 Agent 在特定任务上有更好的表现。EvoMaster 的 Skills 目录在 evomaster/skills/，每个 Skill 是一个 Markdown 文件：

---
name: research-paper-summary
trigger: literature survey, paper review, paper analysis
agent: research
---

# Research Paper Summary Skill

当用户要求总结或分析论文时，执行以下步骤：

1. 提取论文标题、作者、发表venue
2. 提取核心贡献（contribution）
3. 提取方法论要点
4. 提取局限性（limitations）
5. 输出结构化摘要（不超过 300 字）

如果用户提供的是 ArXiv 链接，先抓取页面内容再分析。

Skills 按需加载，Agent 在处理特定类型任务时会自动匹配对应 Skill，不需要手动触发。

持久化记忆

MagiClaw 的记忆通过 evomaster/memory/ 模块管理，支持多种存储后端：

memory:
  backend: sqlite               # 可选：sqlite / redis / file
  session_ttl: 86400            # 会话记忆保留时间（秒）
  long_term:
    enabled: true
    store: file                 # 持久化到磁盘
    path: ./memory_store/

每次对话结束后，Agent 会自动将关键上下文写入记忆。下一次会话开始时，Agent 读取历史记忆，保持跨会话的连贯性。

---

完整工作流演示

场景：为团队搭建一个「论文速读」Agent

目标：在飞书里丢给 Bot 一篇 ArXiv 链接，它自动返回结构化的论文摘要。

Step 1：用 agent_builder 创建 Agent

在飞书里给 MagiClaw 发消息：

帮我创建一个论文速读 Agent，名字叫 paper_reader

agent_builder 会生成 playground/paper_reader/ 目录，包含：

playground/paper_reader/
├── __init__.py
├── agent.py                   # Agent 主逻辑
└── config.yaml                 # Agent 级配置

Step 2：注册到 magiclaw

新 Agent 创建后，编辑 configs/magiclaw/config.yaml，在 playgrounds 下注册：

playgrounds:
  - name: paper_reader
    path: playground/paper_reader
    enabled: true

重启机器人后，magiclaw 就能识别并委托 paper_reader。

Step 3：测试

在飞书里：

@Bot paper_reader https://arxiv.org/abs/2401.01234

paper_reader 自动执行：

1. 抓取 ArXiv 页面
2. 提取标题、作者、摘要
3. 生成结构化摘要（贡献 + 方法 + 局限）
4. 返回飞书消息

---

常见问题排查

Q1：启动机器人后飞书没有响应

原因：事件订阅或长连接配置不正确。

排查步骤：

# 1. 确认机器人已发布（飞书开放平台 → 版本管理与发布）
# 未发布的机器人无法在生产环境收发消息

# 2. 确认长连接已正确配置
# 飞书开放平台 → 事件与回调 → 事件配置 → 选择「长连接」

# 3. 检查启动日志是否有报错
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2：Bot 收到消息但回复「不支持该操作」

原因：权限范围不足，或者应用未发布到对应范围。

排查步骤：

在飞书开放平台 → 权限管理，确认已开通以下最小权限集：

"im:message",
"im:message:send_as_bot",
"im:chat:readonly"

如果 Bot 需要加入群聊，还需要 im:message.group_at_msg:readonly。

---

Q3：agent_builder 创建 Agent 后，magiclaw 无法识别

原因：新 Agent 没有注册到 configs/magiclaw/config.yaml。

解决方法：

确认在 configs/magiclaw/config.yaml 的 playgrounds 列表中添加了新 Agent，并设置 enabled: true。修改配置后需要重启机器人。

---

Q4：记忆没有跨会话保留，每次对话 Agent 都像失忆

原因：记忆存储后端未正确配置，或存储路径不可写。

排查步骤：

# 1. 检查 config.yaml 中的 memory 配置
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. 确保 memory_store 目录存在且可写
mkdir -p memory_store
chmod 755 memory_store

# 3. 重启机器人，发送一条消息触发记忆写入

---

Q5：Web Search 工具返回空结果或超时

原因：网络无法访问搜索服务，或 Search API 凭证未配置。

解决方法：

如果使用 DuckDuckGo（免费，无需 API Key），确认 Python 环境能访问外网：

# 测试网络
python -c "import requests; print(requests.get('https://api.duckduckgo.com/?q=test&format=json').status_code)"

如果返回 200 但 Bot 里仍超时，检查 configs/magiclaw/config.yaml 中 tools.web_search.provider 配置是否正确。

---

Q6：MCP 工具无法启动，提示 command not found

原因：MCP Server 的 npx 或 Node.js 路径未添加到系统 PATH。

解决方法：

# 确认 npx 可用
npx --version

# 如果提示找不到 npx，手动指定路径
# 编辑 configs/magiclaw/config.yaml：
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

扩展阅读与进阶方向

1. 接入 SciMaster 生态

MagiClaw 是 EvoMaster 生态的飞书入口，而完整的 SciMaster 系列（ML-Master、X-Master、Browse-Master 等）位于上游 EvoMaster 仓库。如果你的科研方向需要多模态材料科学分析或多实验协同，可以从 EvoMaster 同步这些专项 Agent，接入 MagiClaw 的编排层。

2. 自定义 MCP 工具

MagiClaw 的 MCP 工具接口支持接入任意 MCP Server。你可以用 Python 写一个 MCP Server 来封装内部 API、科研数据库查询工具或 HPC 集群提交脚本，然后注册到 MagiClaw，让 Agent 在飞书里直接调用。

3. 多 Bot 协作架构

如果团队有多个不同职能的 Bot（例如一个管日历、一个管代码、一个管文献），可以让它们通过飞书群聊协作：在一个群里集成多个 Bot，各自负责自己的职能，通过 @ 切换。

4. 团队私有模型部署

EvoMaster 支持 custom Provider，可以接入公司内部部署的 LLM（Llama、Mistral、Qwen 等）。如果科研数据不能外传，可以在本地或私有云部署模型，通过 MagiClaw 的飞书界面操作，数据完全不离开内网。

5. Agent 行为调优

每个 Playground 的 Agent 行为主要由 config.yaml 中的 prompt 和 skills 控制。如果发现 Agent 在某些场景下表现不佳，可以修改对应的 Skill 文件，调整 Agent 的思考步骤和输出格式，不需要动代码。