GenericAgent 部署与接入：在全平台构建微信/QQ/飞书机器人

项目概览

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

它的设计理念很有意思：不预设技能，而是通过进化获得能力。当 GenericAgent 完成一个新任务后，会自动把执行路径“固化”为 Skill。你使用得越久，累积的技能就越多——从最初这 3K 行种子代码出发，逐步长出完全属于你的个人技能树。

相比 OpenClaw（~530K 行代码），GenericAgent 走的是极简路线：部署非常容易（pip install + API Key），不需要复杂的多服务编排，但仍保留了核心能力——包括完整的浏览器控制、键盘/鼠标操作，以及通过 ADB 控制移动设备。

---

难度 / 时长 / 收获

• 难度：入门友好，不需要深度编程经验
• 时长：约 30 分钟
• 收获：掌握 GenericAgent 部署配置 + 接入三大 IM 平台（微信/QQ/飞书），让你随时随地用手机把 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。下次遇到类似任务时，它就能直接调用，而不需要重新探索。

这意味着：

• 用得越久，它越懂你的工作流
• 技能树完全属于你，不会与他人的“预设技能”雷同
• 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 协议透传
}

结论

---

参考

• GitHub: lsdefine/GenericAgent
• 技术报告： arXiv:2604.17091
• 入门教程: Datawhale Hello GenericAgent
• 飞书配置指南: assets/SETUP_FEISHU.md