🐍 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。见权限指南
MCP 客户端	✅	stdio 服务器 · `{server}:{tool}` 命名空间 · 信任级别映射含 operator override（仅可降级）· `/mcp list / restart / logs` · 非阻塞启动 + `/health` advisory · `{env:VAR}` 密钥占位符。见 MCP 指南
Skill Hub	✅	ClawHub 兼容、渐进式披露、7 层目录发现(含 `.claude/skills/` 跨生态读)、`pyclaw-skill` CLI。见 skill-hub-compatibility.md
内置 Tier 2 工具	✅	进程内 `web_fetch`(httpx + markdownify)、`grep`(Python `re`,沙箱友好)、`glob`(按 mtime 排序)、可选 `fetch_mcp_resource`。全部 `tool_class="read"`,在 `bash` 被拒的 `tier=read-only` 下仍能用。见 builtin-tools.md
Prompt 工程	✅	`PromptBudgetConfig`、Frozen 缓存、优先级截断
TaskManager	✅	集中式异步任务生命周期、K8s 级优雅关闭
自我进化	✅	SOP 提取 + Curator 生命周期（30d/90d）+ ForgetTool + Skill Graduation v2 (可版本演进) + CLI
Session 亲和网关	✅	Active-active 多 worker 水平扩展、Redis 亲和注册 + PubSub 转发、PUBLISH-0 检测自动 failover
子代理系统	✅	5 层 discovery、`.md + frontmatter` 清单、独立上下文窗口、tier/sandbox/memory 继承、depth-1 限制、`/agents` 斜杠命令。MIT 许可清洁（零打包 persona）。`omit_memory_context` / `omit_skills_catalog` / `omit_working_memory` toggle 用于 token-economy 专用。见子代理指南。
工具输出压缩器	✅	4 策略管线（strip_ansi / regex_replace / collapse_whitespace / head_tail），8 条 builtin 规则覆盖 git/pytest/npm/pip/docker/web_fetch。`enable_output_compression: true` 默认开启，bash-heavy session 节省 ~30-50% 输入 token。借鉴 OpenHuman TokenJuice (clean-room)。
智能审批 (UX 层)	✅	`bash_approval_mode: "smart"` 自动放行 ~50 个 read 命令(`cat`/`ls`/`git status`/`python -c`/...)；写命令仍走审批 modal/CardKit。Audit log 记 `decided_by="auto:bash-smart-read"`。消除审批疲劳但不削弱沙箱。
Frozen Prefix 字节稳定	✅	14 个测试证明"90%+ prompt 缓存命中"声明可验证。OpenHuman KV-cache invariant 的 clean-room 借鉴。
Multi-Agent Delegate (V1.5 Phase 1 + Phase 2)	✅	Phase 1: 并行 fan-out (主代理同 turn N 个 sub_agent tool_call → `asyncio.gather` 并发) + `progress_batch_id` audit 关联 + fail-soft + `max_parallel_per_turn` (默认 5) + `reduce_subagent_results` 4 strategy + supervisor advisory。Phase 2 (streaming sub-agent output): 三点 emit (turn-start / per-tool-start / per-tool-end) + 6-state 状态机 (`thinking` → `tool_calling` → `tool_running` → `completed`/`failed`/`aborted`) + 250ms cross-sibling batching + Web SPA 5-color 调色板 + 飞书 CardKit `subagents_status` 元素 + `omit_streaming_progress` manifest toggle。8 V1 + 4 Phase 1 invariants + OH-2 14 byte-stability 全保留; V1 single-spawn (N=1) byte-identical。Phase 3 (cross-agent handoff) 等触发条件。显式不做：LangGraph DAG runtime、Hermes RPC mesh、token-by-token streaming。
Dreaming 引擎	🔲	规划中：Light/Deep/REM 三阶段记忆整理

测试统计： 2923 单元/集成测试 + 16 E2E (3 Phase 3 gated) · ~16K 行 Python · ~120 个源文件（截至 2026-05-29 V1.5 Phase 3 ship）

🎬 特性详解

4 层记忆 + 中文 FTS5

# L2/L3 检索命中 → 注入到 Prompt 的 Dynamic Zone 作为 <facts> / <procedures> XML
# 每轮 4 层都被检索，结果按优先级混合

# 中文查询直接可用
agent.run("帮我看一下飞书 streaming 模块的 token 限流策略")
# → FTS5 通过 jieba.cut_for_search 匹配 "飞书"+"streaming"+"token"+"限流"
# → Top procedures 被注入 Prompt

