🐍 PyClaw

生产级 Python AI Agent 框架 — 4 层持久化记忆 · Hook 驱动架构 · 存算分离

中文（当前） · English · 📚 公众号 Time留痕 文章合集 →

---

🎯 定位

团队自己的 AI Agent — 住在你团队聊天的地方，有可复利的记忆，有可衡量的进化，有企业级的隔离。

大多数 AI agent 每次对话都从空白起步：用户不停重复上下文、重复约定、重复工具栈。PyClaw 押注相反方向：一个嵌入团队沟通平台的 agent，跨周记忆，自动学会团队反复执行的 playbook，按团队的审批流程运行。

四条设计承诺

• 🧠 记忆是 tier-zero，不是插件。 会话、事实、流程、向量归档 — 四层 L1-L4 记忆，全部进 agent 主循环，每轮都检索。中文 FTS5 + jieba 分词原生支持，30 天预警 + 90 天归档生命周期由 Curator 异步执行，分布式安全。少了这一层，剩下的只是套壳。
• 📈 agent 越用越有用**，不是越用越话多。** 成功会话自动抽取 SOP；高频 SOP 自动毕业为可复用 SKILL.md（v2 支持版本演进，旧版进 skill_history/）；过时的由 agent 主动 forget。无需微调，无 vendor lock。14 个 byte-stability 测试为"90%+ prompt cache 命中"背书，不只是宣传。
• 💬 群内原生，不是 IDE 原生。 飞书 CardKit + Web React SPA 共用同一个 agent 内核，Session Affinity Gateway 支持 active-active 多 worker 水平扩展（Redis 亲和注册 + PubSub 跨 worker 转发，3-worker 真机 smoke 验证通过）。设计师、PM、运维跟工程师对同一个 agent，不切换 surface。
• 🛡 企业级治理是地板，不是 enterprise 加价项。 三档权限（read-only / approval / yolo）+ per-user profile + Anthropic srt 真 OS 沙箱（macOS Seatbelt / Linux bubblewrap+seccomp，8 条架构不变量 + fail-closed）+ 结构化 JSON 审计 + 飞书 originator-only CardKit。开箱即用,第一天就能跑。

PyClaw 在 agent 版图里的位置 — 以及不在的位置

2026 年的 agent 版图分化为四条路径，各自押注不同象限：

路径	代表项目	优化目标	致命短板
IDE 编程 agent	Claude Code · Cursor · OpenCode · Aider	单个开发者 + 单个编辑器 + 深度代码理解	没有团队记忆，没有审批
OAuth 个人助手	OpenHuman (21k★, 3 个月)	100+ OAuth 预接入服务把冷启动时间压到几分钟	desktop-only，无 server 形态，企业 IT 不允许接 118 个外部 OAuth
自我进化学习型 agent	Hermes (Nous Research, 160k★)	agent 持续重写自己的 skill 库（自我进化最深）	单 gateway 假设，没有 server 多 worker 水平扩展
团队级企业 agent	PyClaw	团队累积 institutional memory，沙箱 + 审计 + 多 channel 开箱即用	冷启动靠对话积累（不接 OAuth），自我进化深度不及 Hermes

PyClaw 走第 4 条路。 我们不跟 Claude Code 比 IDE 抛光、不跟 OpenHuman 比 OAuth 数量、不跟 LangGraph 比 graph-state runtime。我们竞争一句话：团队有自己的 institutional memory，agent 是这个团队的一员。

反向校准 — PyClaw 已经领先的六个维度

调研完 OpenClaw / Hermes / OpenHuman 三家后的诚实结论（详见 B1 公众号文章对比表）：

维度	OpenClaw	Hermes	OpenHuman	PyClaw
多 worker 水平扩展	✅ 多实例	❌ 单 gateway	❌ desktop-only	✅ Session Affinity Gateway + PubSub 转发
企业级 OS 沙箱	❌ 无内置	⚠️ container	⚠️ Landlock + bwrap	✅ Anthropic srt + 8 条不变量 + fail-closed
中文 FTS	❌	❌	❌	✅ FTS5 + jieba + 停用词 + trigram→jieba 自动迁移
企业工具审批	✅ CardKit	⚠️ command list	❌ 仅桌面弹窗	✅ Web modal + 飞书 CardKit + originator-only + 三档权限
跨生态 Skill 发现	⚠️ 自家	✅ agentskills.io	⚠️ 自家 + QuickJS	✅ 7 层 discovery（跨读 Claude Code / OpenCode / Crush / Cursor 等）
测试规模	N/A	⚠️ 部分 e2e	⚠️ 部分 e2e	✅ 2749 单元/集成 + 13 真 LLM E2E

