MagiClaw for Beginners: An AI research agent team in Feishu that makes collaboration feel natural

Set up in 15 minutes｜Native Feishu experience｜Research Agent orchestration｜One-click extension with the EvoMaster foundation

---

Project overview

MagiClaw is an AI agent platform that runs inside Feishu. Its core idea is simple: it’s not another standalone tool you have to open separately. Instead, it embeds an AI agent team directly into Feishu—whenever you describe your needs in a group chat or private chat, the agent team starts working.

Behind MagiClaw is the EvoMaster framework: a lightweight Agent infrastructure that handles tool calling, Skills, memory management, and session routing. This means you can focus on what you want the agents to do, rather than repeatedly building the engineering layer. The whole project is open source under the Apache 2.0 license. It has a small codebase and is easy to extend for your own needs.

---

Target readers

This article is for developers who:

• Have basic Python knowledge, are familiar with Feishu or Lark collaboration tools, and want to bring AI capabilities directly into day-to-day team communication
• Are interested in AI for Science scenarios and want a scalable research agent framework
• Are already using EvoMaster or a similar Agent framework and want to extend Feishu as the frontend interaction layer

If you’re looking for a complete standalone “research agent bundle,” MagiClaw is not that answer. It’s the integration of the EvoMaster ecosystem into Feishu, so your research workflows can run naturally within your team communication tool.

---

Core dependencies and environment

---

Complete project directory tree

MagiClaw/
├── evomaster/                    # Core framework library
│   ├── agent/                   # Agent base classes and runtime
│   ├── core/                    # Core tool calling and task scheduling
│   ├── interface/
│   │   └── feishu/             # Feishu interface implementation (long connection, Webhook)
│   ├── memory/                  # Persistent memory storage
│   ├── skills/                  # Reusable skill packages
│   └── scheduler/              # Multi-task scheduler
├── playground/
│   ├── magiclaw/               # Default Feishu conversation agent
│   ├── agent_builder/         # Meta-agent: design / generate new Agents
│   ├── coding_agent/          # Code-specialized agent
│   ├── report_writer_agent/  # Report-writing specialized agent
│   └── web_search_agent/     # Web-search specialized agent
├── configs/
│   ├── feishu/                 # Feishu Bot connection credentials
│   │   └── config.yaml
│   ├── magiclaw/               # LLM, tools, MCP, memory configuration
│   │   └── config.yaml
│   └── agent_builder/         # Plan + build dual-agent configuration
├── run.py                       # CLI quick start entry
├── requirements.txt
└── pyproject.toml

---

Step-by-step installation

Step 1: Clone the code

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

Step 2: Install dependencies

pip install -r requirements.txt

Or use uv (faster):

uv pip install -r requirements.txt

Step 3: Create a Feishu app

1. Open Feishu Open Platform and log in to your team account
2. Click Create Enterprise Self-built App, fill in the name and description
3. After entering the app, in the left menu select Add application capabilities, and check Bot

Step 4: Configure app credentials

Copy the environment variable template:

cp .env.template .env

Fill in the credentials provided by the Feishu Open Platform in .env:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 5: Import permission scopes

On the Feishu Open Platform, go to Permission Management → Batch Import/Export Permissions, and paste the following 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"
    ]
  }
}

Step 6: Configure event subscription

In Events & Callbacks → Event Configuration, select Use long connection to receive events, and add the following events:

In Callback Configuration, also choose a long connection and subscribe to:

Step 7: Configure the LLM

Edit configs/magiclaw/config.yaml and fill in your LLM credentials:

llm:
  provider: openai              # or anthropic / custom
  model: gpt-4o
  api_key: sk-...               # from .env or directly in the config file
  base_url: https://api.openai.com/v1  # optional: customize endpoint

Step 8: Publish the app and start

In the Feishu Open Platform Version Management & Publishing, create a version and publish it so the Bot becomes effective.

Then start the robot:

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

After a successful startup, send a message to the Bot in Feishu—it will reply. In the initial state, it is a general-purpose conversation agent with multi-turn context and memory capabilities.

---

