大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



前些天阿里巴巴 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 的主流范式。

---

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
•  — 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 循环中可用

---

用户消息处理流程

用户发送消息    ↓渠道客户端（钉钉/飞书//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()    ↓渠道客户端显示结果