适合 / 不适合

• ✅ 适合你：住在飞书或 Web console 的工程 / 运维 / 产品团队，每周重复某些工作流，需要一个用越久越懂团队、不会跨租户泄露秘密、有审计可追溯的 agent。
• ❌ 不是你的工具：单兵开发者想要最深的 IDE 集成（用 Claude Code / Cursor）；想要第一天就懂你邮件 / 日历的个人助手（用 OpenHuman）；任意 multi-agent DAG 编排框架（用 LangGraph）。

四条路径的 6,000 字深度对比（含源码级证据 + 5 个借鉴招式 + 反向校准）见公众号文章：OpenClaw / Hermes / OpenHuman / PyClaw 四种 Agent 架构路径。

---

✨ 为什么做 PyClaw？

OpenClaw 是一个优秀的多通道 AI 助手 — 但它的 TypeScript 单体（17,000+ 文件）将计算和存储紧耦合，且缺少生产级的记忆系统。PyClaw 用 Python 从头重写，定位 记忆优先 · Hook 驱动 · 水平可扩展：

• 🧠 4 层记忆系统 — L1 Redis 热索引 → L2 事实 → L3 流程 → L4 向量归档。生产级，已完整集成到 Agent 主循环。
• 🔄 自我进化 — 自动从会话中提取 SOP、生命周期管理（30 天预警 / 90 天归档）、Agent 可主动遗忘过时流程、高频 SOP 自动毕业为 Skill。Skill graduation v2 让改进版 SOP 可以原子替换旧的 auto_generated SKILL.md（旧版备份到 skill_history/）。无需微调。
• 🪝 Hook 驱动架构 — 记忆注入、Working Memory、Nudge 提醒、工具审批、输出压缩 — 全部以 Hook 形式接入。可自定义扩展，不动核心。
• ☁️ 存算分离 — 计算层完全无状态，可水平扩展。Session 在 Redis，记忆在 SQLite/Redis，向量经 litellm。
• 🌐 多渠道接入 — 飞书 WebSocket 集群 + Web 渠道（React SPA + OpenAI 兼容 /v1/chat/completions SSE）。
• 🚦 Session 亲和网关 — Active-active 多 worker 水平扩展，Redis 亲和注册 + PubSub 跨 worker 转发。同一 session 永远落同一 worker，不论飞书/LB 怎么 dispatch。Worker 死亡时通过 TTL + PUBLISH-0 检测自动 failover。
• 🇨🇳 中文优化 — FTS5 + jieba 分词，支持中文全文检索。停用词过滤，trigram → jieba 自动迁移。
• 🎯 Prompt 预算工程 — Frozen Prefix（可缓存）+ Per-Turn Suffix（动态）+ Dynamic Zone（按 prompt 检索）。14 个 byte-stability invariant 测试证明"90%+ prompt 缓存命中"是可验证事实，不是宣传（OpenHuman KV-cache invariant 的 clean-room 借鉴）。
• 🗜 工具输出压缩器 — 在 tool result 进入 LLM history 之前用 4 策略管线（strip_ansi / regex_replace / collapse_whitespace / head_tail）规则压缩。8 条 builtin 规则覆盖 git diff/log/status / pytest / npm/pip install / docker / web_fetch。bash-heavy session 节省 ~30-50% 输入 token。借鉴 OpenHuman TokenJuice（clean-room 重实现，OpenHuman 是 GPL-3.0）。
• 🛡 智能审批（无审批疲劳） — bash_approval_mode: "smart" 自动放行 cat/ls/git status/python -c 等 ~50 个 read 命令，写命令仍然弹审批。审批是 UX 层，不是安全层；安全由 srt 沙箱兜底。
• 🤖 Sub-Agent 系统 — Markdown manifest + isolated executor + 8 条架构不变量（沙箱/tier/abort/workspace/memory 继承是结构性的，不是 runtime 检查）。5 层 discovery，license-clean（零 bundled persona），用户自带。omit_memory_context / omit_skills_catalog / omit_working_memory toggle 让 token-economy 专用 agent（如 summarizer、reviewer）省 token。