Dual-core Agent architecture

MagiClaw’s real capability comes from the cooperation of two built-in Playgrounds: magiclaw handles everyday conversation, while agent_builder helps you create new specialized agents.

magiclaw: Feishu session orchestrator

magiclaw is the default activated Feishu conversation agent. Its core strengths are orchestration and delegation.

When you send a complex request, magiclaw doesn’t try to handle everything by itself. Instead, it identifies what specialized capabilities the task needs, and delegates the work to other already-registered Playgrounds via tool calling:

In Feishu, you say: “Help me research the latest progress of RAG architecture in the financial domain, and write a report.”

→ magiclaw receives the request
→ determines it needs: literature research (web_search_agent) + report writing (report_writer_agent)
→ calls these two Agents respectively
→ summarizes the results and returns a Feishu message

This delegation mechanism keeps magiclaw lean—it doesn’t need to “know everything,” only when to call which specialized agent. The capabilities of each specialized agent are extended through Skills and tool interfaces.

agent_builder: the meta-agent

agent_builder is the most interesting part of MagiClaw. It is an Agent itself, but its job is to design and generate new Agents.

You tell it what kind of task you want to do, and it will:

1. Analyze the requirements and extract the core capabilities the Agent needs
2. Generate the Agent’s skill file (YAML frontmatter + Markdown description)
3. Write it into the playground/ directory and register it to MagiClaw
4. The new Agent is immediately usable, and magiclaw can delegate to it

In Feishu, you say: “I need an agent specialized in code review.”

→ agent_builder analyzes the requirement
→ generates `code_reviewer_agent.py` + the corresponding config file
→ registers it to the system
→ replies: “Created code_reviewer. magiclaw can now delegate code review tasks to it.”

This self-bootstrapping ability lets teams continuously expand their Agent library based on their research directions, instead of defining every scenario once and for all.

---

Tool configuration and Skills / memory mechanisms

Tool layer configuration

In configs/magiclaw/config.yaml, you can configure multiple kinds of tools:

tools:
  mcp:
    # MCP protocol tools (e.g., filesystem, Git, database, etc.)
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # optional: bing / google / serpapi

  feishu:
    read_document: true           # read Feishu documents
    send_file: true               # send files

Tool configuration determines what the Agent can do, while Skills determine how well it can do it.

Skills skill system

Skills are packaged structured prompts that help the Agent perform better on specific tasks. The EvoMaster Skills directory is in evomaster/skills/. Each Skill is a Markdown file:

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

# Research Paper Summary Skill

When a user asks to summarize or analyze a paper, execute the following steps:

1. Extract the paper title, authors, and publication venue
2. Extract the core contributions (contribution)
3. Extract key points of the methodology
4. Extract limitations (limitations)
5. Output a structured summary (no more than 300 words)

If the user provides an ArXiv link, first fetch the page content and then analyze it.

Skills are loaded on demand. When the Agent handles a specific type of task, it will automatically match the corresponding Skill—no manual triggering is required.

Persistent memory

MagiClaw’s memory is managed through the evomaster/memory/ module, supporting multiple storage backends:

memory:
  backend: sqlite               # optional: sqlite / redis / file
  session_ttl: 86400            # how long session memory is kept (seconds)
  long_term:
    enabled: true
    store: file                 # persist to disk
    path: ./memory_store/

After each conversation ends, the Agent automatically writes key context to memory. When the next session starts, the Agent reads historical memory to maintain coherence across sessions.

---

End-to-end workflow demo

Scenario: Build a “paper fast reading” Agent for your team

Goal: Send a Bot an ArXiv link in Feishu, and it automatically returns a structured paper summary.

Step 1: Create the Agent with agent_builder

Send a message to MagiClaw in Feishu:

Help me create a paper fast reading Agent named paper_reader

agent_builder will generate the directory playground/paper_reader/, containing:

playground/paper_reader/
├── __init__.py
├── agent.py                   # Agent main logic
└── config.yaml                 # Agent-level configuration

Step 2: Register it to magiclaw

After the new Agent is created, edit configs/magiclaw/config.yaml and register it under playgrounds:

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

