GenericAgent 部署与接入: 微信/QQ/飞书全平台机器人搭建

项目简介

GenericAgent 是一个极简、可自我进化的自主 Agent 框架。它的核心仅 ~3K 行代码，通过 9 个原子工具 + 约 100 行的 Agent Loop，赋予任意 LLM 对本地计算机的系统级控制能力。

它的设计哲学很有意思：不预设技能，靠进化获得能力。每解决一个新任务，GenericAgent 就将执行路径自动固化为 Skill。使用时间越长，沉淀的技能越多，形成一棵完全属于你、从 3K 行种子代码生长出来的专属技能树。

相比 OpenClaw（~530K 行代码），GenericAgent 走的是极简路线——部署简单（pip install + API Key），不需要多服务编排，但依然保留了完整的浏览器控制、键鼠操作、ADB 移动设备控制等核心能力。

---

难度/时长/收获

• 难度：入门级，不需要深度编程经验
• 时长：约 30 分钟
• 收获：掌握 GenericAgent 部署配置 + 微信/QQ/飞书三大 IM 平台接入，实现随时随地用手机操控电脑 AI

---

目标读者画像

• 1-5 年经验的后端或全栈开发者
• 希望搭建个人 AI 助手、自动化工作流的用户
• 对 Agent 技术感兴趣，想快速体验"让 AI 真正替你做事"的开发者
• 有多平台 IM 接入需求（如需要通过微信/QQ 远程控制电脑）

---

核心依赖与环境

---

完整项目结构

GenericAgent/
├── agentmain.py              # 主入口，支持命令行模式
├── launch.pyw                # 桌面 GUI 启动脚本
├── agent_loop.py             # 核心 Agent Loop（约100行）
├── llmcore.py                # LLM 会话管理
├── ga.py                     # GenericAgentHandler，记忆与工具调度
├── frontends/                # IM 平台适配器
│   ├── wechatapp.py         # 微信 Bot
│   ├── qqapp.py             # QQ Bot
│   ├── fsapp.py             # 飞书 Bot
│   ├── tgapp.py             # Telegram Bot
│   ├── wecomapp.py          # 企业微信 Bot
│   ├── dingtalkapp.py       # 钉钉 Bot
│   ├── tuiapp.py            # 终端 UI
│   └── ...
├── assets/
│   ├── mykey_template.py    # API Key 配置模板
│   ├── tools_schema.json    # 9个原子工具定义
│   ├── sys_prompt*.txt      # 系统提示词
│   └── tmwd_cdp_bridge/    # 浏览器注入插件
├── memory/                   # 记忆存储目录
└── temp/                     # 临时文件与日志

---

手把手步骤

Step 1: 安装项目与依赖

首先克隆仓库并安装基础依赖：

# 克隆仓库
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 安装基础依赖
pip install requests

# 安装 GUI 依赖（桌面模式）
pip install streamlit pywebview

# 或安装终端 UI 依赖
pip install requests textual

Step 2: 配置 API Key

复制配置模板：

cp assets/mykey_template.py mykey.py

编辑 mykey.py，填入你的 LLM 配置。下面是使用 Defapi 的示例（以 Claude 为例）：

# 使用 Defapi 中转 Claude（官方半价）
native_claude_config = {
    'name': 'claude-defapi',                    # 显示名
    'apikey': 'sk-ant-your-defapi-key',         # Defapi 提供的 key
    'apibase': 'https://api.defapi.org',        # Defapi 端点
    'model': 'claude-sonnet-4-6',               # 或 claude-opus-4-7
    'fake_cc_system_prompt': True,              # 中转服务需要开启
    'thinking_type': 'adaptive',
    'max_tokens': 16384,
}

GenericAgent 会自动根据变量名判断协议格式：

• 含 native + claude → NativeClaudeSession（原生 tool 字段）
• 含 native + oai → NativeOAISession（OpenAI 原生 tool 字段）
• 含 claude（不含 native）→ ClaudeSession（文本协议工具）

Step 3: 启动 GenericAgent

先测试命令行模式是否正常：

python agentmain.py

你应该能看到交互提示符 >，输入一句话测试：

> 在桌面创建一个 hello.txt，内容是 Hello World

如果一切正常，Agent 会执行任务并反馈结果。

切换到桌面 GUI 模式：

python launch.pyw

---

Step 4: 接入微信 Bot

微信 Bot 支持个人微信扫码登录，接入最简单。

安装额外依赖：

pip install pycryptodome qrcode requests

配置（可选，不配置也能用，但建议设置白名单）：

在 mykey.py 中添加：

# 微信白名单，填写微信 ID，不填则允许所有用户
wechat_allowed_users = []

启动微信 Bot：

python frontends/wechatapp.py

