概念总览¶

本文档简要介绍 pyclaw 的核心概念，帮助你理解系统的工作方式。完整的技术细节请参阅 架构设计文档。

Gateway¶

Gateway 是 pyclaw 的核心服务进程，负责接收来自各通道和客户端的消息，路由到 Agent 处理，并将回复发送回去。

Chat Apps ──┐
CLI ────────┼── Gateway ── Agent Runtime
UI ─────────┤
API ────────┘

Gateway 基于 FastAPI 构建，暴露两套 API：

• WebSocket RPC（ws://localhost:18777/ws）：双向实时通信，支持 25+ 方法（chat、sessions、config 等）
• OpenAI 兼容 HTTP（/v1/chat/completions、/v1/models）：可替代 OpenAI SDK 使用

启动 Gateway：pyclaw gateway，默认监听 127.0.0.1:18777。

详见: API 参考 · 配置说明

Agent 运行时¶

Agent 运行时是消息处理的核心循环。收到用户消息后，Agent 执行以下流程：

1. 将用户消息追加到会话
2. 构建系统提示（AGENTS.md + Skills + 上下文）
3. 调用 LLM 流式生成回复
4. 如果 LLM 发出工具调用，执行工具并将结果返回给 LLM
5. 循环直到 LLM 完成回复（无更多工具调用）
6. 将回复追加到会话并推送给客户端

多 Provider 支持¶

pyclaw 统一了不同 LLM 的流式接口，支持 OpenAI、Anthropic、Google Gemini、Ollama 以及 20+ OpenAI 兼容提供商。切换 Provider 只需修改配置，Agent 逻辑无需变动。

思维模式¶

通过 thinking 配置控制 LLM 的推理深度：

• disabled — 直接生成
• low — 简短推理
• high — 深度推理（token 消耗更大）

详见: 架构设计 — Agent Runtime

会话¶

会话（Session）是 Agent 与用户交互的完整对话历史，以 JSONL DAG 格式存储在 ~/.pyclaw/sessions/ 下。

会话范围¶

会话重置¶

会话支持定时重置和空闲重置：

• 定时重置：每天指定时间（如凌晨 4 点）创建新会话
• 空闲重置：空闲超过指定时间后自动新建

会话压缩¶

当会话过长时，系统自动进行压缩（compaction），移除早期消息并注入摘要，保持上下文窗口在合理范围内。

多 Agent 路由¶

pyclaw 支持同时运行多个 Agent，通过 7 级优先级路由 决定由哪个 Agent 处理消息：

1. 会话绑定（session → agent）
2. 线程绑定（thread → agent）
3. 通道绑定（channel → agent）
4. 群组绑定（chat_id → agent）
5. 用户绑定（sender → agent）
6. 全局绑定（pattern match）
7. 默认 Agent

通过 bindings 配置实现路由：

{
  bindings: [
    { agent: "work", match: { channel: "telegram" } },
    { agent: "home", match: { channel: "discord" } },
  ],
}

工具¶

Agent 在对话过程中可以调用 20+ 内置工具 完成任务：

命令执行审批¶

危险操作（如 shell 命令）需要通过审批：

• allowlist — 匹配的命令直接执行
• denylist — 匹配的命令直接拒绝
• 其他命令 — 推送审批请求到 UI/CLI，等待用户确认

工作区沙箱¶

工具操作默认限制在配置的工作区目录内（tools.restrictToWorkspace），文件路径会经过规范化以防止目录遍历。

MCP (Model Context Protocol)¶

pyclaw 支持通过 MCP 协议连接外部工具服务器，扩展 Agent 的能力。支持两种传输方式：

• stdio — 启动本地子进程通信
• HTTP — 连接远程 MCP 端点

MCP 服务器中的工具在 Gateway 启动时自动发现，并注册到 Agent 工具池。配置格式与 Claude Desktop / Cursor 兼容。

MCP 配置支持热重载 — 修改 tools.mcpServers 后自动断开旧连接并重新连接。

检查状态：pyclaw mcp status

记忆¶

pyclaw 实现了双引擎混合记忆系统：

• SQLite FTS5 — 全文检索，基于关键词匹配
• LanceDB — 向量搜索，基于语义匹配

两个引擎的结果通过混合排序（MMR + 时间衰减）融合，近期记忆权重更高。