Hook 驱动的记忆流水线

class MyCustomHook(AgentHook):
    async def before_prompt_build(self, ctx):
        ctx.append_dynamic("<custom>...自定义内容...</custom>")
    async def after_response(self, ctx, response):
        # 每次回复后自动抽取事实
        ...

agent.hooks.register(MyCustomHook())

Frozen / Per-Turn 三段式 Prompt

graph LR
    subgraph Frozen["❄️ Frozen Prefix（缓存，命中率 90%+）"]
        F[identity · tools · skills · L1 snapshot]
    end
    subgraph Suffix["🔄 Per-Turn Suffix（每轮重建）"]
        S[runtime · working_memory · nudge]
    end
    subgraph Dynamic["🔍 Dynamic Zone（记忆检索）"]
        D[facts · procedures with entry_id]
    end

    Frozen ~~~ Suffix ~~~ Dynamic

    style Frozen fill:#e3f2fd,stroke:#1565c0
    style Suffix fill:#fff3e0,stroke:#e65100
    style Dynamic fill:#e8f5e9,stroke:#2e7d32

OpenAI 兼容 API

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"model":"pyclaw","messages":[{"role":"user","content":"hi"}],"stream":true}'

可对接 OpenWebUI / Lobe / NextChat 等任意 OpenAI 兼容客户端。

多实例生产部署

# docker-compose.yml
services:
  pyclaw:
    deploy: { replicas: 3 }       # 3 个 active-active worker
    environment:
      PYCLAW_AFFINITY_ENABLED: "true"
  redis:
    image: redis:7-alpine         # 共享状态 + 亲和注册表
  nginx:
    image: nginx:alpine           # ip_hash 反向代理
    volumes: [./deploy/nginx.conf:/etc/nginx/conf.d/default.conf]
    ports: ["80:80"]

双层 stickiness 设计：

Layer 1 — Nginx ip_hash：同一客户端 IP 固定路由到同一 worker（减少 forward 流量）
Layer 2 — Session 亲和网关：Redis 维护 session_key → worker_id 映射，保证同一 session 永远在同一 worker 处理。Nginx（或飞书 cluster mode）即使把消息分发到别的 worker，亲和层会通过 Redis PubSub 转发到 owner。Worker 死亡时通过 TTL 过期 + force_claim 自动接管。

本地 dev 反向代理（统一入口 localhost:9000 → 3 个 worker）：

make worker1     # terminal 1: PORT=8000
make worker2     # terminal 2: PORT=8001
make worker3     # terminal 3: PORT=8002
make nginx-start # 反向代理 :9000
make affinity-status   # 任意时刻查 Redis 亲和状态

详情参见 make help 与 reports/affinity-gateway-smoke-2026-05-15.md（真机 smoke 测试报告）。

📚 深度文章（公众号 Time留痕）

📖 完整文章合集 →

系列	标题	主题
A1	从 TypeScript 单体到存算分离	为什么重写 OpenClaw — 三条原则
A2	从 6000 行包装到 645 行单循环：我如何重写 OpenClaw 的 Agent 内核	六大 Agent 框架源码级对比（Claude Code / OpenClaw / OpenCode / DeerFlow / GenericAgent / Hermes）
D0	AI Agent 记忆系统的四种流派	Karpathy / 火山 / Shopify / YC 四家记忆思路对比
D1	你的 AI Agent 为什么总是"失忆"？	PyClaw 的 4 层记忆架构设计
D2	给 AI Agent 的记忆系统通上电	工具设计 + Hook 驱动 + APSW/jieba FTS5 修复
E1	给 Agent 加一个"心脏起搏器"：TaskManager 设计	异步任务生命周期管理
E11	Slash 命令系统：4 层分工驯服 21 个命令	CommandRegistry + ProtocolOp + Hook 多层分工
E12	Session Affinity Gateway：N worker 水平扩展	Affinity 双层 stickiness + (N-1)/N 转发
E17	权限系统：4 层 tier × per-user × per-MCP-server	工具审批系统四阶段演化
E18	运行时沙箱：基于 Anthropic srt 的系统实现	8 条架构不变量 + SandboxPolicy Protocol 三件套
E21	Sub-Agent 系统的 8 条架构不变量	Markdown manifest → isolated executor 全景
F13	stub-and-revert 测试方法论	unit + e2e 全绿不代表无错
B1	四种 Agent 架构路径：OpenClaw / Hermes / OpenHuman / PyClaw	四方对比 + 5 个借鉴招式 + 反向校准