---

🚀 快速开始

超出 2 分钟上手范围？ 跳到 § 配置 & 部署 查阅完整指南：本地 dev、单实例 Docker、3-worker active-active、多用户隔离、沙箱、MCP 服务器、工具审批。

作为飞书机器人 — 2 分钟

git clone https://github.com/Timeflys2018/pyclaw.git && cd pyclaw
python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# 在 configs/pyclaw.json 配置飞书 App 凭证
./scripts/start.sh

📖 更多：完整 pyclaw.json schema 见 配置参考, 或直接复制 configs/pyclaw.example.json。生产单实例部署：部署指南 § 单 Docker。

作为 Web Agent — 2 分钟

./scripts/start.sh                # 启动后端 + 自动构建 React 前端
open http://localhost:8000        # 登录（默认 admin / changeme）

Web 渠道开箱即用：流式聊天（含执行轨迹面板：工具调用 + 记忆命中 + token 用量） · 多模态输入（粘贴 / 拖拽 / 选择图片） · ⌘K 命令面板 · 全局快捷键 · 会话重命名 + 删除 · 双主题（明暗） · 工具审批 UI · OpenAI 兼容 API（可对接第三方客户端）。

📖 更多：调整三档权限模型（read-only / approval / yolo）见 权限指南。挂 MCP 服务器（GitHub、filesystem 等）见 MCP 指南。多用户团队部署 + per-user tier 隔离见 多用户部署。

作为库使用

from pyclaw.core.agent.factory import build_agent_runner
from pyclaw.infra.settings import load_settings

settings = load_settings("configs/pyclaw.json")
runner = build_agent_runner(settings)

async for event in runner.run("帮我看一下这个 Python 报错..."):
    print(event)

📖 更多：Settings 类型、Hook、Agent 主循环 API 见 架构决策（D1–D26）和 Context Engine。

---

🧠 记忆系统（核心特性）

记忆系统是一个 4 层流水线，集成到每一次 Prompt 拼装：

flowchart LR
    User["用户提问"] --> L1["L1: Redis<br/>Working Memory<br/>(按 session)"]
    User --> L2["L2: SQLite + FTS5<br/>事实<br/>(jieba 分词)"]
    User --> L3["L3: SQLite + FTS5<br/>流程 / SOP"]
    User --> L4["L4: SQLite + sqlite-vec<br/>会话归档"]

    L1 -.snapshot.-> Prompt["Frozen Prefix"]
    L2 -.facts ≤3.-> Dynamic["Dynamic Zone"]
    L3 -.procedures ≤2.-> Dynamic
    L4 -.语义检索.-> Dynamic

    Prompt --> Agent[Agent 主循环]
    Dynamic --> Agent

    style L1 fill:#fff3e0,stroke:#e65100
    style L2 fill:#e8f5e9,stroke:#2e7d32
    style L3 fill:#e8f5e9,stroke:#2e7d32
    style L4 fill:#e3f2fd,stroke:#1565c0

驱动它的 Hook（不修改 LLM 侧）：

Hook	作用
WorkingMemoryHook	每轮注入 <working_memory> XML（按 session 的 Redis KV）
MemoryNudgeHook	每 10 轮提醒 Agent："考虑使用 memorize"。使用后计数器归零
archive_session_background	/new 时把旧 session 异步归档到 L4 + 向量化（不阻塞）
ContextEngine.assemble	按用户提问检索 L2/L3，注入 Top-K 事实 + 流程

Agent 自己调用的工具：

• memorize — 持久化到 L2（事实）或 L3（流程）。"无执行不写入"原则。
• forget — 归档过时/失败的 SOP。Agent 主动的生命周期管理。
• update_working_memory — 按 session 的临时记事本（1024 字符上限，7 天 TTL，FIFO 淘汰）。
• skill_view — 渐进式披露：按需加载完整 SKILL.md 内容。

---

🔄 自我进化（新功能！）

PyClaw 的 Agent 能自我改进 — 无需微调、无需重训：

