openmozi

为什么选择 OpenMozi？

OpenMozi 的架构设计参考了 Moltbot，但专注于不同的使用场景：

| 特性 | OpenMozi | Moltbot | |------|------|---------| | 定位 | 国产生态优先的轻量框架 | 全功能个人 AI 助手 | | 代码量 | ~16,000 行 (64 文件) | ~516,000 行 (3,137 文件) | | 国产通讯 | QQ、飞书、钉钉、企业微信原生支持 | WhatsApp、Telegram、Slack 等 | | Node.js 版本 | >= 18 | >= 22 | | 适用场景 | 企业内部机器人、国内团队协作 | 个人多设备助手、海外平台集成 | | 学习 Agent 原理 | 代码简洁清晰，适合学习 | 代码庞大复杂，学习门槛高 |

OpenMozi 用 3% 的代码量实现了核心功能，专注简洁高效，易于理解和二次开发。 适合 学习 Agent 原理，深入了解 AI 助手的架构设计。

快速开始

环境要求

• Node.js >= 18
• npm / pnpm / yarn
• 跨平台支持：macOS、Linux、Windows

1. 安装

# 全局安装（推荐）
npm install -g mozi-bot

# 或者克隆项目开发
git clone https://github.com/King-Chau/mozi.git
cd mozi && npm install && npm run build

2. 配置

运行配置向导（推荐）：

mozi onboard

向导会引导你完成以下配置：

• 国产模型 — DeepSeek、豆包、智谱AI、DashScope、Kimi、阶跃星辰、MiniMax、ModelScope
• 自定义 OpenAI 兼容接口 — 支持任意 OpenAI API 格式的服务（如 vLLM、Ollama）
• 自定义 Anthropic 兼容接口 — 支持任意 Claude API 格式的服务
• 通讯平台 — QQ、飞书、钉钉、企业微信
• 记忆系统 — 启用/禁用长期记忆、自定义存储目录

配置文件将保存到 ~/.mozi/config.local.json5。

也可以直接使用环境变量（快速体验）：

export DEEPSEEK_API_KEY=sk-your-key

3. 启动

# 仅 WebChat（无需配置 QQ/飞书/钉钉）
mozi start --web-only

# 完整服务（WebChat + QQ + 飞书 + 钉钉）
mozi start

# 克隆项目方式
npm start -- start --web-only

打开浏览器访问 http://localhost:3000 即可开始对话。

支持的模型提供商

国产模型

| 提供商 | 环境变量 | 说明 | |--------|----------|------| | DeepSeek | DEEPSEEK_API_KEY | 推理能力强、性价比高 | | 豆包 | DOUBAO_API_KEY | 字节跳动火山引擎，Seed 深度思考系列，256k 上下文 | | DashScope | DASHSCOPE_API_KEY | 阿里云灵积，通义千问商业版，稳定高并发 | | 智谱 AI | ZHIPU_API_KEY | GLM-Z1/GLM-4 系列，清华技术团队，有免费额度 | | ModelScope | MODELSCOPE_API_KEY | 阿里云魔搭社区，Qwen 开源版，有免费额度 | | Kimi | KIMI_API_KEY | Kimi K2.5/Moonshot 系列，长上下文支持 | | 阶跃星辰 | STEPFUN_API_KEY | Step-2/Step-1 系列，推理与多模态 | | MiniMax | MINIMAX_API_KEY | MiniMax M2.1 系列，推理能力强 |

海外模型

| 提供商 | 环境变量 | 说明 | |--------|----------|------| | OpenAI | OPENAI_API_KEY | GPT-4o、GPT-4、GPT-3.5 | | OpenRouter | OPENROUTER_API_KEY | 聚合多家模型，统一 API | | Together AI | TOGETHER_API_KEY | 开源模型托管，Llama、Mixtral 等 | | Groq | GROQ_API_KEY | 超快推理速度 |

本地部署

| 提供商 | 环境变量 | 说明 | |--------|----------|------| | Ollama | OLLAMA_BASE_URL | 本地运行开源模型 |

自定义接口

支持配置任意 OpenAI 或 Anthropic 兼容的 API 接口。通过 mozi onboard 向导配置，或手动添加到配置文件：