系列代号：A（项目认知）· B（竞品解析）· C（上下文）· D（记忆+进化）· E（架构+安全）· F（方法论）

⚙️ 配置 & 部署

PyClaw 用单个 pyclaw.json 描述所有运行时配置，按 ./pyclaw.json、configs/pyclaw.json、~/.openclaw/pyclaw.json 顺序查找。配置参考文档按 5 个使用场景组织：本地开发、生产单实例、多实例 active-active、Feishu 机器人、记忆 + 自演化。

配置与运维：

配置参考（中文） · Configuration reference (EN) — 所有 Settings 字段、env-var 覆盖映射、按场景的最小可用 JSON（5 个场景）
部署指南（中文） · Deployment guide (EN) — 本地 dev、单实例 Docker、3-worker active-active（含可跑的 deploy/docker-compose.multi.yml）、无 Docker 的 make worker[1-3]
多用户部署（中文） · Multi-user deployment (EN) — UserProfile schema、per-user 默认 tier、role-based 权限（admin / member）、/admin user slash 命令
configs/pyclaw.example.json — 完整可执行模板（167 行）

安全与集成：

权限与工具审批（中文） · Permissions & tool approval (EN) — 三档权限（read-only / approval / yolo）、各 channel UX（Web modal vs 飞书 CardKit）、audit log schema
沙箱（中文） · Sandbox (EN) — @anthropic-ai/sandbox-runtime（srt）集成：macOS Seatbelt / Linux bubblewrap+seccomp、BashTool 与 MCP 子进程隔离、8 条不变量 manifest、production_require_sandbox 开关
MCP 服务器（中文） · MCP servers (EN) — Anthropic Model Context Protocol 集成：stdio server 配置、{env:VAR} 密钥、per-server forced_tier（仅可降级）、/mcp list/restart/logs、非阻塞启动、安全要点

🛠 CLI 工具

# Skill 管理
pyclaw-skill list                    # 列出已发现的技能
pyclaw-skill search github           # 搜索 ClawHub 市场
pyclaw-skill install github          # 安装技能
pyclaw-skill check                   # 资格检查（bins / env / OS）

# SOP 生命周期管理（Curator）
pyclaw-skill curator list --auto     # 活跃的自动提取 SOP
pyclaw-skill curator list --stale    # 30+ 天未使用（预警）
pyclaw-skill curator list --archived # 已归档 SOP（含原因）
pyclaw-skill curator restore <id>    # 恢复已归档的 SOP
pyclaw-skill curator graduate --preview  # 预览毕业候选
pyclaw-skill curator graduate            # 执行毕业
pyclaw-skill curator graduate --id <id>  # 指定 ID 强制毕业

# 实时记忆观测
.venv/bin/python scripts/verify_memory_live.py   # L1/L2/L3/L4 实时监控

🧪 测试

# 单元 + 集成（无外部依赖）
.venv/bin/pytest tests/ --ignore=tests/e2e

# 含真实 Redis
PYCLAW_TEST_REDIS_HOST=localhost .venv/bin/pytest tests/integration/

# 真实 LLM E2E
PYCLAW_LLM_API_KEY=sk-... .venv/bin/pytest tests/e2e/

2923 单元/集成测试 · 16 真 LLM E2E（3 Phase 3 gated） · ~16K 行代码 · ~120 个源文件（截至 2026-05-29 V1.5 Phase 3 ship）。

📁 项目结构

