AI Agent平台CoPaw源码学习——CoPaw的架构概览

前些天阿里巴巴 AgentScope 团队发布了基于Python构建的类 OpenClaw 个人 AI 助手平台———— CoPaw 的V1.0版本，和 OpenClaw 一样它也是一个运行在用户自有环境中的 AI 助手，通过多种聊天渠道与用户交互，并支持按配置运行定时任务。

安装并体验了几天，个人感觉 CoPaw 的体感比 OpenClaw 更好，因为 CoPaw 本地化做的更好，并且控制台功能更完善，大部分功能都能通过WEB控制台配置，比 OpenClaw 易用性更好。

底层源码基于Python构建并已开源，整体项目结构化很好，源码可读性比 OpenClaw 高，抱着学习的态度，我决定接下来一段时间，每天抽些时间仔细阅读一下 CoPaw 的源码，向优秀的开发者们学习如何构建一个AI Agent平台，并定期向大家分享我的学习成果。

今天向大家分享的是 CoPaw 源码学习的第一篇：CoPaw架构概览。

技术栈概览

CoPaw 当前版本技术选型如下：

• 后端：Python 3.12+，基于 FastAPI + AgentScope
• 前端：React 18 + TypeScript + Ant Design，使用 Vite 构建
• Agent 框架：AgentScope（阿里巴巴开源的 Agent 框架）
• 任务调度：APScheduler 3.x
• 浏览器自动化：Playwright
• 许可证：Apache License 2.0

项目仓库地址：https://github.com/agentscope-ai/CoPaw

架构模式：分层单体 + 插件化扩展

CoPaw 采用分层单体架构 + 插件化扩展的模式，这是理解整个系统的关键：

分层架构：从用户交互到数据持久化，层层递进，职责清晰。

插件化架构：渠道（Channels）和技能（Skills）均可动态扩展——想接入新的聊天平台？写一个 Channel 插件就好；想增加新功能？创建一个 Skill 即可。

事件驱动：配置文件和 MCP 支持热重载，定时任务支持异步触发。

ReAct Agent 模式：AI Agent 采用 Reasoning-Action-Observation 循环——推理一步，执行一步，观察结果，再推理……这是当前大语言模型 Agent 的主流范式。

系统分层：8 层架构详解

CoPaw 系统分为 8 个主要层次，从上到下依次是：

层与层之间有明确的依赖关系：用户交互层通过 HTTP/WebSocket 调用 API 层，API 层通过 app.state 访问 Runner，Runner 创建 Agent 实例，Agent 调用 Tools 和 Skills，Skills 调用 LLM 进行推理。

核心组件深度解析

1. AgentRunner — 系统核心调度器

代码路径：src/copaw/app/runner/runner.py

这是系统的发动机。每次用户发送消息，都会走到这里：

stream_query(request)

接收查询请求后，Runner 会：

1. 提取 session_id、user_id、channel 信息
2. 构建 env_context（元数据）
3. 从 MCPClientManager 获取可用的 MCP 客户端
4. 为每次查询创建一个全新的 CoPawAgent 实例（无状态设计）
5. 加载 Session（通过 JSON 文件持久化）
6. 执行 ReAct 循环，流式返回结果
7. 保存 Session 状态

为什么要每次新建 Agent 实例？答案是无状态设计——避免共享状态带来的并发问题，状态通过 Session 文件持久化。

2. CoPawAgent — ReAct Agent 核心实现

代码路径：src/copaw/agents/react_agent.py

CoPawAgent 继承自 AgentScope 的 ReActAgent，是真正执行推理的部分。它的初始化流程是这样的：

1. _create_toolkit() — 注册 14 个内置工具：

• execute_shell_command（Shell 命令执行）
• read_file / write_file / edit_file（文件操作）
• grep_search / glob_search（文件搜索）
• browser_use（浏览器控制）
• desktop_screenshot（桌面截图）
• view_image / view_video（媒体查看）
• send_file_to_user（文件发送）
• get_current_time（获取时间）
• set_user_timezone（设置时区）
• get_token_usage（Token 统计）

2. _register_skills() — 加载技能 Markdown 文件，从 working directory 注册技能目录

3. _build_sys_prompt() — 从 AGENTS.md、SOUL.md、PROFILE.md 组装系统提示词

4. create_model_and_formatter() — 通过 ModelFactory 创建 LLM 模型

5. _setup_memory_manager() — 配置长期记忆（基于 ReMe）

6. ReAct 循环执行：

• Reasoning：LLM 推理当前状态
• Action：调用 Tool 或 Skill
• Observation：获取结果，继续推理或完成

3. Channel System — 多渠道通信

BaseChannel（src/copaw/app/channels/base.py）是所有渠道的基类，定义了统一的消息处理接口：

• consume_one(payload) — 消费队列中的消息
• _consume_one_request(payload) — 将原生消息转为 AgentRequest
• send_content_parts() — 发送消息回渠道（子类实现）

ChannelManager（src/copaw/app/channels/manager.py）管理所有渠道的生命周期：

• from_config() — 根据配置初始化渠道
• start_all() / stop_all() — 启停所有渠道
• 维护异步消息队列和消费者 Worker