首次启动会弹出一个二维码窗口，用微信扫码确认。登录成功后，你的微信就变成了与 GenericAgent 对话的界面。

Step 5: 接入 QQ Bot

QQ Bot 使用 QQ 机器人官方 API，不需要公网 webhook，通过 WebSocket 长连接接收消息。

安装依赖：

pip install qq-botpy

配置：

1. 去 QQ 开放平台 创建机器人，获取 AppID 和 AppSecret
2. 在 mykey.py 中添加：

qq_app_id = "你的APP_ID"
qq_app_secret = "你的APP_SECRET"
qq_allowed_users = ["用户openid"]  # 或 ['*'] 允许所有人

启动 QQ Bot：

python frontends/qqapp.py

首次发消息给机器人后，用户的 openid 会记录到 temp/qqapp.log。

Step 6: 接入飞书 Bot

飞书 Bot 支持文本、富文本、图片、文件、音频、交互卡片等多种消息格式。

安装依赖：

pip install lark-oapi

配置：

1. 在飞书开放平台创建企业自建应用，获取 AppID 和 AppSecret
2. 在 mykey.py 中添加：

fs_app_id = "cli_xxxxxxxxxxxxxxxx"
fs_app_secret = "xxxxxxxxxxxxxxxx"
fs_allowed_users = ["ou_xxxxxxxxxxxxxxxx"]  # 或 ['*'] 允许所有人

启动飞书 Bot：

python frontends/fsapp.py

Step 7: 验证与调优

所有 Bot 都支持这些通用命令：

• /new - 开启新对话，清空当前上下文
• /continue - 列出可恢复的会话快照
• /continue N - 恢复第 N 个历史会话

验证多平台同时接入：

如果你想同时运行多个 Bot，开多个终端窗口即可：

# 终端1：微信
python frontends/wechatapp.py

# 终端2：QQ
python frontends/qqapp.py

# 终端3：飞书
python frontends/fsapp.py

---

常见问题排查

1. API Key 配置后报认证错误

原因：变量名写错或 fake_cc_system_prompt 配置错误

解决：

• 确认变量名包含正确的关键字（native_claude、oai_config 等）
• 中转服务必须 fake_cc_system_prompt: True
• 检查 apibase 是否正确（如 Defapi 用 https://api.defapi.org）

2. 微信扫码后提示登录失败

原因：微信风控对新设备登录的限制

解决：

• 尝试在手机端确认登录（有时需要手机端二次验证）
• 确保微信账号没有异常行为
• 降低 Bot 使用频率，避免触发风控

3. QQ Bot 收不到消息

原因：机器人未启用或权限配置错误

解决：

• 在 QQ 开放平台确认机器人已启用
• 检查是否正确添加了事件订阅（需要订阅 私聊消息 事件）
• 查看 temp/qqapp.log 确认用户 openid 是否正确记录

4. 飞书 Bot 响应延迟高

原因：LLM 推理本身较慢，或网络延迟

解决：

• 使用更快的模型（如 GPT-4o-mini、MiniMax-M2）
• 检查网络到 LLM API 的延迟
• 适当降低 max_tokens 加快首 token 响应

5. Bot 无法记住对话上下文

原因：执行了 /new 命令或会话超时

解决：

• 使用 /continue 命令恢复历史会话
• 确认 memory/ 目录有写入权限
• 检查 temp/model_responses/ 目录是否有会话记录

6. 运行时报 ModuleNotFoundError

原因：缺少依赖包

解决：

# 让 Agent 自己安装
> 请帮我安装所有需要的 Python 依赖

# 或手动安装常见依赖
pip install requests pycryptodome qrcode streamlit pywebview

---

扩展阅读 / 进阶方向

浏览器自动化能力

解锁 Web 工具后，GenericAgent 可以在保留你登录态的真实浏览器中操作：

> 执行 web setup sop，解锁 web 工具

之后你可以这样用：

> 打开淘宝，搜索 iPhone 16，按价格排序
> 去 B 站，查看我最近看过的历史视频

浏览器插件位于 assets/tmwd_cdp_bridge/，支持 Chrome/Edge 等主流浏览器。

自我进化机制详解

GenericAgent 的核心差异在于每完成一个任务，自动将执行路径固化为 Skill。下次遇到类似任务，直接调用，无需重新摸索。

这意味着：

• 用得越久，Agent 越懂你的工作流
• 技能树完全属于你，不会与他人的"预设技能"雷同
• 3K 行种子代码，能生长出无限可能

Skill 库生态

社区已经积累了百万级 Skill 库（公众号文章），你可以：

• 让 Agent 搜索：帮我找个做 XXX 的 skill
• 直接导入：访问 XXX，按照这个 skill 做

进阶模式

GenericAgent 的所有高级功能都是自文档化的——直接问 Agent 即可：

编程能力与 Claude Code 对比