src/pyclaw/
├── core/                     # 计算层（无状态）
│   ├── agent/
│   │   ├── runner.py         # ~1100 行单循环
│   │   ├── system_prompt.py  # Frozen + Per-Turn 构建器
│   │   ├── tools/            # bash, read, write, edit, grep, glob, web_fetch, memorize, forget, update_working_memory, skill_view (+ fetch_mcp_resource opt-in)
│   │   ├── hooks/            # WorkingMemoryHook, MemoryNudgeHook
│   │   ├── compaction/       # 压缩子系统（planning, dedup, hardening, checkpoint, reasons）
│   │   └── factory.py        # 自动装配记忆工具 + Hook
│   ├── context_engine.py     # Bootstrap + 记忆检索 + assemble
│   ├── curator.py            # 后台 SOP 生命周期管理（扫描 → 归档 → 毕业）
│   ├── sop_extraction.py     # LLM SOP 提取（per-session）
│   ├── skill_graduation.py   # 高频 SOP 毕业为 SKILL.md
│   ├── memory_archive.py     # /new 时后台 L4 归档
│   └── hooks.py              # AgentHook / ToolApprovalHook / SkillProvider Protocol
├── storage/
│   ├── memory/               # 4 层记忆（composite, sqlite, redis_index, jieba_tokenizer, embedding）
│   ├── session/              # Redis + InMemory session
│   ├── workspace/            # File + Redis workspace
│   └── lock/                 # Redis 分布式锁
├── channels/
│   ├── feishu/               # WS receiver、CardKit 流式、斜杠命令
│   ├── web/                  # WebSocket + REST + OpenAI SSE + React SPA + admin
│   └── session_router.py     # SessionKey → SessionId 路由
├── skills/                   # Skill Hub（parser, discovery, eligibility, prompt, clawhub_client, installer）
├── infra/
│   ├── task_manager.py       # 集中式异步生命周期（spawn/cancel/drain）
│   ├── settings.py           # MemorySettings, EmbeddingSettings, PromptBudgetConfig
│   └── redis_client.py
├── cli/skills.py             # pyclaw-skill CLI
└── app.py                    # FastAPI 入口 + lifespan

🛡 安全与隔离

PyClaw 当前的隔离模型是单租户或可信团队 — Session 数据、Redis 键、飞书 Workspace、记忆存储按用户隔离, 但同一份部署内不同团队之间没有租户边界。适用场景: 一个团队跑自己的实例, 或者一份共享实例服务可信内部用户。Web 渠道为信任用户设计（Tool Approval Hook 管控高风险操作）。多租户 SaaS 部署需要走下面的升级路径。

详见 D26: 用户隔离模型 — 隔离边界、已知限制、多租户升级路径。

📖 文档

上手与运维

配置参考 — 所有 Settings 字段，按场景组织
部署指南 — 本地 dev / 单实例 Docker / 多实例 active-active

架构与设计

架构决策（D1–D26） — 全部设计选择与理由
会话系统设计 — SessionKey/SessionId、命令、空闲重置
上下文引擎 — assemble/ingest/compact Protocol
内置工具 — 11 个内置工具、Tier 2 web_fetch / grep / glob、沙箱旁路约定
Skill Hub 兼容性 — ClawHub 集成 + 7 层跨生态发现
用 gpt-image-2 画 infographic 实战指南 — 5 段式 prompt + 文字渲染纪律 + 完整 PyClaw 主图 prompt 解剖
开发路线图

英文文档：docs/en/

🗺 路线图

最近 ship（Sprint 6 / 7 / 8）

✅ 工具输出压缩器（OH-1） — 4 策略规则管线，bash-heavy session 节省 ~30-50% 输入 token（Sprint 6，2026-05-20 ship）
✅ Frozen Prefix 字节稳定不变量（OH-2） — 14 个测试证明"90%+ prompt 缓存命中"在跨 turn / 跨 section / dict 排序 / budget 截断后均成立（Sprint 6，2026-05-20 ship）
✅ 子代理 omit toggles（OH-3） — omit_memory_context / omit_skills_catalog / omit_working_memory token-economy 专用（Sprint 6，2026-05-20 ship）
✅ Skill Graduation v2（Follow-up B） — auto_generated SKILL.md 可被改进版 SOP 原子替换；旧版备份到 skill_history/<timestamp>（Sprint 7，2026-05-20 ship）
✅ S3 安全三件套 — env deny-floor 扩展（DATABASE_URL/REDIS_URL/DOCKER_HOST/VAULT_TOKEN/VAULT_ADDR）+ srt 版本检查（< 1.0.0 警告；production_require_sandbox=true fail-closed）+ Settings _comment_* 字段 strip（Sprint 7，2026-05-20 ship）
✅ WebSocket 鉴权失败循环修复 — close code 4001/4002/4003 触发 logout() + 跳转登录页，不再无限重连（Sprint 6.1，2026-05-20 ship）
✅ 智能审批（TA1, bash_approval_mode） — read 命令白名单自动放行，消除审批疲劳但不削弱沙箱（Sprint 8，2026-05-20 ship）
✅ S3- deferred 清理（8 fix + advisory + 3 核查后关闭非真问题）* — A13 srt 运行时 fallback / A7 zero-admin / F8 forward-compat / F4 source-grep→behavioral / F2 Windows 路径 / F5 inspect.signature / F7 fixture / B1B2 / E4 / F3+A14 advisory；A8/A11/A12 核查为非真问题（Sprint 9，2026-05-21 ship）

