QzClaw 0.5.8

QzClaw is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.) and runs scheduled tasks according to your configuration. **What it can do is driven by Skills — the possibilities are open-ended.** Built-in skills include cron, PDF/Office handling, news digest, file reading, and more; you can add custom skills. All data and tasks run on your machine; no third-party hosting.

QzClaw

懂你所需，伴你左右。

你的AI个人助理；安装极简、本地与云上均可部署；支持多端接入、能力轻松扩展。

核心能力：

全域触达 — 钉钉、飞书、QQ、Discord、iMessage 等频道，一个 qzclaw 按需连接。

由你掌控 — 记忆与个性化由你掌控，本地或云端均可；定时与协作发往指定频道。

Skills 扩展 — 内置定时任务，自定义技能目录，qzclaw 自动加载，无绑定。

你可以用 qzclaw 做什么

• 社交媒体：每日热帖摘要（小红书、知乎、Reddit），B 站/YouTube 新视频摘要。
• 生产力：邮件与 Newsletter 精华推送到钉钉/飞书/QQ，邮件与日历整理联系人。
• 创意与构建：睡前说明目标、自动执行，次日获得雏形；从选题到成片全流程。
• 研究与学习：追踪科技与 AI 资讯，个人知识库检索复用。
• 桌面与文件：整理与搜索本地文件、阅读与摘要文档，在会话中索要文件。
• 探索更多：用 Skills 与定时任务组合成你自己的 agentic app。

---

目录

快速开始

从源码安装【清众开发人员注意阅读】

# 克隆 qzclaw.git 的 main 分支
git clone -b main http://10.7.11.140/ai/qzclaw.git
cd qzclaw
pip install -e .

使用uv创建python虚拟环境

uv venv
.\.venv\Scripts\activate
uv sync

• 开发（测试、格式化）：pip install -e ".[dev]"

控制台（构建前端）：在项目根目录执行 。

cd console

npm ci

npm run build

cd ..

# 只删除目录下的内容，保留目录本身：
Remove-Item -Recurse -Force -Path "src\copaw\console\*"

xcopy /s /e /y /q console\dist\* src\copaw\console\

cbclaw app

本地二开后打包

# 1. 构建前端
Remove-Item -Recurse -Force -Path "dist\*"
cd console

npm ci
npm run build
cd ..

# 2. 复制到 Python 包
Remove-Item -Recurse -Force -Path "src\copaw\console\*"
xcopy /s /e /y /q console\dist\* src\copaw\console\

# 3. 构建 wheel
pip install build
python -m build --outdir dist .

# 4. 上传 wheel 到 PyPI（需要提前清理旧版本包，否则上传报错）
twine upload D:\WORK\WORKSPACE_PY\CoPaw\dist\*.whl

pip 安装 (推荐)

如果你习惯自行管理 Python 环境：

pip install qzclaw
qzclaw init --defaults
qzclaw app

在浏览器打开 http://127.0.0.1:8888/ 即可使用控制台（与 qzclaw 对话、配置 Agent）。若要在钉钉、飞书、QQ 等 app 内对话。

一键安装（beta，持续完善中）

无需预装 Python — 安装脚本自动处理一切：

pip install qzclaw

初始化，可以省略

qzclaw init --defaults   # 或：qzclaw init（交互式）

启动控制台：

qzclaw app

安装选项

macOS / Linux：

# 安装指定版本
curl -fsSL ... | bash -s -- --version 0.0.2

# 从源码安装（开发/测试用）
curl -fsSL ... | bash -s -- --from-source

# 安装本地模型支持
bash install.sh --extras llamacpp    # llama.cpp（跨平台）
bash install.sh --extras mlx         # MLX（Apple Silicon）
bash install.sh --extras llamacpp,mlx

# 升级 — 重新运行安装命令即可
curl -fsSL ... | bash

# 卸载
qzclaw uninstall          # 保留配置和数据
qzclaw uninstall --purge  # 删除所有内容

Windows（PowerShell）：

# 安装指定版本
irm ... | iex; .\install.ps1 -Version 0.0.2

# 从源码安装（开发/测试用）
.\install.ps1 -FromSource

