<div align="center">

# qzclaw


<p align="center"><b>懂你所需，伴你左右。</b></p>

</div>

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

> **核心能力：**
>
> **全域触达** — 钉钉、飞书、QQ、Discord、iMessage 等频道，一个 qzclaw 按需连接。
>
> **由你掌控** — 记忆与个性化由你掌控，本地或云端均可；定时与协作发往指定频道。
>
> **Skills 扩展** — 内置定时任务，自定义技能目录，qzclaw 自动加载，无绑定。
>
> <details>
> <summary><b>你可以用 qzclaw 做什么</b></summary>
>
> <br>
>
> - **社交媒体**：每日热帖摘要（小红书、知乎、Reddit），B 站/YouTube 新视频摘要。
> - **生产力**：邮件与 Newsletter 精华推送到钉钉/飞书/QQ，邮件与日历整理联系人。
> - **创意与构建**：睡前说明目标、自动执行，次日获得雏形；从选题到成片全流程。
> - **研究与学习**：追踪科技与 AI 资讯，个人知识库检索复用。
> - **桌面与文件**：整理与搜索本地文件、阅读与摘要文档，在会话中索要文件。
> - **探索更多**：用 Skills 与定时任务组合成你自己的 agentic app。
>
> </details>

---



## 目录

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

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

```

#### 使用uv创建python虚拟环境
```bash
uv venv
.\.venv\Scripts\activate
uv sync
```

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

**控制台**（构建前端）：在项目根目录执行 。
```bash
cd console
```
```bash
npm ci
```
```bash
npm run build

```
```bash
cd ..
```
```bash
# 只删除目录下的内容，保留目录本身：
Remove-Item -Recurse -Force -Path "src\copaw\console\*"
```
```bash
xcopy /s /e /y /q console\dist\* src\copaw\console\
```
```bash
qzclaw app
```
### 本地二开后打包
```
# 1. 构建前端
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 环境：

```bash
pip install qzclaw
qzclaw init --defaults
qzclaw app
```

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


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

无需预装 Python — 安装脚本自动处理一切：
```bash
pip install qzclaw
```
初始化，可以省略

```bash
qzclaw init --defaults   # 或：qzclaw init（交互式）
```
启动控制台：
```bash
qzclaw app
```

<details>
<summary><b>安装选项</b></summary>

**macOS / Linux：**

```bash
# 安装指定版本
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）：**

```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  # 删除所有内容
```

</details>


## 本地模型

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`   |

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

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

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

---

## 文档

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

完整文档见本仓库 [website/public/docs/](website/public/docs/)。

---

## 常见问题

常见问题、排错指南与已知问题，请访问 **[FAQ 页面](https://qzclaw.agentscope.io/docs/faq)**。

---

## 路线图

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

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

### 参与贡献

qzclaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 [路线图](#路线图)（尤其是标记为 **征集中** 的项）选择你感兴趣的方向，并阅读 [CONTRIBUTING](https://github.com/agentscope-ai/qzclaw/blob/main/CONTRIBUTING_zh.md) 了解如何开始。我们特别欢迎：

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

欢迎在 [GitHub Discussions](https://github.com/agentscope-ai/qzclaw/discussions) 参与讨论、提出想法或认领任务。

---

