Mina OpenClaw Channel

Mina IM 的 OpenClaw 原生渠道插件，连接你自行部署和运行的 AI Agent。Mina 不提供默认模型或模型密钥。

当前为 0.3.7 公开预览候选版，支持助手所有者的文本、图片和文件私聊，并自动准备受限群执行环境；真实云服务器、Mina 服务和手机的端到端验收尚未完成。

安装

发布到 npm 后，使用以下不带版本号的命令安装官方 registry 的最新发布版：

openclaw plugins install npm:@minaim/openclaw-channel
openclaw channels add mina

安装时按 OpenClaw 提示审阅来源及能力。用户安装公开包不需要 npm 账号。一个 account 对应一个 Mina AI 助手，可配置多个 account。

配置

在 Mina App 的 AI 助理页面创建助手，向导中输入 HTTPS 网关、AppID、助手 ID、所有者 ID、凭证版本和一次性 AppSecret。密钥通过隐藏输入保存至私有文件，不写入 OpenClaw 普通配置。宿主只保存配置路径；已有不同绑定不覆盖。

启动或重启 Gateway 后在 App 检查连接。配置探测是本地被动检查，不表示已联网。Mina 长轮询只需出站 HTTPS。同一助手同时只允许一个有效消费者，插件不会自动抢占另一个实例。

更新

更新前停止当前 Gateway，再执行：

openclaw plugins update mina

完成后重新启动 Gateway。用户不需要填写版本号；npm 更新跟随 latest 发布标签，Gitee 的代码改动需重新发布 npm 才会进入该更新渠道。保留原来的私有配置、SQLite 和待提交文件，不通过删除状态库重试任务。活动执行的热升级与自动回滚尚未提供。

环境

• 已验证 OpenClaw 2026.10.5；Node >=24.16.0 <25 或 >=26.1.0。
• Python >=3.9，使用标准库持久工作进程。npm 包已包含 Python 源码，但服务器仍需提供 Python 运行时。
• Linux/macOS 本地磁盘；实际宿主测试在 Linux 完成。
• 私有目录 0700、配置文件 0600；容器中保留整个宿主 state 持久卷。

宿主版本与运行时检查不因更新到最新插件而取消。不要把本插件当作模型或 Agent 托管服务。

图片和文档

支持 PNG/JPEG/GIF，单张最大 8 MiB；文件最大 20 MiB；最终回复最多 5 个附件。TXT、PDF、Office 文档传实际字节，解析、OCR 和编辑取决于用户宿主的模型与工具。输出文件目录和远程域名需由部署者显式授权，不从聊天正文推导上传权限。不支持流式、语音和视频；主动发送支持服务器绑定的来源会话文本、图片和文件；不允许任意跨会话目标。普通安装向导及旧账号首次启动会自动准备独立的 owner/members Agent、工作目录和受限工具，无需手工填写群 profile。使用宿主已选模型及官方 provider 凭证解析，不复制个人记忆、技能或凭证文件。已有显式群执行配置保留并校验；不安全配置会阻止启动。若宿主缺少配置接口或模型凭证不可用，私聊继续运行，运行状态 groupReady 为 false、groupError 说明原因，不向 Mina 声明群能力。doctor 仅被动检查本地配置，不代表联网或群模型调用成功。

可靠性与许可

消息先可靠接收，再申请执行许可；未知执行不自动重跑，已保存结果失败只补交。诊断输出固定错误码，不含密钥、对话正文或完整附件能力链接。

维护与版本记录：Mina Agent 插件仓库。当前仓库公开可读，npm 包也公开可下载。此包标记为 UNLICENSED，公开分发不授予开源许可证。

群内先 @助手再选择图片或文件；群文件输出只能使用本次事件输入和 Worker 下发的 group_output_dir，不能借用个人输出目录。定时本地附件仅使用绑定来源会话的输出目录或允许的公开 HTTPS 附件，不复用历史事件输入。识图、解析及生成由宿主模型/工具处理，插件不维护模型名单；没有可发送结果或附件永久不可用时给脱敏文字，临时网络与安全错误保留原有处理边界。

云端安全生成候选：群专用 Agent 的 tools.allow 可显式添加 mina_generate_image、mina_create_document。图片使用宿主原生生成服务；基础文档导出使用远端 Python 格式库（TXT/MD/CSV 无额外依赖，PDF/Office 按需安装）。模型只传内容，目录与来源由插件确定；不开放主机 shell。配置和限制见源码仓库 integrations/mina-agent/README.md 的“云服务器生成后回群”。本版为公开预览；新群能力需要配套Mina服务端部署后开启。

基础文档导出：TXT/Markdown/CSV 使用标准库。需要 PDF/Word/Excel/PPT 时，在 Mina 配置所选的远端 Python 环境安装对应库（可按需选择）：

python -m pip install reportlab==5.0.1 python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2

自动创建的群 Agent 仅开放网页搜索/获取、Mina 来源受限的图片/文档生成；只有 owner Agent 添加 cron。保持原私有配置、SQLite 和附件持久卷，更新前停止 Gateway，更新完成再启动。插件升级不会替你启用服务端新能力。

已有自定义群 Agent 也必须隔离：有效 skills 必须为 []、contextInjection 为 never、memory.search.enabled 为 false；可以继承明确关闭这些能力的全局设置。群工作目录和 Agent 数据目录不得与私有 Agent 的工作目录或数据目录重叠，包括宿主自动推导的目录。插件保留有效的自定义 ID 和配置；不安全的显式映射会阻止该账号启动，需先修正配置，不会自动复制或改写个人技能、记忆及凭证。

OpenClaw 将 cron 工具名规范化为 automations；两种名称都受来源群限制。群 owner 只能创建发回当前群的任务，不能列举、修改或运行其他任务。若宿主以 CONFIG_INCLUDE_OWNERSHIP 拒绝自动写入群 Agent（例如涉及 $include 所属配置），插件保留原文件并仅运行私聊，groupReady 为 false、groupError 为 group_execution_unavailable；不会展开或覆写 include 文件。此类配置尚不能保证自动启用群能力。

0.3.1 文档读取修复

校验本次事件的附件大小及SHA后，插件提取TXT/Markdown/CSV、DOCX/XLSX/PPTX及PDF正文，保留文件元数据和解析限制；不会按聊天中的任意本地路径或网址读取文件。PDF需要宿主提供pdftotext，旧版DOC/XLS/PPT需要catdoc/xls2csv/catppt；未安装、加密或无可提取文本时返回明确限制。图片仍交给宿主的视觉模型；升级插件不会替用户启用或配置视觉模型。

更新沿用现有配置、SQLite和待提交媒体，不需要重新绑定Mina。群专用执行器同时传递现有宿主所需的Agent身份，权限和工具范围保持原配置。