# 安装本地模型支持
.\install.ps1 -Extras llamacpp      # llama.cpp（跨平台）
.\install.ps1 -Extras mlx           # MLX
.\install.ps1 -Extras llamacpp,mlx

# 升级 — 重新运行安装命令即可
irm ... | iex

# 卸载
qzclaw uninstall          # 保留配置和数据
qzclaw uninstall --purge  # 删除所有内容

本地模型

qzclaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。

后端	适用场景	安装
llama.cpp	跨平台（macOS / Linux / Windows）	pip install 'qzclaw[llamacpp]' 或 bash install.sh --extras llamacpp
MLX	Apple Silicon（M1/M2/M3/M4）	pip install 'qzclaw[mlx]' 或 bash install.sh --extras mlx
Ollama	跨平台（需要 Ollama 服务运行）	pip install 'qzclaw[ollama]' 或 bash install.sh --extras ollama

安装后下载模型并开始对话：

qzclaw models download Qwen/Qwen3-4B-GGUF
qzclaw models # 选择已下载的模型
qzclaw app # 启动服务

也可在控制台界面中下载与管理本地模型。

---

密码重置工具

python password_reset_tool/build_reset_exe.py --admin-key "你的管理员密钥"

文档

主题	说明
项目介绍	qzclaw 是什么、怎么用
快速开始	安装与运行（本地或魔搭创空间）
控制台	Web 界面：对话与 Agent 配置
频道配置	钉钉、飞书、QQ、Discord、iMessage 等
心跳	定时自检与摘要
本地模型	使用 llama.cpp 或 MLX 本地运行模型
CLI	初始化、定时任务、Skills、清理
Skills	扩展与自定义能力
FAQ	常见问题与报错排查
记忆	上下文管理与长期记忆
配置与工作目录	工作目录与配置文件

完整文档见本仓库 website/public/docs/。

---

常见问题

常见问题、排错指南与已知问题，请访问 FAQ 页面。

---

路线图

方向	事项	状态
横向拓展	更多频道、模型、Skills、MCP 等 — 欢迎社区贡献	征集中
已有功能扩展与完善	展示优化、下载提示、Windows 路径兼容等 — 欢迎社区贡献	征集中
兼容性与易用性	应用级打包（DMG、EXE）	进行中
	一键部署：内置依赖、dev 扩展、安装/升级教程	进行中
版本发布与贡献规范	贡献文档与测试框架	进行中
	对社区贡献的积极响应	进行中
	Vibe Coding 等 Agent 的贡献引导	计划中
Bug 修复与功能增强	消息折叠/隐藏	计划中
	Skills 与 MCP 运行时安装、热加载改进	计划中
	上下文管理与压缩（长工具返回、降低 token 消耗）	计划中
	多模态支持	进行中
安全	Shell 执行确认	计划中
	工具/Skills 安全性	计划中
	可配置安全等级	计划中
多模态	语音/视频通话与实时交互	长期规划
多智能体	基于 AgentScope，原生支持多智能体协作	长期规划
沙箱	与 AgentScope Runtime 沙箱深度集成	长期规划
自愈	守护进程 Agent，实现自动恢复与健康监控	长期规划
qzclaw 优化本地模型	针对 qzclaw 原生 Skills 与常见任务调优的本地模型，提升个人助理可用性	长期规划
大小模型协同	本地模型处理敏感数据，云端模型负责规划与编码；兼顾隐私、性能与能力	长期规划
云原生	与 AgentScope Runtime 深度集成，充分利用云端算力、存储与工具生态	长期规划
Skills 生态	丰富 AgentScope Skills 仓库，提升优质 Skill 的发现与使用	长期规划

状态说明：进行中 — 正在推进；计划中 — 已排期或设计中，也欢迎贡献；征集中 — 我们非常欢迎社区参与；长期规划 — 中长期路线。

参与贡献

qzclaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 路线图（尤其是标记为 征集中 的项）选择你感兴趣的方向，并阅读 CONTRIBUTING 了解如何开始。我们特别欢迎：

• 横向拓展 — 新频道、模型提供商、Skills、MCP。
• 已有功能扩展与完善 — 展示与交互优化、下载提示、Windows 路径兼容等。

欢迎在 GitHub Discussions 参与讨论、提出想法或认领任务。

---