Zhumora 智能体

开源的桌面 AI 智能体（Windows / Ubuntu Linux）。

Zhumora 可以连接 OpenAI 兼容模型，并操作你的文件、终端、浏览器和桌面。程序本体以本地运行为主，同时支持 MCP、Skills、长期记忆和权限控制。

English · 技术文档 · bilibili视频

功能

• 支持 OpenAI 兼容 API，也可接入 Ollama、llama.cpp、vLLM 等本地端点
• 在指定工作目录内读取、编辑、搜索和管理文件
• 通过按格式划分的内置工具读写 Word、Excel、PowerPoint 和 PDF 文件
• 执行终端命令
• 使用 Playwright 自动化 Chromium
• 通过无障碍元素、截图、鼠标和键盘观察并控制 Windows 应用（Linux 上桌面控制仅保留截图观察）
• 通过 MCP 扩展工具
• 自身也是 MCP 服务器，可供 Claude Code、Codex 等外部编排器接入并委托任务
• 从 Markdown 文件加载 Skills
• 本地保存会话、长期记忆和 Token 用量
• 接入 Telegram Bot 或 QQ Bot，用手机和同一个本地 Agent 对话，实时显示进度
• 可导入 VRM 角色并按会话手动开启独立透明 Avatar 窗口，由 Agent 调用已配置的动作和表情
• 对高风险操作进行权限确认
• 支持深色 / 浅色主题与多语言界面

用 Telegram / QQ 随身对话

在 设置 → 聊天机器人 里接入 Telegram Bot 或 QQ Bot，就能用手机和同一个本地 Agent 对话，不必守在电脑前。

• 双平台接入 — Telegram 填 BotFather Token，QQ 填开放平台的 AppID / AppSecret，两端跑的是同一个 Agent、同一套工具和权限
• 看得见进度 — 思考过程实时流出（💭 …），每个工具调用都即时可见（🔧 bash: npm test），完成后变成 ✅ 1.2s，长时间任务不会让人以为卡死
• 随时随地审批 — 高风险操作会在聊天里请求确认：Telegram 发「允许 / 拒绝」内联按钮，QQ 回复 y / n
• 始终可控 — Bot 只响应白名单用户（先发 /id 拿到自己的 ID / OpenID），随时 /stop 中止当前任务

桌面控制

Zhumora 可以直接操作 Windows 桌面：

• 观察 — 列出运行中的应用、截取屏幕、读取任意窗口的 UI 无障碍树（含短期有效的语义元素引用）
• 操作 — 点击、双击、右键、输入、按键、滚动、拖拽、聚焦、切换控件，可基于无障碍元素引用或截图坐标定位
• 验证 — 改变应用状态的操作默认附带截图；单纯移动指针仅在明确请求时截图

这让 Zhumora 能够驱动没有 API 或命令行的原生 Windows 应用，而不仅仅是文件、终端和浏览器。

Linux 版本：无障碍树和输入注入依赖 Windows 专有的 Terminator 库，因此桌面控制仅保留截图观察（desktop_observe 的 screen 模式）；文件、终端、浏览器等其余能力不受影响。

作为 MCP 服务器：接住外部编排器的委托

Zhumora 本身也是一个 MCP 服务器。Claude Code、Codex 等外部编排器可以把它当作协作者，把成块的任务委托进来，由同一个本地 Agent 执行。

在 设置 → MCP 对外服务 打开开关即可，页面会显示运行状态、端点地址，并生成可直接粘贴的客户端配置（给 Claude Desktop、Cursor、Cline 等的是 JSON，给 Codex 的是 TOML）。

• 仅本机回环 + Bearer 令牌 — 服务器只监听 127.0.0.1，客户端用 Authorization: Bearer <令牌> 鉴权。令牌在首次启用时生成并落库固定，不会随应用重启自动轮换；换令牌或端口后重新复制一份配置即可。
• 一次委托就是一个会话 — 每个委托任务都是侧边栏里的一个 Zhumora 会话，和你在桌面手动发起的会话一样实时显示进度、写入历史，也可以随时中止。
• 跟进到终态 — 外部编排器用 zhumora_chat 投递任务，用 zhumora_wait 等待完成（有界长等待 + 进度通知），拿到的是自包含的最终答复，而不是被误当成完成的 running；断线重连后仍可取回结果。
• 权限仍在你手里 — 默认「仅桌面确认（推荐）」：外部编排器只能看到任务在等待权限，批准或拒绝由你在 Zhumora 桌面里完成。开启「允许客户端裁决普通级操作」后，它才能在你授予的权限范围内用 zhumora_respond 批准普通级工具；危险操作始终等你确认。
• 诊断而非轮询 — zhumora_status 只提供任务的瞬时状态快照，不用于定时轮询。

快速开始

环境要求

• Windows 10 / 11，或 Ubuntu Linux（x64）
• Node.js 22.12+（推荐 Node.js 24 LTS）
• npm

安装

npm install

开发

npm run dev

构建

npm run build

打包 Windows 安装包

npm run build:win

打包 Linux（AppImage / deb）

npm run build:linux

安装包输出到 release/。

模型配置

在 设置 中添加 OpenAI 兼容 Provider：

• Base URL
• API Key（如需要）
• 模型名称
• Temperature
• Reasoning Effort
• Context Window

本地和远程模型端点均可使用。

VRM Avatar

在 设置 → Avatar 导入 .vrm 角色，并可为角色填写内嵌动画名称或导入 .vrma 动画（一次可多选多个文件）。新会话默认关闭 Avatar；需要时在会话输入栏的 Avatar 上拉菜单选择角色。启用后，角色运行在可拖动的独立透明窗口中，Agent 只能调用该角色已报告或已配置的动作与表情。

Avatar 自带程序生成的待机、说话、点头、摇头、打招呼、挥手、耸肩、鞠躬、鼓掌、庆祝、伤心等动作（适配 VRM 0/1），并有呼吸、重心微移、手臂随动和手指微曲的常驻生命感动画。

项目不附带角色模型。@pixiv/three-vrm 代码采用 MIT 许可证，但每个 VRM 模型拥有独立许可；导入和分发模型前请自行确认模型作者的授权范围。

文档

会话/消息系统的权威架构与开发约束见 ARCHITECTURE.md 和 AGENTS.md；工具系统、上下文管理、长期记忆、MCP 和构建细节见 TECHNICAL.md。

许可证

Zhumora 采用 AGPL-v3.0

此前已经按 MIT 许可证发布的版本继续适用当时授予的条款。第三方组件仍采用各自 的许可证，详见 THIRD_PARTY_NOTICES.md。