支持的渠道包括：

• Console — Web 界面
• 钉钉 — DingTalk Stream SDK
• 飞书 — Lark OpenAPI
• Discord — discord.py
• QQ — OneBot 协议
• Telegram — python-telegram-bot
• 企业微信 — WeCom Work API
• 微信 — WeChat API
• iMessage — macOS AppleScript
• MQTT — MQTT 物联网协议
• Matrix — Matrix 协议
• Mattermost — Mattermost 集成

4. Skills System — 技能系统

SkillService（src/copaw/agents/skills_manager.py）管理技能的完整生命周期：

• 内置技能（package 内置）
• 已激活技能（从 package 同步到用户目录）
• 工作区技能（运行时加载）

技能加载流程：

builtin skills (package)    ↓ syncactive skills (user data dir)    ↓ sync  working skills (working dir)    ↓ registerCoPawAgent.toolkit.register_agent_skill(skill_dir)

内置技能包括：

• browser_cdp / browser_visible（浏览器控制）
• cron（定时任务）
• file_reader（文件读取）
• news（新闻摘要）
• pdf / docx / xlsx / pptx（Office 文档处理）
• guidance（安装与配置指导）
• copaw_source_index（源码索引）
• multi_agent_collaboration（多 agent 协作）
• channel_message（渠道消息）
• dingtalk_channel（钉钉集成）
• himalaya（邮件处理）

SkillsHub 支持从远程市场安装技能——搜索、安装，一键搞定。

5. MCP 集成 — 扩展工具生态

MCP（Model Context Protocol）是 AI 工具生态的新标准。CoPaw 的 MCP 集成：

MCPClientManager 管理所有 MCP 客户端连接：

• 从 config.json 读取配置
• 创建 StdIO 客户端
• 支持热重载（修改配置后自动重连）

MCPConfigWatcher 监听配置文件变化，触发热重载。

每次查询时：

1. mcp_manager.get_clients() 获取客户端列表
2. agent.register_mcp_clients() 注册到 toolkit
3. MCP 工具在 ReAct 循环中可用

数据流分析

用户消息处理流程

用户发送消息    ↓渠道客户端（钉钉/飞书/QQ/Discord/iMessage/Console）    ↓Channel（将原生消息转为 AgentRequest）    ↓Channel Manager（异步队列 → 消费者 Worker）    ↓AgentRunner.stream_query(request)    ↓创建新 CoPawAgent 实例    ↓加载 Session（JSON 文件）    ↓ReAct 循环：  ├─ Reasoning：LLM 推理  ├─ Action：调用 Tool/Skill  └─ Observation：获取结果 → 继续推理或完成    ↓流式返回响应事件    ↓Channel.send_content_parts()    ↓渠道客户端显示结果

定时任务流程

APScheduler 触发    ↓CronExecutor.execute()    ↓AgentRunner.stream_query (cron 指令)    ↓Agent 执行任务    ↓CronManager 将结果推送到目标渠道

配置热重载流程

用户修改 config.json    ↓ConfigWatcher 检测文件变化    ↓重新加载配置    ↓├─ Channel Manager 重启变更的渠道└─ MCP Config Watcher 重新初始化 MCP 客户端

扩展性设计

CoPaw 在四个维度上提供了出色的扩展能力：

1. 渠道扩展

所有渠道继承 BaseChannel 基类，通过 Channel Registry 注册。配置驱动——在 config.json 中添加渠道配置即可启用。第三方渠道可通过 custom_channels/ 目录安装。

2. 技能扩展

Markdown 格式的技能描述文件，三级目录系统：内置 → 已激活 → 工作区。Skills Hub 支持从 Marketplace 安装，用户可在 customized_skills/ 目录创建自定义技能。

3. MCP 扩展

支持标准 MCP 协议，config.json 中配置 MCP Server 即可，自动注册为 Agent 可用工具。

4. 模型扩展

Provider Registry 支持注册新的 LLM 供应商。本地模型支持 llama.cpp 和 MLX 后端，Ollama 管理器支持 Ollama 服务。

技术选型说明

性能与安全

性能方面：

• 异步处理：FastAPI + asyncio 全异步架构
• 流式响应：Agent 结果流式返回，减少等待
• 每查询一实例：Agent 无状态，避免共享状态问题
• 异步消息队列：渠道消息通过 asyncio 队列处理，支持并发

安全方面：

• 本地部署：数据不外传
• API Key 管理：通过环境变量或配置文件管理
• 渠道过滤：COPAW_ENABLED_CHANNELS 控制可用渠道

总结

CoPaw 是一个设计精良的本地 AI Agent 平台：

• 本地优先：数据和任务均在用户本地运行，无需第三方托管
• 多渠道接入：钉钉、飞书、QQ、Discord、iMessage、Console，统一消息处理
• 技能系统：可扩展的技能机制，内置 PDF、文件处理、浏览器控制等能力
• MCP 生态：支持 Model Context Protocol，无缝接入外部工具
• ReAct 模式：基于 AgentScope 的推理-行动-观察循环
• 热重载：配置变更和 MCP 客户端变更自动生效

如果你想在本地部署一个 AI 助手，CoPaw 值得关注。