flowchart LR
    subgraph Extract["1. 提取"]
        A[任务] --> B[Tracker Hook]
        B --> C{Session 结束?}
        C -->|阈值满足| D[LLM 提取]
        D --> E[去重 + 写入 L3]
    end

    subgraph Curate["2. 维护"]
        E --> F[Search 命中<br/>递增计数]
        F --> G{90天未用?}
        G -->|是| H[归档]
        I[forget 工具] --> H
    end

    subgraph Graduate["3. 毕业"]
        F --> J{计数 ≥ 5<br/>存活 ≥ 7天?}
        J -->|是| K[SKILL.md]
        K --> L[skill_view]
    end

    style Extract fill:#e8f5e9,stroke:#2e7d32
    style Curate fill:#fff3e0,stroke:#e65100
    style Graduate fill:#e3f2fd,stroke:#1565c0

进化时间线：

时间	发生什么
第 1 天	Agent 正常执行任务
第 7 天	从成功会话中自动提取可复用 SOP
第 30 天	未使用的 SOP 标记为 stale（仍可用，CLI 可见）
第 60 天	Agent 发现过时 SOP 时主动调 forget 归档
第 90 天	Curator 自动归档仍未使用的 SOP
第 90+ 天	高频 SOP 毕业为 SKILL.md（渐进式披露加载）

核心设计思想：

• 严格拒绝 — 宁可不学也不学错
• stale 是计算属性 — 不写 DB，search 逆转完全自动
• 确定性 + Agent 驱动 — Curator 管时间衰减；forget 管质量判断
• 分布式安全 — Redis SETNX 保证多实例只有一个 Curator 运行

---

🏛 架构图

graph TB
    subgraph Channels["🌐 通道"]
        CH[飞书 WebSocket · Web WS · OpenAI SSE]
    end

    subgraph Compute["☁️ 计算层 — 无状态 Worker"]
        direction TB
        Runner["Agent Runner · ~1100 行单循环<br/>Frozen Prefix · Per-Turn Suffix · Prompt 预算"]
        Tools["工具: bash · read · write · edit · grep · glob · web_fetch<br/>memorize · forget · update_working_memory · skill_view"]
        Hooks["Hook: WorkingMemory · MemoryNudge · ToolApproval · SopTracker"]
        CE["Context Engine: assemble + 记忆检索 + compact"]
        Infra["基础设施: TaskManager · Curator · Skill Graduation · Settings"]
    end

    subgraph Storage["💾 存储层"]
        direction TB
        Redis[("Redis<br/>Sessions · 分布式锁 · L1 索引 · Working Memory")]
        Memory[("SQLite + FTS5 + jieba<br/>L2 事实 · L3 流程")]
        Vec[("sqlite-vec<br/>L4 会话归档")]
        Embed["Embedding API · litellm"]
    end

    CH --> Runner
    Runner --> Tools
    Runner --> Hooks
    Runner --> CE
    Hooks --> Redis
    CE --> Memory
    CE --> Vec
    CE --> Embed
    Infra --> Redis

    style Channels fill:#e3f2fd,stroke:#1565c0
    style Compute fill:#f3e5f5,stroke:#6a1b9a
    style Storage fill:#e8f5e9,stroke:#2e7d32

---

📊 当前状态

模块	状态	亮点
Agent Core	✅	~1100 行单循环、11 个内置工具（Tier 2:web_fetch / grep / glob）、Hook 系统、5 文件压缩子系统、frozen-prefix byte-stability invariant
记忆系统	✅	4 层（L1/L2/L3/L4）、FTS5 + jieba、sqlite-vec、trigram → jieba 自动迁移
上下文引擎	✅	Frozen/Per-Turn 拆分、记忆检索、L1 snapshot、Prompt 预算
会话存储	✅	Redis（生产）+ InMemory（开发）、SessionKey/SessionId 轮换、DAG 树
飞书渠道	✅	WebSocket 集群（最多 50 worker）、CardKit 流式、斜杠命令
Web 渠道	✅	React 19 SPA · Linear/Cursor 视觉 · 执行轨迹 · 多模态 · ⌘K 命令面板 · 键盘快捷键 · 会话 CRUD · OpenAI 兼容 SSE · JWT 认证 · 工具审批 modal + 三档权限 (read-only / approval / yolo)
工具审批	✅	端到端接通: WebToolApprovalHook + 飞书 CardKit 交互卡片 (originator-only 授权) · per-turn 切档 · 结构化 JSON audit log。见权限指南
*