早期（Sprint 1–5）

✅ 记忆存储 — 4 层 SQLite-vec + FTS5 + jieba
✅ Web 渠道 — 多路复用 WebSocket、OpenAI 兼容 SSE、React SPA
✅ Skill Hub — ClawHub SKILL.md 解析、渐进式披露
✅ TaskManager — 集中式异步任务生命周期
✅ 自我进化 — SOP 提取 + Curator 生命周期 + ForgetTool
✅ Session 亲和网关 — Active-active 多 worker、Redis 亲和注册 + PubSub 转发（2026-05-14 真机 smoke 验证通过）
✅ Web UI MVP — Linear/Cursor 风视觉重构（2026-05-15 ship）
✅ MCP 客户端 — Anthropic Model Context Protocol 集成（Sprint 2）
✅ 用户隔离 + srt 沙箱 — Per-user tier profile + 角色权限 + Anthropic srt + 11 条架构不变量（Sprint 3，2026-05-16 ship）
✅ Tier 2 内置工具 — 进程内 web_fetch / grep / glob、.claude/skills/ 跨生态 7 源发现（Sprint 4'，2026-05-18 ship）
✅ Sub-Agent 系统 (A') — Markdown + YAML frontmatter、5 层 discovery、depth-1、license-clean MIT 分发（Sprint 5，2026-05-18 上线）

调研中（active）

✅ Multi-Agent Delegate V1.5 Phase 1 ship 2026-05-22 — 并行 fan-out + audit batch_id + fail-soft + reducer (4 strategy) + supervisor advisory + max_parallel rate limit。8 V1 不变量保留。Ship report: reports/multi-agent-delegate-v15-phase1-ship-2026-05-22.md。
✅ Multi-Agent Delegate V1.5 Phase 2 ship 2026-05-22 — streaming sub-agent output: 三点 emit + 250ms 跨兄弟 batching + 6-state 状态机 + Web SPA 5-color 调色板 + 飞书 CardKit subagents_status 元素 + omit_streaming_progress toggle + SubagentProgressEmitter (race-safe _dirty ordering) + Decision 9 sink-bypass-runner 架构。10 commits, 2694→2749 (+55 tests), 0 regression。8 V1 + 4 Phase 1 invariants + OH-2 14 byte-stability 全保留; N=1 byte-identical。Ship report: reports/multi-agent-delegate-v15-phase2-ship-2026-05-22.md。
✅ Multi-Agent Delegate V1.5 Phase 3 ship 2026-05-29 — supervisor-mediated 跨代理 handoff: 内置 request_handoff tool（sub-agent-only） + AgentManifest.can_handoff_to 二态 hybrid 白名单 + session-keyed Redis-persisted pending_handoffs (sha256-hashed key 防注入) + 确定性 LCS 匹配（NFC + 4-decimal round）+ effective_hop_index 关闭 reducer-merge cap bypass + 4 个 advisory 变体 (A/B/C/D) + 6 个新 audit event 类型。15 commits, 2760→2923 (+163 tests), 0 regression。8 V1 + 9 Phase 1 + 8 Phase 2 + 20 Phase 3 = 51 invariants 全保留。Ship report: reports/multi-agent-delegate-v15-phase3-ship-2026-05-29.md。

规划中

🔲 Dreaming 引擎 — Light/Deep/REM 三阶段记忆整理（提取 → 聚类 → 图谱）
🔲 PostgreSQL + pgvector — 生产级记忆后端（多 pod K8s 部署）
🔲 pyclaw migrate-from-openclaw — 给 OpenClaw 用户的迁移工具（对标 Hermes hermes claw migrate）
🔲 Plugin 平台 (B) — 跨 5 类注册表的统一扩展协议；V2+ backlog，触发条件 ≥3 个第三方 plugin 需求或 PyClaw 用户数 ≥ 10k（"marketplace 基建 < 10k 用户 premature"）

上面列表是高层 mirror。详细的 sprint 状态、依赖图、ship 报告、活跃 proposal 由维护者私下追踪；对外可见的架构变更通过 pull request 和公众号文章发布（公众号合集）。

🤝 与 OpenClaw 的关系

PyClaw 受 OpenClaw 启发，并设计为与其技能生态兼容。PyClaw 是独立的 Python 重新实现，不是 fork。它继承了领域模型（Session、Channel、Skill），但以记忆为一等公民重新设计了架构。

🧩 姊妹项目：KnowMe / 知我（暂未发布）

PyClaw 和 KnowMe / 知我 是同一作者的姊妹项目，命名都遵循「拼音 + 技术词」模式。两者解决的是 agent-memory 故事的互补两半：

PyClaw — Agent 运行时（本仓）：多通道（飞书 / Web）、4 层 L1-L4 记忆、Sub-agent 系统、沙箱、MCP client。
KnowMe — MCP-native 本地优先知识库：SQLite + jieba FTS5、Markdown、Obsidian 兼容，对外暴露 5 个只读 MCP tool。

说明：KnowMe 目前是私有仓库（未发布），公开发布预计跟着 v1 ship（约 2026-07）。公开后本节会补上仓库链接。在那之前，把 KnowMe 当作 PyClaw MCP-extension 路线的架构上下文来看就行。

两者怎么协作（KnowMe 公开 + 在 pyclaw.json 里启用之后）：

PyClaw agent  ──MCP 查询──▶  KnowMe vault          (今天已通,只读,
                                                    内部冒烟通过)
            ◀──MCP 写入──   KnowMe                  (规划中,KnowMe v1.5+)
            ─memorize─▶ PyClaw L4 写到 KnowMe vault (规划中)

PyClaw 今天就支持把 KnowMe 当 MCP server 接 — 接线骨架在 configs/pyclaw.json 的 mcp.servers.knowme（schema 见 configs/pyclaw.example.json），默认注释掉 / 关闭，等 KnowMe 公开后启用。内部冒烟（2026-05-18）：list_pages 返已索引 wiki 页、search "pyclaw" 返 jieba 分词后的全文命中。

边界契约（两个项目独立 ship）：

PyClaw 的 MCP client 把 KnowMe 当作有版本号的外部依赖 —— KnowMe tool schema 任何破坏性变更必须先公示再做破坏性提交，changelog 会随 KnowMe 仓公开发布。
反向（PyClaw 把自己包装成 MCP server，让 KnowMe 未来的 agent panel 可以调 PyClaw）是一个待立项的 PyClaw OpenSpec change —— 内部跟踪为 pyclaw-mcp-server-package，还没启动。

为什么是这个架构：KB 能力原本是 PyClaw 的 Sprint 4，2026-05-18 改交给 KnowMe，让 PyClaw 专注 agent runtime、KnowMe 专注 vault，MCP 是两者之间的协议。

📡 关注我们

微信公众号：Time留痕 — 持续分享 PyClaw 开发历程、AI Agent 架构设计、记忆系统、上下文工程。

📚 完整文章合集 →

🤝 参与贡献

欢迎 PR。openspec/ 目录跟踪所有架构变更 — 提交大型 PR 前请阅读活跃的提案。小型 PR（拼写、bug 修复）随时欢迎。

📜 许可证

MIT License — 自由使用、修改、分发，包括商业用途。

Name		Name	Last commit message	Last commit date
Latest commit History 339 Commits
agents		agents
configs		configs
deploy		deploy
docs		docs
reports		reports
scripts		scripts
src/pyclaw		src/pyclaw
tests		tests
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_EN.md		README_EN.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json

Folders and files

Latest commit

History

Repository files navigation

🐍 PyClaw

🎯 定位

四条设计承诺

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

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

适合 / 不适合

✨ 为什么做 PyClaw？

🚀 快速开始

作为飞书机器人 — 2 分钟

作为 Web Agent — 2 分钟

作为库使用

🧠 记忆系统（核心特性）

🔄 自我进化（新功能！）

🏛 架构图

📊 当前状态

🎬 特性详解

4 层记忆 + 中文 FTS5

Hook 驱动的记忆流水线

Frozen / Per-Turn 三段式 Prompt

OpenAI 兼容 API

多实例生产部署

📚 深度文章（公众号 Time留痕）

⚙️ 配置 & 部署

🛠 CLI 工具

🧪 测试

📁 项目结构

🛡 安全与隔离

📖 文档

🗺 路线图

最近 ship（Sprint 6 / 7 / 8）

早期（Sprint 1–5）

调研中（active）

规划中

🤝 与 OpenClaw 的关系

🧩 姊妹项目：KnowMe / 知我（暂未发布）

📡 关注我们

🤝 参与贡献

📜 许可证

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages