Zclaw 是一个用 Python 编写的 AI 编程助手，将大语言模型（LLM）与本地文件系统、Shell 环境深度结合，让 AI 能够像人类程序员一样读取代码、修改文件、执行命令、搜索项目，从而完成复杂的编程任务。

GitHub：https://github.com/zhanghuiwan/Zclaw/tree/master

Zclaw 是什么

Zclaw 巧妙地结合了 Claude Code 的工具调用理念与 OpenClaw 的自主 Agent 能力，通过统一的 OpenAI 兼容接口，支持阿里百炼、Ollama、Azure 等任意兼容服务。其核心是一个工具调用循环（Agent Loop）机制，LLM 可以自主决定调用哪些工具、调用多少轮，真正实现复杂的编程任务自动化。

核心定位

Zclaw 不仅仅是一个聊天机器人，而是一个智能体编程环境，具备以下核心能力：

读取整个代码仓库
跨多个文件编辑、创建文件
执行 shell 命令、运行测试
集成 git / GitHub 等开发工具
通过 MCP 协议接入外部系统
支持 Skills 扩展，类似 Claude Code 的工作流复用

典型使用场景

# 交互模式
python main.py

# 非交互模式（单次提问）
python main.py -p "帮我审查当前目录的代码"

# 启动 Web UI
python -m src.web.server

核心特性详解

多模型支持

Zclaw 提供统一的 OpenAI 兼容接口，可以连接各种 LLM 服务：

ZCLAW_PROVIDER=bailian
ZCLAW_MODEL=qwen-plus
ZCLAW_API_KEY=sk-xxxxxxx
ZCLAW_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

支持的 Provider：

阿里百炼（Dashscope）：通义千问系列
Ollama：本地部署的 Llama、Mistral 等模型
OpenAI：GPT-4、GPT-3.5 等
Azure OpenAI：企业级部署
以及其他任意 OpenAI 兼容 API

工具调用循环（Agent Loop）

这是 Zclaw 最核心的机制——让 LLM 自主决定调用工具的种类和轮次：

1	用户输入 → LLM 思考 → 判断是否需要工具 → 调用工具 → 获取结果 → 再次思考 → ...

每轮循环中，LLM 可以：

调用文件操作工具读写代码
执行 shell 命令
搜索项目文件
操作 Git
访问记忆系统
连接 MCP 外部工具

直到认为任务完成，自主结束循环。

分层安全体系

Zclaw 实现了三级危险等级的安全机制：

危险等级	行为	代表工具
`safe`	自动批准	`file_read`, `grep`, `glob`
`confirm`	需用户确认	`shell`, `file_write`, `git_commit`
`dangerous`	始终确认	高危系统命令（如 `rm -rf /`）

权限判定流程：auto_approve列表 → blocked_patterns → 路径限制 → 危险等级

路径限制

文件工具（file_read/write/edit）受路径限制约束：

黑名单：/etc、/usr、/bin、/sbin、/proc、/sys 等系统目录
白名单：默认为当前目录（.）

危险命令拦截

Shell 工具会拦截以下危险模式：

rm\s+-rf\s+/ — 递归删除根目录
sudo\s+ — 权限提升
mkfs — 格式化文件系统
dd\s+if= — 裸磁盘写入
命令注入模式

审计日志

所有操作以 JSONL 格式记录在 ~/.Zclaw/audit/，自动对敏感信息脱敏。

持久记忆系统

Zclaw 实现了分层记忆架构（L0-L4），让 Agent 拥有记忆能力：

层级	类型	实现	说明
L0	感知记忆	RingBuffer	最近 N 轮对话的原始记忆
L1	工作记忆	会话快照	当前会话的压缩摘要
L2	情景记忆	SQLite-VSS	跨会话的历史搜索（向量相似度）
L3	语义记忆	JSON	用户的长期偏好和项目状态
L4	程序记忆	YAML	Skills、规则、工具定义

Skills 扩展

Zclaw 支持类似 Claude Code / OpenClaw 的 Skills 功能，允许扩展 AI 的专业能力：

1 2	~/.zclaw/skills/ # 全局 Skills（所有项目共享） project_root/skills/ # 项目 Skills（仅当前项目可用）

Skills 本质上是一个包含 SKILL.md 定义文件的目录，Claude 可以根据触发词自动匹配并加载相关 Skill，将内容注入到 LLM 上下文中。

MCP 协议集成

Zclaw 支持连接外部 MCP（Model Context Protocol）工具服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/dir"]
    },
    "web-search": {
      "url": "http://localhost:3001/sse",
      "transport": "sse"
    }
  }
}

MCP 工具服务器提供的工具会自动注册到 Zclaw 的工具注册表中，LLM 可以像调用内置工具一样调用它们。

内置工具清单

Zclaw 内置 28 个工具，分为 6 大类：

文件工具（8 个）

工具	危险等级	功能
`file_read`	safe	读取文件内容，支持 offset/limit 分段
`file_write`	confirm	创建新文件或完全覆盖
`file_edit`	confirm	精确替换文件中的旧文本
`multi_edit`	confirm	对同一文件原子执行多处替换
`line_edit`	confirm	按行号替换/插入/删除
`line_read`	safe	按行号范围读取，显示行号
`diff`	safe	比较文本/文件差异（unified/并排）
`snapshot`	confirm	文件快照管理（保存/恢复/删除）

搜索工具（4 个）

工具	危险等级	功能
`directory`	safe	列出目录内容
`file_search`	safe	按文件名或内容搜索
`grep`	safe	正则表达式搜索（include/exclude/上下文）
`glob`	safe	Glob 模式匹配查找文件

系统工具（1 个）

工具	危险等级	功能
`shell`	confirm/dangerous	执行 Shell 命令，动态危险检测

Git 工具（7 个）

工具	危险等级	功能
`git_diff`	safe	查看差异（未暂存/已暂存/提交间/文件）
`git_commit`	confirm	暂存并提交（支持 amend）
`git_log`	safe	查看提交历史（支持过滤）
`git_status`	safe	查看仓库状态
`git_branch`	confirm	查看/创建/切换分支
`git_show`	safe	查看提交详情
`git_blame`	safe	查看行级修改信息

分析工具（4 个）

工具	危险等级	功能
`code_structure`	safe	AST 代码结构分析（类/函数/导入）
`symbol_find`	safe	按名称查找符号定义
`symbol_edit`	confirm	按符号名称精确替换函数/类
`import_analyze`	safe	导入依赖分析 + 未使用检测

记忆工具（4 个）

工具	危险等级	功能
`search_conversation_history`	safe	搜索历史对话记录（跨会话）
`get_session_history`	safe	获取特定会话的完整历史
`update_memory`	safe	更新用户/项目的持久化记忆
`set_preference`	safe	设置单个用户偏好

项目架构

Zclaw/
├── main.py                          # 简易对话入口
├── src/
│   ├── config/                      # 配置管理
│   ├── llm/                         # LLM 抽象层（多 Provider 支持）
│   ├── core/                        # 核心引擎（Agent、Loop、State、Planner）
│   ├── tools/                       # 工具系统（28 个内置工具）
│   │   └── builtin/                 # 内置工具实现
│   ├── sandbox/                     # 命令运行器（超时控制）
│   ├── security/                    # 安全系统（权限、校验、审计）
│   ├── memory/                      # 记忆模块（L0-L4 分层）
│   ├── context/                     # 上下文管理（Token 预算、压缩）
│   ├── prompt/                      # 提示词工程
│   ├── mcp/                         # MCP 协议实现
│   ├── plugins/                     # 插件系统（热重载）
│   ├── skills/                      # Skills 模块
│   ├── web/                         # Web UI（FastAPI + WebSocket）
│   └── cli/                         # CLI 界面（REPL、Rich 渲染）
└── tests/                           # 验证测试

核心模块说明

模块	说明
`llm/`	统一的 LLM 抽象层，支持 OpenAI 兼容接口的任意 Provider
`core/`	Agent 循环、状态机、任务规划器
`tools/`	28 个内置工具 + 插件扩展
`security/`	三级危险等级、路径限制、命令拦截、审计日志
`memory/`	L0 感知记忆到 L4 程序记忆的分层实现
`mcp/`	Model Context Protocol 客户端和服务器端支持

CLI 命令

命令	功能
`/help`	显示帮助信息
`/clear`	清空对话历史
`/undo`	撤销上一轮对话
`/compact`	手动压缩上下文
`/usage`	显示 token 使用统计
`/tools`	列出已注册工具
`/provider [name]`	查看/切换 LLM Provider
`/model [name]`	查看/切换模型
`/info`	显示完整配置信息
`/memory`	查看/搜索/删除记忆
`/session save\|load\|delete\|list`	会话管理
`/plugin [reload\|list]`	插件管理
`/cost`	Token 用量和费用统计
`/plan [clear]`	查看/清除当前计划
`/mcp list\|connect\|disconnect`	MCP 服务器管理
`/quit` `/exit`	退出

Web UI

Zclaw 提供完整的 Web 界面，通过 FastAPI + WebSocket 实现实时流式对话：

1 2	python -m src.web.server # 访问 http://localhost:8080

Web UI 功能：

实时流式对话输出
工具执行可视化
权限确认对话框
文件浏览器
工具列表面板
会话管理
费用统计
暗色主题

开发进度

当前所有核心模块均已完成：

模块	状态
配置管理（Settings + 环境变量 + YAML）	✅ 已完成
LLM 层（多模型支持、Router 路由）	✅ 已完成
核心引擎（Agent、Loop、State、Planner）	✅ 已完成
工具系统（28 个内置工具）	✅ 已完成
沙箱执行（超时控制）	✅ 已完成
安全系统（权限、校验、审计）	✅ 已完成
记忆模块（L0-L4 分层）	✅ 已完成
上下文管理（Token 预算、压缩）	✅ 已完成
提示词工程	✅ 已完成
插件系统（热重载）	✅ 已完成
Skills 模块	✅ 已完成
MCP 协议	✅ 已完成
Web UI	✅ 已完成
CLI 界面	✅ 已完成

后续发展方向

方向	说明
24 小时持续运行	Cron 调度器、Heartbeat 心跳机制、事件驱动触发
本地软件操控	Browser 自动化（Playwright）、进程管理、屏幕截取
多 Agent 架构	多会话管理、Agent 间通信、子代理模式
多通道接入	WhatsApp/Telegram/Slack/Discord 等消息通道

总结

Zclaw 是一个将 AI 编程助手能力提升到新高度的项目，它：

通过统一 LLM 接口降低了模型切换成本
通过** Agent Loop 机制**实现了真正的自主任务执行
通过分层安全体系保障了操作安全
通过持久记忆系统让 AI 拥有了跨会话的”记忆”
通过 Skills 和 MCP 协议实现了高度可扩展性

如果你正在寻找一个类似 Claude Code 的本地 AI 编程助手，Zclaw 是一个值得尝试的选择——不仅功能完整，而且完全开源，可本地部署，数据完全自主可控。

张会挽's Blog

Zclaw：结合 Claude Code 与 OpenClaw 的 AI 编程助手