中文上手指南

安装与使用 MausBot

从下载桌面版开始，连好一个 AI 引擎，再让你的第一个 Bot 完成一件小事。

开始前准备

一台受支持的电脑、网络连接，以及一个支持的 AI 服务账号或具有模型权限的 API Key。安装包和开始菜单里的应用名称可能显示为 OpenMausBot。

01 / 下载与安装

按电脑系统选择安装包

WindowsmacOSUbuntu

Windows 64 位 · x64

  1. 打开「设置 → 系统 → 关于」，确认系统类型是基于 x64 的处理器。
  2. 下载 OpenMausBot-setup.exe，双击运行，跟随安装向导。官方安装器通常无需管理员权限。
  3. 完成后，从开始菜单搜索 OpenMausBot 并打开。

如果 SmartScreen 提示发布者未知，先核对文件是否来自官方 Releases，并检查发布者信息。

下载 Windows 安装包 ↓

macOS Apple 芯片或 Intel

  1. 点「 → 关于本机」。显示 Apple M 系列芯片，选 Apple 芯片版。显示 Intel 处理器，选 Intel 版。
  2. 打开下载的 .dmg，把 OpenMausBot 拖进「应用程序」。
  3. 从「应用程序」启动。系统提示打开下载的应用时，核对来源和应用名称后再继续。
Apple 芯片 ↓Intel ↓

Ubuntu 24.04 · x64 · 测试版

  1. 下载 OpenMausBot-amd64.deb。在文件管理器打开下载目录，在该目录中打开终端。
  2. 运行下方命令，按提示输入系统密码，安装完成后在应用列表中打开 OpenMausBot。
sudo apt install ./OpenMausBot-amd64.deb

使用 AppImage 时，在文件属性中允许执行，再打开文件。启动失败时，查看发行版的 AppImage 运行要求。

下载 .deb ↓AppImage ↓

链接指向最新发布。文件名变更或下载失败时，打开 GitHub Releases，在 Assets 里找对应的安装包。

02 / 首次配置

安装并登录一个 AI 引擎

打开 MausBot，跟随首次启动向导进入引擎检查。已跳过向导时，从侧栏齿轮进入 App settings → Agent engines。部分版本显示为 Settings → Engines。

  1. 选择 Codex 或 Claude Code。选你已有账号且可以使用模型的一项。Codex 对应 OpenAI，Claude Code 对应 Anthropic。
  2. 按状态安装和登录。引擎显示缺失时，使用该行给出的安装入口或命令。提示未登录时，按该引擎的登录提示完成授权。若所选方式需要 API Key，在应用的 API keys 或对应引擎配置中保存。
  3. 回到引擎检查并重新检测。确认引擎可用，再到新建 Bot 的模型列表选择一个可用模型。刚安装 CLI 而检测不到时，完全退出并重开 MausBot。

如果你在终端里能使用引擎，但应用仍找不到它，可在 Settings → Engines 检查或指定 CLI 路径。Windows 用 where.exe codex 或 where.exe claude，macOS / Linux 用 command -v codex 或 command -v claude 查找。

界面依据 官方快速开始 和 仓库说明 整理。首次聊天只需一个可用引擎。

03 / 第一次对话

创建第一个 Bot

  1. 点击 New or share → New bot。
  2. 名称填「日程助手」，选刚连接的引擎和可用模型。普通聊天可留空工作目录。处理文件时，再选择该任务专用的目录。
  3. 创建后在侧栏打开「日程助手」，粘贴下方示例并发送。收到包含三项任务和时间安排的回复，就完成了首次使用。

我明天上午有两小时，需要回邮件、写项目进展、准备会议。请给出一份表格，包含每项任务的开始时间、耗时和产出，总耗时不超过两小时。只回复计划。

04 / 日常使用

让 Bot 处理实际任务

读文件与写草稿

给 Bot 选定工作目录，把材料放进去，告诉它具体文件名、输出格式和限制。比如「只读 meeting.md，列出行动项、负责人和截止日期」。

检查权限请求

涉及命令、文件修改或外部操作时，关注聊天里的审批卡。确认命令、路径和预期影响后点 Allow，否则点 Deny。

定时执行

让 Bot「每周一上午 9 点提醒我写周报」。在 Triggers（部分版本为 Automations）检查时区、执行时间和运行历史，也可以暂停或试运行。本机任务需要宿主保持运行。

连接应用

在 Apps / Connected apps 选择 Gmail、GitHub 等应用，按提示授权。先试一个只读任务，再使用需要写入或发送的操作。

在手机上查看或继续聊天

从官方 下载页 进入 Discord 获取 Android 或 iOS 伴侣应用。打开手机端，按提示与运行中的电脑或服务器配对。使用时让主机保持在线、唤醒并运行 MausBot。

05 / 可选方式

用命令行启动

有 Node.js 24 或更新版本的电脑，可以从 npm 启动浏览器版。运行下方命令，按终端向导选择 AI 登录方式或 API Key，再选择模型。

node --version
npx openmausbot

保持终端运行。按 Ctrl + C 停止服务，下次执行同一个命令会继续使用已保存的配置。

开发者从源码运行

准备 Git、Node.js 24 或更新版本、pnpm，以及至少一个已安装并登录的 AI 引擎。用 HTTPS 克隆并安装依赖。

git clone https://github.com/milind-soni/OpenMausBot.git
cd OpenMausBot
pnpm install

如果已配置 GitHub SSH 密钥，可以用 git clone git@github.com:milind-soni/OpenMausBot.git 替换克隆命令。

在项目目录打开两个终端，分别运行以下命令，保持两个进程运行。

# 终端 1，启动后端
pnpm dev:server

# 终端 2，启动网页界面
pnpm dev

打开 http://127.0.0.1:5199。需要 Electron 窗口时，在项目目录另开一个终端运行 pnpm dev:desktop。

查看项目 README ↗

06 / 故障排查

遇到问题，先查这里

引擎显示未安装或不可用

先在同一台电脑的终端确认 CLI 能启动并已登录。重开应用，在 Agent engines 重新检测。终端正常而应用检测失败时，检查引擎路径配置。

能选模型，但发送后报 401、429 或超时

401 先核对登录是否过期、API Key 是否有效。429 查看服务商的配额和速率限制。超时先确认能访问模型服务，再发一条短消息重试。

Bot 找不到文件，或没有操作权限

核对 Bot 的工作目录、文件名、系统权限与审批卡。先用一个测试目录验证读取，再逐步授权所需操作。

定时任务没运行，或手机连不上

确认宿主机已开机、未休眠、网络正常且应用在运行。定时任务还要检查暂停状态、时区和运行历史。手机端可按配对指引检查连接。

仍无法解决时，提交操作系统、应用版本、引擎名称和脱敏后的报错。GitHub Issues ↗