After restarting the robot, magiclaw can recognize and delegate to paper_reader.

Step 3: Test

In Feishu:

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

paper_reader will execute automatically:

1. Fetch the ArXiv page
2. Extract the title, authors, and abstract
3. Generate a structured summary (contributions + method + limitations)
4. Return the result as a Feishu message

---

Troubleshooting

Q1: Feishu has no response after starting the Bot

Cause: Event subscriptions or long-connection configuration is incorrect.

Check steps:

# 1. Confirm the Bot is published (Feishu Open Platform → Version Management & Publishing)
# An unpublished Bot cannot send/receive messages in production

# 2. Confirm long connection is configured correctly
# Feishu Open Platform → Events & Callbacks → Event Configuration → select “Long connection”

# 3. Check whether there are errors in the startup logs
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2: The Bot receives messages but replies “Operation not supported”

Cause: Insufficient permission scopes, or the app has not been published to the relevant scopes.

Check steps:

On the Feishu Open Platform → Permission Management, confirm that the following minimal permission set is enabled:

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

If the Bot needs to join group chats, you also need im:message.group_at_msg:readonly.

---

Q3: After agent_builder creates an Agent, magiclaw can’t recognize it

Cause: The new Agent is not registered in configs/magiclaw/config.yaml.

Solution:

Make sure you add the new Agent to the playgrounds list in configs/magiclaw/config.yaml and set enabled: true. After modifying the configuration, restart the robot.

---

Q4: Memory isn’t preserved across sessions; the Agent seems to “forget” every time

Cause: The memory storage backend is not configured correctly, or the storage path is not writable.

Check steps:

# 1. Check the memory configuration in config.yaml
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. Ensure the memory_store directory exists and is writable
mkdir -p memory_store
chmod 755 memory_store

# 3. Restart the robot, send a message to trigger memory writing

---

Q5: Web Search returns empty results or times out

Cause: The network cannot access the search service, or the Search API credentials are not configured.

Solution:

If you’re using DuckDuckGo (free, no API key needed), confirm that your Python environment can access the public internet:

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

If it returns 200 but the Bot still times out, check whether tools.web_search.provider in configs/magiclaw/config.yaml is set correctly.

---

Q6: The MCP tool can’t start; it says command not found

Cause: The MCP Server’s npx or Node.js path is not added to the system PATH.

Solution:

# Confirm npx is available
npx --version

# If npx can’t be found, specify the path manually
# Edit configs/magiclaw/config.yaml:
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

Further reading and advanced directions

1. Integrate the SciMaster ecosystem

MagiClaw is the Feishu entry point for the EvoMaster ecosystem. The complete SciMaster series (ML-Master, X-Master, Browse-Master, etc.) lives in the upstream EvoMaster repository. If your research direction requires multimodal materials science analysis or coordination across multiple experiments, you can sync these specialized Agents from EvoMaster and plug them into MagiClaw’s orchestration layer.

2. Build custom MCP tools

MagiClaw’s MCP tool interface supports connecting to any MCP Server. You can write an MCP Server in Python to wrap internal APIs, scientific research database query tools, or HPC cluster submission scripts, then register it with MagiClaw so the Agent can call it directly from Feishu.

3. Multi-Bot collaboration architecture

If your team has multiple Bots with different responsibilities (e.g., one manages calendars, one handles code, one handles literature), you can let them collaborate through Feishu group chats. Integrate multiple Bots into one group, and switch their functions via @ mentions.

4. Deploy a team-private model

EvoMaster supports the custom Provider, which allows you to connect to LLMs deployed internally (Llama, Mistral, Qwen, etc.). If your research data can’t be sent out, deploy the model locally or on a private cloud. Then use MagiClaw’s Feishu interface to operate it—your data never leaves the intranet.

5. Tuning agent behavior

Each Playground Agent’s behavior is mainly controlled by the prompt and skills fields in config.yaml. If you find the Agent performs poorly in certain scenarios, you can modify the corresponding Skill file—adjust the agent’s reasoning steps and output format without changing any code.