很多开发者关心一个问题：GenericAgent 能替代 Claude Code 或 Codex 吗？

答案是：能编程，但不能完全替代。

GenericAgent 的编程能力

GenericAgent 通过 code_run 工具执行任意代码，配合 file_read/file_write/file_patch 等文件操作，编程能力是完整的。只要配上擅长编程的模型（如 Claude、GPT-4o），它就能：

• 读写文件
• 执行命令行
• 调试代码
• 解释代码逻辑

# 配置 Claude 作为后端
native_claude_config = {
    'apikey': 'your-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,
}

然后直接用自然语言编程：

> 帮我写一个快速排序函数，然后运行测试
> 用 Python 实现一个 HTTP 服务器
> 解释一下这个 React 组件是怎么工作的

与 Claude Code / Codex 的区别

关键区别在于：Claude Code 通过自己的协议和工具链工作（类似 MCP），GenericAgent 无法直接调用它们。但有以下间接方式：

方式 1：Codeg 并行使用

Codeg 项目可以同时启动 GenericAgent + Claude Code + Codex，在同一个 UI 里协作：

# 把 GenericAgent 和 Codeg 放在同级目录
/workspace/
  ├── GenericAgent/
  └── codeg/

# Codeg 会自动检测到 GenericAgent，然后并行使用

方式 2：通过 API 中转

GenericAgent 的 NativeClaudeSession 走的是 Claude Code 兼容协议，如果中转服务（如 Defapi）支持 Claude Code 透传，你就能用 GenericAgent 调用 Claude 的编程能力：

# GenericAgent 用 Claude 的能力编程
native_claude_config = {
    'name': 'claude-defapi',
    'apikey': 'your-defapi-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,  # Claude Code 协议透传
}

结论

多实例与记忆隔离

GenericAgent 的记忆是项目级别的，不是全局的。这意味着如果你有多个项目，需要考虑如何管理记忆隔离。

记忆存储结构

GenericAgent/
├── memory/                     # 记忆目录
│   ├── global_mem.txt         # L2 全局事实
│   └── global_mem_insight.txt # L1 记忆索引
└── temp/
    └── model_responses/       # L4 会话归档

记忆层级与作用范围：

方案对比

方案 A：分别复制（最简单）

如果你的多个项目需要完全独立的记忆，直接复制仓库是最省心的方案：

# 每个项目一个 GenericAgent 副本
~/projects/project-a/generic-agent/   → 记忆 A
~/projects/project-b/generic-agent/   → 记忆 B
~/projects/project-c/generic-agent/   → 记忆 C

# 分别启动不同的 Bot
cd ~/projects/project-a/generic-agent && python frontends/wechatapp.py
cd ~/projects/project-b/generic-agent && python frontends/qqapp.py
cd ~/projects/project-c/generic-agent && python frontends/tgapp.py

方案 B：符号链接（代码集中）

如果你希望代码集中管理，用符号链接分离记忆：

# 1. 只克隆一份 GenericAgent
cd ~/workspace
git clone https://github.com/lsdefine/GenericAgent.git generic-agent-core

# 2. 项目 A 的 memory 链接
cd ~/projects/project-a
ln -s ~/workspace/generic-agent-core/memory ./ga-memory

# 3. 项目 B 的 memory 链接
cd ~/projects/project-b
ln -s ~/workspace/generic-agent-core/memory ./ga-memory

方案 C：--task 模式（适合一次性任务）

对于一次性任务，可以用 --task 模式通过 I/O 目录隔离：

# 任务 A
python agentmain.py --task project-a-task --input "帮我处理项目A的文件"

# 任务 B（独立的 I/O 目录）
python agentmain.py --task project-b-task --input "帮我处理项目B的文件"

每个任务有独立的 temp/project-a-task/ 和 temp/project-b-task/ 目录。

多 Bot 接入同一实例（记忆共享）

如果你同时跑微信 + QQ + 飞书 Bot，它们都连到同一个 GenericAgent 实例：

# 三个终端共享同一个 memory/ 目录
python frontends/wechatapp.py   # 终端1
python frontends/qqapp.py       # 终端2
python frontends/fsapp.py       # 终端3

迁移与清空记忆

# 迁移记忆到新项目
cp -r ~/old-project/GenericAgent/memory/ ~/new-project/GenericAgent/

# 选择性迁移某个文件
cp ~/old-project/GenericAgent/memory/global_mem.txt ~/new-project/GenericAgent/memory/

# 清空记忆，重新开始
rm -rf ~/projects/project-a/GenericAgent/memory/*

结论

---

Reference

• GitHub: lsdefine/GenericAgent
• Technical Report: arXiv:2604.17091
• 入门教程: Datawhale Hello GenericAgent
• 飞书配置指南: assets/SETUP_FEISHU.md