{
  providers: {
    // 自定义 OpenAI 兼容接口（如 vLLM、LiteLLM 等）
    "custom-openai": {
      id: "my-provider",
      name: "My Provider",
      baseUrl: "https://api.example.com/v1",
      apiKey: "xxx",
      models: [
        {
          id: "model-id",
          name: "Model Name",
          contextWindow: 32768,
          maxTokens: 4096,
          supportsVision: false,
          supportsTools: true
        }
      ]
    },

    // 自定义 Anthropic 兼容接口
    "custom-anthropic": {
      id: "my-anthropic",
      name: "My Anthropic",
      baseUrl: "https://api.example.com",
      apiKey: "xxx",
      apiVersion: "2023-06-01",
      models: [
        {
          id: "claude-3-5-sonnet",
          name: "Claude 3.5 Sonnet",
          contextWindow: 200000,
          maxTokens: 8192
        }
      ]
    }
  }
}

通讯平台接入

QQ、飞书和钉钉都支持长连接模式，企业微信使用 Webhook 回调模式：

| 平台 | 连接模式 | 公网 IP | 接入文档 | |------|----------|---------|----------| | 飞书 | WebSocket 长连接 | 不需要 | 飞书接入指南 | | 钉钉 | Stream 长连接 | 不需要 | 钉钉接入指南 | | QQ | WebSocket 长连接 | 不需要 | QQ 接入指南 | | 企业微信 | Webhook 回调 | 需要 | 企业微信接入指南 |

长连接模式：无需公网 IP，无需配置回调地址，启动即可接收消息。

配置参考

配置文件支持 config.local.json5、config.json5、config.yaml 等格式，优先级从高到低。存放在 ~/.mozi/ 目录下。

{
  // 模型提供商
  providers: {
    deepseek: {
      apiKey: "sk-xxx"
    },
    dashscope: {
      apiKey: "sk-xxx",
      // 可选：自定义模型列表（覆盖预设）
      models: [
        {
          id: "qwen-max-latest",
          name: "通义千问 Max",
          contextWindow: 32768,
          maxTokens: 8192
        }
      ]
    },
    zhipu: {
      apiKey: "xxx"
    },
    modelscope: {
      apiKey: "ms-xxx"
    }
  },

  // 通讯平台（长连接模式，无需公网）
  channels: {
    feishu: {
      appId: "cli_xxx",
      appSecret: "xxx"
    },
    dingtalk: {
      appKey: "xxx",
      appSecret: "xxx"
    },
    qq: {
      appId: "xxx",
      clientSecret: "xxx",
      sandbox: false  // 沙箱环境设为 true
    },
    wecom: {
      corpId: "xxx",
      corpSecret: "xxx",
      agentId: "xxx",
      token: "xxx",
      encodingAESKey: "xxx"
    }
  },

  // Agent 配置
  agent: {
    defaultProvider: "deepseek",
    defaultModel: "deepseek-chat",
    temperature: 0.7,
    maxTokens: 4096,
    systemPrompt: "你是墨子，一个智能助手。"
  },

  // 服务器配置
  server: {
    port: 3000,
    host: "0.0.0.0"
  },

  // 日志级别
  logging: {
    level: "info"  // debug | info | warn | error
  },

  // Skills 配置（可选）
  skills: {
    enabled: true,           // 是否启用技能系统（默认 true）
    userDir: "~/.mozi/skills",     // 用户级技能目录
    workspaceDir: "./.mozi/skills", // 工作区级技能目录
    disabled: ["skill-name"],      // 禁用指定技能
    only: ["skill-name"]           // 仅启用指定技能
  },

  // 记忆系统配置（可选）
  memory: {
    enabled: true,                  // 是否启用（默认 true）
    storageDir: "~/.mozi/memory"   // 存储目录（默认 ~/.mozi/memory）
  }
}

Skills 技能系统

Skills 是 OpenMozi 的可扩展知识注入系统，通过编写 SKILL.md 文件，可以为 Agent 添加专业知识、自定义行为规则或领域能力，无需修改代码。

工作原理

