TinyClaw：用 500 行代码复刻生产级 AI Agent 引擎｜轻量级多智能体框架实战

🔧 TinyClaw：用 500 行代码复刻生产级 AI Agent 引擎｜轻量级多智能体框架实战

摘要：在 AI Agent 开发日益复杂的今天，是否有一个"小而美"的方案能快速落地？本文深度解析开源项目 TinyClaw——一个基于 FastAPI + LangChain 0.3 + Vue 3 的轻量级 AI Agent 执行引擎，带你从零理解多智能体委派、记忆管理、技能热加载等核心机制。

🎯 为什么需要 TinyClaw？

当前主流的 Agent 框架（如 LangGraph、AutoGen、CrewAI）功能强大但学习曲线陡峭，部署复杂且资源消耗大。对于个人开发者、快速原型验证或边缘部署场景，往往"杀鸡用牛刀"。

TinyClaw 的诞生正是为了解决这一痛点：

"用最小的代码复杂度，复刻生产级的 Agent 执行能力"

它从 OpenClaw 精简而来，剥离分布式网关与复杂图编排，保留最核心的 Tool Calling、多智能体路由、工作空间隔离等能力，单机即可运行，代码清晰易读，是学习 Agent 架构的绝佳实践项目。

✨ 核心特性全景图

🤖 多智能体智能委派

用户 → main Agent → "@coder 请写个网页" → 自动路由 → coder Agent → 执行 file.write

• 支持主 Agent 与多个子 Agent（如 @coder、@researcher）
• 前端无缝切换角色，后端自动转发消息上下文
• 基于 Prompt 指令的软路由，无需复杂配置

🧩 OpenClaw 技能完全兼容

backend/skills/
├── file.read/     # 读取文件技能
│   ├── skill.json # 元数据定义
│   └── run.py     # 业务逻辑实现
└── file.write/    # 写入文件技能

• 复用 OpenClaw 生态技能插件
• 动态热加载：新增技能文件夹，重启即生效
• 标准化入参：params 字典 + 隐式注入 __workspace_dir

🧠 高级记忆管理系统

🛠️ 硬核调试能力

• Traces 控制台：折叠式展示技能调用链，入参/出参一目了然
• AOP 切面日志：@log_call 注解无侵入记录函数执行
• debug.log：原始 Prompt 与 Model Response 完整留存，排查"模型不听话"问题

🔐 工作空间物理隔离

data/workspaces/
├── default/
│   ├── memory.json    # 对话历史
│   ├── files/         # 生成/读取的文件
│   └── logs/          # 运行日志
└── project_x/         # 多项目并行，数据绝不串号

🏗️ 技术架构深度解析

后端：FastAPI + LangChain 0.3

# core/agent.py - Agent 执行核心
async def run_agent(agent_name: str, message: str, workspace: str):
    # 1. 加载 Agent 配置（prompt + skills）
    # 2. 构建 LangChain Tool 列表（Pydantic Schema 自动转换）
    # 3. 调用 LLM 并处理 Tool Calling 循环
    # 4. 记忆裁剪/压缩策略介入
    # 5. 返回结构化响应

关键设计：

• 使用 LangChain 0.3 原生 bind_tools + tool_calling，避免自定义解析器
• 技能参数通过 Pydantic 自动校验，类型安全
• 异步 async/await 全程支持，高并发友好

前端：Vue 3 + Composition API

<!-- App.vue - 极简聊天终端 -->
<template>
  <AgentSwitcher v-model="currentAgent" :agents="agents" />
  <ChatWindow :messages="messages" @trim="deleteMessage" />
  <TracePanel :traces="debugTraces" v-if="showDebug" />
</template>

• 响应式状态管理：Agent 切换、消息流、调试面板联动
• 自定义指令：v-trim 实现消息裁剪交互
• 轻量无状态：所有数据通过 API 与后端同步，前端专注渲染

配置驱动：solu.json

{
  "model": {
    "type": "openai",
    "name": "gpt-4o-mini",
    "base_url": "https://api.openai.com/v1"
  },
  "agents": {
    "main": {
      "prompt": "你是前台管家...",
      "skills": []
    },
    "coder": {
      "prompt": "你是代码专家...",
      "skills": ["file.read", "file.write"]
    }
  },
  "runtime": {
    "timeout": 20,
    "max_steps": 5
  }
}

• 零代码配置 Agent 网络：修改 JSON 即可调整角色分工
• 多模型支持：OpenAI 标准接口 / Ollama 本地模型无缝切换
• 运行时控制：超时、最大步骤防止死循环

🚀 5 分钟快速上手

环境准备

# 后端：Python 3.10+
cd backend && pip install -r requirements.txt

# 前端：Node 18+
cd frontend && npm install

启动服务

# Terminal 1: 后端
cd backend && uvicorn app:app --reload --port 8000

# Terminal 2: 前端  
cd frontend && npm run dev

配置模型（backend/solu.json）

// 使用 Ollama 本地模型（免费！）
"model": {
  "type": "openai",
  "name": "qwen2.5-coder",
  "base_url": "http://localhost:11434/v1",
  "api_key": "ollama"
}

访问 http://localhost:5173，即刻体验多智能体对话！

💡 高级技巧：让 TinyClaw 更强大

1️⃣ 自定义技能开发（3 步搞定）

# 1. 创建技能目录
mkdir backend/skills/weather.query

# 2. 编写 skill.json
{
  "name": "weather.query",
  "description": "查询城市天气",
  "entry": "run.py",
  "params": { "city": "string" }
}

# 3. 实现 run.py
async def run(params: dict) -> dict:
    city = params["city"]
    # 调用天气 API...
    return {"success": True, "data": f"{city} 晴，25℃"}

✅ 重启后端，@main 北京天气 即可自动调用！

2️⃣ 记忆压缩实战：节省 80% Token

# 当对话超过 20 条时触发
if len(messages) > 20:
    summary = await llm.invoke(f"请总结以下对话：{messages}")
    messages = [SystemMessage(content=f"前情提要：{summary}")]

• 适合：长文档分析、多轮需求澄清、代码迭代开发
• 效果：上下文从 10K tokens → 1K tokens，API 成本直降

3️⃣ 调试"模型不调用工具"问题

# 查看底层日志
tail -f backend/data/workspaces/default/logs/debug.log

# 常见原因：
# 1. skill.json 描述不清晰 → 优化 description
# 2. 参数类型不匹配 → 检查 Pydantic Schema
# 3. Prompt 未明确触发条件 → 加强 agent prompt

🔍 适合谁用？

📦 项目信息

• 🔗 源码：https://github.com/qyhua0/TinyClaw
• 📜 协议：MIT License（可商用）
• 🐍 后端：Python 3.10+ / FastAPI / LangChain 0.3
• ⚛️ 前端：Vue 3 / Vite / TypeScript
• 🤖 模型：OpenAI 标准接口 / Ollama / 任意兼容端点

🌟 总结

TinyClaw 证明了：强大的 Agent 能力，不需要复杂的架构。

它用极简的设计哲学，将多智能体协作、技能扩展、记忆管理等核心能力封装为可配置的模块，既适合快速落地业务，也适合深入理解 Agent 底层原理。

💡 个人建议：如果你正在寻找一个"能跑起来、看得懂、改得动"的 Agent 框架，TinyClaw 值得加入你的技术栈。