一个小而完整、私有自托管、默认受控的个人 Agent。
MiniClaw 把模型、Tool、权限、审批、持久化和多个消息渠道收进同一个本地 Core。你可以从 TUI、飞书、Telegram 或 Discord 与同一个 Agent 交互；所有本机动作仍要经过统一的 Policy、Workspace 边界和可审计执行链。
Important
当前代码已完成 Phase 5 的本地实现门禁；Feishu/Telegram/Discord 的完整真实 Live Gate 仍按各自证据单独标记。
v0.5.3 Core 已加入 SDK 日志脱敏、Gateway lease/provenance、受管 Live Runner 与异常 Tool 历史恢复；
Feishu/Discord 严格 15/15 仍为 Live Pending。
飞书 Card callback 现在绑定唯一 sent receipt、账号与 Approval ID；真实“仅本次”已完成 Tool、child Turn
与结果 Delivery，状态为 TARGETED CALLBACK LIVE VERIFIED / 15-CASE LIVE PENDING。
飞书消息到达后立即创建一张蓝色 Claw Trail Agent Card，执行中持续原地更新，成功后同一卡片变为绿色并展示脱敏步骤、Tool、安全目标、状态、耗时、过程摘要和最终回答；最终回答统一渲染为 bullet points，Markdown 表格会转换为条目。
缺少 tools.mode 的配置默认使用 autopilot，但只对本地入口和经过验证的 Owner 私聊生效；硬安全边界不变。
Memory Autopilot A～E 已完成本地实现：四入口共享一个 Owner Memory Space，Markdown 保存语义真相，SQLite
保存 durable buffer、来源、治理和可重建 FTS5 Projection；真实 IM 平台能力仍只按各自 Live evidence 标记。
| 目标 | MiniClaw 的选择 |
|---|---|
| 私有与可控 | 状态、会话、审批和审计保存在本机；Secret 不进入 Prompt、日志或 Memory。 |
| 小而完整 | 一个 Python Core、一个主 TUI、一个 OpenAI-compatible Provider，不提前堆叠服务。 |
| 真正能行动 | 18 个内置 Tool 覆盖系统信息、文件、搜索、HTTPS、exact-argv CLI 和 Memory。 |
| 默认可追溯 | Turn、ToolRun、Approval、Delivery 与 Channel Inbox/Outbox 都有 SQLite 状态。 |
| 多入口同一 Core | TUI、Feishu、Telegram、Discord 复用同一个 AgentRuntime；Transport 和故障域隔离。 |
| 先验证再扩张 | unittest、TypeScript test、Agent/Channel JSONL、20 轮 soak 和文档校验共同守门。 |
MiniClaw 不是“把聊天框接到 Shell”——模型只提出 Tool Call，Core 负责参数校验、风险判定、审批绑定、执行、审计和恢复。
| 层 | 已实现能力 |
|---|---|
| Agent Loop | OpenAI-compatible 流式响应、Tool Loop、token/latency telemetry、错误归一化、Context compaction。 |
| TUI | 默认 pi-tui、中文/英文、流式对话、Tool 状态、紧凑审批卡、四档 Permission Mode、Textual fallback。 |
| Tool | 系统、文件、搜索、HTTPS、exact-argv CLI，以及 remember/search/get/list/flush/forget/correct/review Memory surface。 |
| 安全 | Workspace Guard、敏感路径硬拒绝、exact argv、最小子进程环境、HTTPS/DNS/SSRF 校验、参数绑定 Approval。 |
| Channel | Feishu 用单张 Claw Trail Agent Card 展示脱敏步骤和最终回答；审批点击在原卡先显示处理中，再以成功、拒绝或失败终态收口；三平台各自独立 Transport/Delivery/Manager/queue/recovery，共享 Agent Runtime。 |
| 数据 | SQLite Session/Message/Turn/ToolRun/Approval/Channel/Memory control plane；owner-only Markdown Truth 与 Skills。 |
| 运维 | init、23 项 doctor、gateway、Memory rebuild、结构化脱敏日志、幂等恢复与版本化 Eval。 |
init 会幂等安装 feishu-lark-cli 与 github-cli Skill：飞书业务请求走官方 lark-cli，GitHub 远端请求走本机 gh，本地仓库请求走 git；凭据不进入 Tool 参数或模型上下文。
SAFE：只读低风险动作自动执行，其余动作按 Policy 请求审批或拒绝。SMART：精确规则和安全 HTTPS 可以少打扰，未命中仍受监督。AUTOPILOT：已验证 Owner 的非关键动作可自动执行，硬边界、参数校验与审计仍然存在。YOLO：最少监督模式；不会关闭敏感路径、SSRF、Workspace 和关键动作硬边界。
新安装和缺少 tools.mode 的旧配置默认使用 autopilot；显式 safe/smart 保持不变。该默认值只信任本地入口和经过验证的 Owner 私聊，群聊、其他用户与硬拒绝规则不会扩权。
如果当前个人实例明确要求最少监督，可在私有 ~/.miniclaw/config.toml 中设置 mode = "yolo" 并重启 Gateway；这只减少硬校验通过后的审批，不会开放凭据、敏感路径、SSRF、提权或 Shell 字符串执行。
- Python 3.12+
- uv
- Node.js 22.19+ 与 pnpm（默认 pi-tui）
- 一个 OpenAI-compatible 模型端点；默认配置为
deepseek-v4-pro
git clone https://github.com/NEDONION/miniclaw.git
cd miniclaw
uv sync --extra dev --extra channels
pnpm --dir tui install
pnpm --dir tui build
cp .env.example .env
# 只在本机填写 MINICLAW_MODEL_API_KEY；不要提交 .env
uv run miniclaw init
uv run miniclaw doctor
uv run miniclaw默认状态目录是 ~/.miniclaw，Workspace 是 ~/.miniclaw/workspace。使用隔离实例：
uv run miniclaw --home /absolute/path/to/demo-home init
uv run miniclaw --home /absolute/path/to/demo-home如果暂时没有满足版本要求的 Node.js，可以显式使用迁移期 fallback：
MINICLAW_TUI=textual uv run miniclaw| 命令 | 用途 |
|---|---|
uv run miniclaw |
启动唯一主 TUI。 |
uv run miniclaw init |
幂等初始化 owner-only 状态、配置、Memory、Skills 和 SQLite。 |
uv run miniclaw doctor |
检查配置、目录权限、Provider、TUI 和数据库状态。 |
uv run miniclaw gateway |
启动已配置的 Feishu/Telegram/Discord Gateway。 |
uv run miniclaw eval validate --root evals/scenarios |
校验版本化 JSONL 场景。 |
uv run miniclaw eval run --suite offline --root evals/scenarios |
跑真实 Core/Policy/Tool/SQLite 离线回归。 |
uv run miniclaw eval run --suite channel --repeat 20 --json --root evals/scenarios |
跑三平台 Channel gate 与 20 轮本地 soak。 |
Channel 的 allowlist、Owner 身份与平台凭据配置见本地运行指南。
下面 3 个典型 Case 均在 Warp 中使用全新隔离 MINICLAW_HOME 运行。为了不消耗真实模型额度，Provider 响应来自本地固定端点；MiniClaw 的 TUI、Bridge、TurnService、Policy、ToolExecutor、SQLite、Approval 和 Tool 执行均走真实代码路径。
中文输入、回答、32K 应用侧 Context budget、token、迭代和耗时在同一界面可见。
run_command 在执行前展示规范化后的绝对程序、精确 argv、超时和四种审批选择；截图时命令仍处于 requested，没有执行。
MiniClaw 用 run_command 的 exact argv 调用隔离仓库中的 git status --short --branch，再根据真实 Tool 结果完成总结；没有 Shell 字符串拼接。
flowchart LR
U["Owner"] --> TUI["pi-tui / Textual"]
U --> IM["Feishu / Telegram / Discord"]
TUI --> CORE["TurnService + AgentRunner"]
IM --> PIPE["isolated Channel pipelines"]
PIPE --> CORE
CORE --> PROVIDER["OpenAI-compatible Provider"]
CORE --> EXEC["ToolExecutor"]
EXEC --> POLICY["Policy + Permission Mode"]
POLICY --> APPROVAL["bound Approval"]
POLICY --> TOOLS["Files / HTTPS / CLI / Memory"]
CORE --> DB["SQLite ledgers"]
CORE --> MD["Markdown Memory + Skills"]
一次典型本机动作的链路是：
- TUI 或 Channel 把用户消息交给同一个
TurnService； ContextBuilder组合 SOUL、USER、当前 Memory、Skills 和有界历史；- Provider 返回文本或 Tool Call；
- Tool 先做 Schema 校验，再由 Policy 决定 allow / deny / approval；
- 执行结果写入 ToolRun/Audit，返回 Agent 继续完成回答；
- Turn、消息、审批与 Channel Delivery 都能在重启后恢复或解释。
| 能力 | 当前实现 |
|---|---|
| 真相源 | 已接受 Unit 写入 memory/owners/<owner>/memory.md；SQLite Projection 可重建 |
| 写入 | 普通 Turn 非阻塞 capture/flush；明确“记住”原子落盘后才报告成功 |
| 检索 | owner-scoped FTS5/CJK、完整来源链、有效期过滤与固定 Recall 预算 |
| 治理 | short-term、重复晋升、Review、冲突、纠错、forget、TTL 与 weekly review |
| 跨渠道 | TUI、Feishu、Telegram、Discord 的已验证 Owner 私聊共享一个 Memory Space |
| 隐私 | 群聊、非 Owner、未知/冲突身份 fail closed；Secret 在 Candidate 前拒绝 |
| 维护 | Markdown direct edit 对账、/memory rebuild、legacy 只读 hash 迁移、Doctor drift 检查 |
架构、实现和证据入口：
- Memory Autopilot 能力 Gap 与重构架构
- 正式设计 Spec
- 最佳实践与技术选型
- Memory A～E TDD 实施计划
- Memory Autopilot 工程实现
- v0.6.0 发布证据
- Secret 永不进入仓库、普通日志或 Memory；常见 Token、密码、OTP、Authorization 和私钥在边界拒绝。
- 文件 Tool 只能访问配置的 Workspace/允许根；symlink、路径逃逸、二进制和超限内容 fail closed。
run_command只接受程序与参数数组，shell=False，使用最小环境、固定 cwd、超时和输出上限。http_get只允许经过 URL、DNS、端口和重绑定检查的 HTTPS 目标。- Approval 绑定 Tool 名、规范化参数 hash、Owner、TTL 和可用决策；篡改、重放和跨 Owner 使用都会拒绝。
- Channel allowlist、Owner 映射、Inbox/Outbox 幂等、独立 queue 和恢复状态不会交给模型决定。
- Memory、Skill 和外部内容只能提供上下文，不能扩大 Policy 权限。
完整威胁模型与契约见系统架构和Phase 2 安全设计。
| 项目 | 当前证据 |
|---|---|
| Python | 671/671 unittest PASS |
| TUI | 35/35 TypeScript tests + build PASS |
| Agent | 39/39 active offline cases PASS（含 MEM-AUTO-001..010） |
| Channel | 32/32 versioned cases PASS |
| 稳定性 | 20 轮 local Channel soak，640/640 PASS |
| Feishu | TARGETED CALLBACK LIVE VERIFIED / 15-CASE LIVE PENDING |
| Telegram / Discord | Implementation PASS；真实平台 Live Gate 仍 pending |
| Memory Autopilot | A～E IMPLEMENTATION PASS；真实 IM Live 结论沿用各平台 gate |
本地 fake SDK、离线场景和 640/640 soak 只代表 IMPLEMENTATION PASS，不会冒充真实平台 Live PASS。历史发布证据见 docs/evals/releases/。
Memory 上线前的 Phase 5 历史基线为 562 Python、30 TypeScript、29/29 Agent；Memory v0.6.0 的历史基线为
666 Python、35 TypeScript、39/39 Agent；当前发布数字以上表和 v0.6.1 为准。
uv run python -m unittest discover -s tests -v
pnpm --dir tui test
pnpm --dir tui build
uv run ruff check .
uv run miniclaw eval run --suite channel --repeat 20 --json --root evals/scenarios
uv run python scripts/validate_docs.py
git diff --checkflowchart LR
P53["v0.5.3\nLive Evidence 收口"] --> MA["Memory A-E\nIMPLEMENTED"]
MA --> P6["Phase 6\nAutomation + Sandbox"]
P6 --> P65["Phase 6.5\nBrowser Agent"]
P65 --> P7["Phase 7\nControlled Evolution"]
P7 --> P8["Phase 8\nSkills + MCP + Provider"]
P8 --> P9["Phase 9\nSub-agent + Multimodal"]
Owner AUTOPILOT 默认值、飞书 Claw Trail Agent Card、v0.5.3 Core hardening 与 Memory A～E 已实现。
下一步继续收口 Feishu/Discord 严格 Live Evidence，再进入 Phase 6 自治任务。路线图中后续节点不代表
相应代码已经存在。
src/miniclaw/
├── agent/ # Context、Runner、Turn、Compaction
├── channels/ # Feishu / Telegram / Discord adapters and pipelines
├── memory/ # Markdown Truth、buffer/flush、FTS5、治理、对账与迁移
├── policy/ # Workspace、Command、Network、Permission、Approval
├── providers/ # OpenAI-compatible Provider
├── storage/ # SQLite schema, repositories and migrations
├── tools/ # 18 个内置 Tool
└── tui/ # Textual fallback；默认 pi-tui 在仓库 tui/
tui/ # Node.js pi-tui + Python Bridge client
evals/ # versioned Agent / Channel scenarios
docs/ # PRD、架构、工程、计划、发布证据与进度页
tests/ # Python unittest
| 入口 | 适合读者 |
|---|---|
| 文档中心 | 完整索引与推荐阅读顺序 |
| 产品需求文档 | 产品范围、非目标和验收标准 |
| 系统架构 | 模块边界、数据流与安全原则 |
| 本地运行指南 | 安装、配置、TUI、Gateway 与排障 |
| 工程文档索引 | 已实现模块与规划文档的边界 |
| 开发与交付时间线 | 架构 Phase、真实版本顺序与证据状态的对应关系 |
| 开发进度页 | 当前 Phase、证据和下一步 |
| OpenClaw / Hermes Gap | 竞品能力映射与 v0.5.3 Evidence→Memory A～E→Phase 6～9 路线 |
| 能力对齐工程落地总方案 | 后续交付的模块、数据和测试边界 |
| Memory A～E 实施计划 | 可直接执行的 RED→GREEN 施工计划 |
| Memory Autopilot 工程实现 | 当前数据流、安全边界、恢复和运维入口 |
欢迎 Issue 和 Pull Request。开始前请阅读 AGENTS.md 与文档中心，保持变更范围小、测试离线可重复，并且不要把规划写成已实现。
uv sync --extra dev
uv run python -m unittest discover -s tests -v
uv run ruff check .