Agent 可通过 memory_search 和 memory_store 工具主动使用记忆。

Active Memory¶

Active Memory 是一个自动记忆检索子系统，在 Agent 生成回复前自动检索相关记忆并注入上下文。

工作原理¶

用户消息 → Active Memory 检索 → 注入上下文 → LLM 生成回复

查询模式¶

提示风格¶

会话控制¶

# 启用 Active Memory
pyclaw active-memory on --session <session-id>

# 禁用 Active Memory
pyclaw active-memory off --session <session-id>

# 查看状态
pyclaw active-memory status

Wiki¶

Wiki 是一个结构化知识库系统，同时面向人类用户和 AI Agent。

目录结构¶

wiki/
├── entities/       # 实体页面（人物、公司、项目）
├── concepts/       # 概念页面（想法、模式、技术）
├── syntheses/      # 综合页面（摘要、分析）
├── sources/        # 源文档（触发编译）
├── reports/        # 自动生成的报告
├── _attachments/   # 附件（图片、文件）
├── _views/         # 视图和查询
├── AGENTS.md       # Agent 指令
├── WIKI.md         # Wiki 系统说明
├── index.md        # 首页索引
└── inbox.md        # 待处理项

Claim/Evidence 模型¶

Wiki 使用 Claim（声明）+ Evidence（证据）模型管理知识：

• Claim: 一个可验证的陈述，包含置信度、状态、标签
• Evidence: 支持或反驳 Claim 的来源，包含文件路径、行号、权重

Claim 状态：active（活跃）、superseded（已取代）、refuted（已反驳）

区块标记¶

使用区块标记保护人工编辑内容：

<!-- BEGIN BLOCK: human-edit -->
这部分内容在编译时会被保留
<!-- END BLOCK: human-edit -->

Memory Bridge¶

MemoryBridge 同步 Wiki 与 MemoryDirectory：

• 从 MEMORY.md 提取结构化信息到 Wiki
• 将 Wiki Claim 同步回 MemoryDirectory
• 保持两者一致性

# 初始化 Wiki
pyclaw wiki init

Dreaming¶

Dreaming 是记忆巩固子系统，模拟人类睡眠周期进行记忆整理。

三阶段周期¶

六维评分算法¶

每个候选记忆从六个维度评分（权重可配置）：

自动提升¶

满足条件的记忆自动提升到 MEMORY.md：

• 综合得分 ≥ min_score（默认 0.5）
• 召回次数 ≥ min_recall_count（默认 2）
• 独立查询数 ≥ min_unique_queries（默认 2）

配置示例¶

{
  "dreaming": {
    "enabled": true,
    "cron": "0 3 * * *",
    "limit": 10,
    "minScore": 0.5,
    "storage": "inline"
  }
}

消息通道¶

通道是连接外部消息平台的插件。每个通道实现统一的 ChannelPlugin 接口：

• start() / stop() — 生命周期管理
• send_reply() — 发送回复
• on_message() — 注册消息回调

pyclaw 内置 25 个通道，涵盖 Telegram、Discord、Slack、WhatsApp、DingTalk、QQ、Feishu、Matrix、IRC 等主流平台。

DM 与群组策略¶

每个通道可独立配置 DM 策略（dmPolicy）和群组策略（groupPolicy）：

• pairing — 未知发送者需通过配对码验证
• allowlist — 仅允许列表中的用户
• open — 允许所有人
• disabled — 禁用

群组消息默认要求 @mention 才会触发 Agent。

子 Agent¶

Agent 可以在执行过程中 spawn 子 Agent，将子任务委派给专门的 Agent 实例。子 Agent 拥有独立的会话和工具访问，完成后将结果返回给父 Agent。

子 Agent 的生命周期包括：spawn（创建）、steer（重定向）、kill（终止）。

技能 (Skills)¶

通过 SKILL.md 文件注入 Agent 能力。技能被加入系统提示，使 Agent 获得特定领域的知识和工具：

~/.pyclaw/workspace/skills/
├── my-skill/
│   └── SKILL.md
└── ...

技能可通过 ClawHub marketplace 搜索和安装：

pyclaw skills search "code review"
pyclaw skills install code-review

安全模型¶

pyclaw 在多个层面提供安全保障：

安全审计：pyclaw security audit [--deep] [--fix]

相关文档: 架构设计 · 配置说明 · API 参考