Skills 通过 YAML frontmatter + Markdown 内容的方式定义，启动时自动加载并注入到 Agent 的系统提示词中。

技能加载顺序

| 优先级 | 来源 | 目录 | 说明 | |--------|------|------|------| | 1 | 内置 | skills/ | 项目自带的技能 | | 2 | 用户级 | ~/.mozi/skills/ | 用户自定义技能，所有项目共享 | | 3 | 工作区级 | ./.mozi/skills/ | 项目级技能，仅当前项目生效 |

同名技能按优先级覆盖，工作区级 > 用户级 > 内置。

编写 Skill

每个技能是一个目录，包含一个 SKILL.md 文件：

skills/
└── greeting/
    └── SKILL.md

SKILL.md 格式：

---
name: greeting
title: 智能问候
description: 根据时间和场景提供个性化问候
version: "1.0"
tags:
  - greeting
  - chat
priority: 10
---

当用户向你打招呼或问候时，请遵循以下规则：

1. **根据时间问候**: 根据当前时间使用合适的问候语
   - 早上 (6:00-11:00): 早上好
   - 下午 (13:00-18:00): 下午好
   - 晚上 (18:00-22:00): 晚上好

2. **友好热情**: 保持友好和积极的态度

3. **简洁明了**: 问候语简短有力

Frontmatter 字段

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 技能唯一标识 | | title | string | 否 | 显示名称 | | description | string | 否 | 技能描述 | | version | string | 否 | 版本号 | | tags | string[] | 否 | 标签，用于分类 | | priority | number | 否 | 优先级，数值越大越靠前（默认 0） | | enabled | boolean | 否 | 是否启用（默认 true） | | eligibility.os | string[] | 否 | 限制操作系统（darwin/linux/win32） | | eligibility.binaries | string[] | 否 | 需要的命令行工具 | | eligibility.env | string[] | 否 | 需要的环境变量 |

Skills 配置

{
  skills: {
    enabled: true,             // 是否启用（默认 true）
    userDir: "~/.mozi/skills", // 用户级技能目录
    workspaceDir: "./.mozi/skills", // 工作区级技能目录
    disabled: ["greeting"],    // 禁用指定技能
    only: ["coding"]           // 仅启用指定技能（白名单模式）
  }
}

记忆系统

记忆系统让 Agent 能够跨会话记住重要信息，如用户偏好、关键事实、任务上下文等。记忆默认启用，存储在 ~/.mozi/memory/ 目录。

工作原理

Agent 通过三个内置工具管理记忆：

| 工具 | 说明 | |------|------| | memory_store | 存储一条新记忆（包含内容和标签） | | memory_query | 根据关键词查询相关记忆 | | memory_list | 列出所有已存储的记忆 |

Agent 会在对话中自动判断何时需要存储或查询记忆，无需用户手动触发。例如：

• 用户说 "我喜欢简洁的代码风格" → Agent 自动调用 memory_store 存储偏好
• 用户问 "我之前说过喜欢什么风格？" → Agent 自动调用 memory_query 查询

配置

{
  memory: {
    enabled: true,                  // 是否启用（默认 true）
    storageDir: "~/.mozi/memory"   // 存储目录（默认 ~/.mozi/memory）
  }
}

也可以通过 mozi onboard 向导配置记忆系统（步骤 5/5）。

存储结构

记忆以 JSON 文件存储，每条记忆包含内容、标签和时间戳，支持按关键词检索。

定时任务 (Cron)

定时任务系统让 Agent 能够按计划执行任务，支持三种调度方式和两种任务类型：

调度类型

| 类型 | 说明 | 示例 | |------|------|------| | at | 一次性任务 | 在 2024-01-01 10:00 执行 | | every | 周期性任务 | 每 30 分钟执行一次 | | cron | Cron 表达式 | 0 9 * * * 每天 9 点执行 |

任务类型

| 类型 | 说明 | 用途 | |------|------|------| | systemEvent | 系统事件（默认） | 简单的提醒、触发信号 | | agentTurn | Agent 执行 | 执行 AI 对话，可投递结果到通道 |

agentTurn 任务支持以下参数：

• message — A