IRIS 文档

从安装到把它接进你的工作群。当前版本 v1.0.0，适用于 Windows、macOS 与 Linux。

概览

IRIS 是一个自进化的个人 AI 代理。同一份内核提供三种入口：桌面端图形界面、终端界面（TUI）与消息网关。 三者共享同一套配置、会话库和技能，所以在桌面端开的对话，可以在手机上接着聊。

• 桌面端：图形化会话、技能发现、渠道配置与产物查看。
• 终端：weiagent 进入全屏 TUI，斜杠命令直接操作模型、技能与上下文。
• 消息网关：把同一个代理接到企业微信、飞书、钉钉、Telegram 等渠道。

所有本地数据都在 ~/.hermes 下。卸载时删除该目录即可彻底清除，不会在系统其它位置残留。

快速开始

两步：装好，然后开始对话。

# 1. 安装
$ curl -fsSL https://iris.agent/install.sh | bash

# 2. 重新加载 shell 后启动
$ source ~/.bashrc
$ weiagent

首次启动会引导你选择模型服务商并填入凭证。想一次配好全部内容（模型、工具、消息渠道），运行向导：

$ weiagent setup

安装

macOS / Linux / WSL2

$ curl -fsSL https://iris.agent/install.sh | bash

Windows

在 PowerShell 中执行：

> iex (irm https://iris.agent/install.ps1)

安装完成后可能需要重开终端，再运行 weiagent 开始对话。

Android / Termux

aarch64 设备请使用预发布的 APT 包（含 Python、Node.js 与 TUI），不要用桌面版安装脚本，否则依赖会装错架构。

桌面安装包

图形界面版本从下载页获取：Windows 为 .exe，macOS 为 .dmg，Linux 为 .AppImage / .deb。桌面端与 CLI 共用同一份 ~/.hermes。

首次配置

配置分三步，逐步细化：

配置写在 ~/.hermes/config.yaml，密钥写在同目录的 .env。两者都支持多套配置档案，互不干扰。

模型与服务商

对话中随时切换，不需要重启，也不需要改代码：

/model                      # 交互式选择
/model openrouter:anthropic/claude-sonnet-4
/model nous:hermes-4-405b

支持的服务商包括 Nous Portal、OpenRouter（200+ 模型）、NVIDIA NIM、Kimi / Moonshot、智谱 GLM、MiniMax、Hugging Face、OpenAI，以及任意兼容 OpenAI 协议的自定义端点。

不想逐个申请 Key 的话，可以用订阅制的模型网关一次覆盖模型、联网搜索、图像生成、语音合成与云浏览器；也可以按工具粒度混用——模型走订阅，搜索走自己的 Key。

上下文与用量

/compress                   # 压缩上下文，保留结论
/usage                      # 查看本轮与累计用量
/insights --days 7          # 近 7 天使用洞察

技能

技能是写给人看、也能被代理读懂的操作手册：一份 SKILL.md 加上可选的脚本与资源。IRIS 会在完成复杂任务后自动生成技能，并在后续使用中改写它。

• 查看与启用：对话里输入 /skills，或在桌面端「技能与工具」页面浏览。
• 直接调用：/<skill-name>，例如 /weekly-report。
• 兼容标准：遵循 agentskills.io，社区技能可直接导入。
• 策展机制：长期不用或效果差的技能会被降级、合并或淘汰，避免清单膨胀。

把团队流程写成技能是最划算的投入：一次把步骤和坑写清，之后每次执行都一致。

消息渠道

消息网关是一个独立进程，负责把各平台的消息转给同一个代理内核，再把结果投递回去。

# 交互式选择要接入的渠道并填写凭证
$ weiagent gateway setup

# 前台启动（生产环境建议交给 systemd / 计划任务托管）
$ weiagent gateway start

企业微信、飞书、钉钉均为原生适配，不需要公网 IP 或内网穿透：

每个渠道可单独设置允许的用户与会话，未授权的人发消息不会触发代理。定时任务的结果也可以指定投递到某个渠道。

逐个平台的图文步骤（每一步点什么、填什么、看到什么算成功）见下面的渠道接入手册。

渠道接入手册

企业微信、钉钉、飞书三家都走长连接——由你的电脑主动连平台，所以不需要服务器、公网 IP、域名或内网穿透， 公司内网、家用宽带、笔记本连热点都能用。三个平台在各自后台点几下拿到凭证，回 IRIS 粘两个值就通了。

三个平台通用的两个坑

• 「保存并重连」不等于重启。它只让已有的后台进程重连一次，新填的凭证经常不生效。 改完要彻底退出 IRIS（右下角托盘图标也要退）再打开，或执行 bin\hermes.exe gateway restart。
• 第一次发消息会要一次「批准」。收到带配对码的英文提示不是报错，是授权机制。 在跑 IRIS 的机器上执行 hermes pairing approve wecom <配对码>（钉钉填 dingtalk、飞书填 feishu）， 批准后立刻生效，不用重启，之后也不用再批。

企业微信

企业微信侧做 4 件事（找入口 → 建机器人 → 拿凭证 → 设可见范围），IRIS 侧只做 1 件。 不需要管理员权限：普通成员在客户端「工作台 → 智能机器人」里就能建，只有「让全公司都能用」才需要管理员。

• 创建时必须选 API 模式创建：Bot ID 和 Secret 只在这个模式下生成，选「AI 自动生成 / 手动创建」翻遍页面也找不到。
• 可见范围里一定要有你自己。最常见的失误是只加了同事忘了加自己，结果自己搜不到机器人，看着像接入失败。
• 要在群里 @ 它，需要额外开一行 WECOM_GROUP_POLICY=open（写在 %LOCALAPPDATA%\hermes\.env），改完重启。有外部联系人的大群建议保持默认的配对模式。

内嵌预览加载不出来时，点右上角「新窗口打开」或「下载」查看原文件。

钉钉

钉钉侧做 4 件事（建应用 → 拿凭证 → 加机器人 → 发布），IRIS 侧填 4 个字段。 前 4 步都在 open-dev.dingtalk.com 后台，第 5 步才回到 IRIS。

• Allowed users 留空 = 允许任何人使用，而这个机器人能执行命令、读写你电脑上的文件。务必把自己的 StaffId 填进去。
• 机器人接收模式必须选 Stream，选 HTTP 回调就要公网地址加解密配置，Iris 用不上。
• 权限里要开通 qyapi_robot_sendmsg，否则现象是「能收到消息、一直显示思考中、发不出回复」。
• 应用必须发布（应用发布 → 创建新版本）。只保存不发布，机器人不会出现在任何人的钉钉里，凭证也调不通——这是最容易漏的一步。

内嵌预览加载不出来时，点右上角「新窗口打开」或「下载」查看原文件。

飞书

飞书侧要做 6 件事（建应用 → 加机器人 → 开权限 → 订阅事件与回调 → 拿凭证 → 发版），IRIS 侧只填 2 个值。 比另外两家多两道闸门：建应用可能要管理员授权，改完配置必须重新发版。

• 最容易漏的是「获取用户发给机器人的单聊消息」（im:message.p2p_msg:readonly）。它不在默认权限里，漏了之后发消息完全没反应，不报错、日志里也没有东西。另外三条：im:message:send_as_bot、im:message.group_at_msg:readonly、im:resource、im:chat:readonly。
• 事件配置勾 im.message.receive_v1，回调配置勾 card.action.trigger；两个页签订阅方式都选「使用长连接」。
• 不发版等于没配：权限、事件、回调都存在草稿里，创建版本并发布通过后才生效，一般 1–2 分钟。
• 群聊默认只放行单聊，要开 FEISHU_GROUP_POLICY=open；固定几个人长期用可以写白名单 FEISHU_ALLOWED_USERS=<open_id>。

内嵌预览加载不出来时，点右上角「新窗口打开」或「下载」查看原文件。

定时任务

用自然语言描述计划即可，调度器会解析成 cron 表达式并托管执行。

• 桌面端：左侧「定时任务」→ 选择模板（晨间简报、邮件巡检、周报、价格监控等）或自定义。
• 执行结果默认回到发起对话的渠道；也可以指定固定投递给某个群或个人。
• 无人值守运行，失败会记录原因并在下一轮重试。

子代理与并行

长任务不必占用主对话。IRIS 可以派生出隔离子代理，各自带独立上下文并行推进，完成后只把结论交回主线。

# 让代理把三件事分给三个子代理同时做
请并行处理：拉取上周数据、生成图表、写一份周报草稿

需要极致节省上下文时，可以让代理写一段 Python 脚本，通过 RPC 直接调用工具，把整条多步流水线压进一轮。

插件

扩展能力优先做成插件，而不是往内核里加工具。一个插件是一个目录：

plugins/
└── my-tool/
    ├── plugin.yaml        # 元信息与依赖声明
    └── __init__.py        # register(ctx) 里注册工具

在 register(ctx) 中调用 ctx.register_tool(...) 即可把工具挂进工具集；插件也可以注册新的模型服务商、记忆后端或消息平台。启用后在桌面端「技能与工具」页可见。

CLI 参考

常用斜杠命令

排障

先跑一次诊断，大多数问题能直接定位：

$ weiagent doctor

• 提示找不到命令：重新加载 shell（source ~/.bashrc）或重开终端。
• 模型报鉴权错误：weiagent model 重新填写凭证，注意 .env 里不要留空格。
• 渠道收不到消息：确认网关进程在运行（weiagent gateway status），并检查该渠道的授权用户列表。
• 响应变慢或费用异常：工具集开得太多会放大每轮请求，用 weiagent tools 收敛。

更新日志

v1.0.0

• 桌面端正式版：会话、技能发现、渠道配置、产物一体。
• 消息网关支持 26 个渠道，含企业微信（智能机器人 / 自建应用）、飞书、钉钉。
• 技能策展：自动生成、使用中改进、长期不用则合并淘汰。
• 六种执行后端：本地、Docker、SSH、Daytona、Singularity、Modal。
• 多配置档案隔离，可在同一台机器上跑多套互不干扰的代理。
• 定价上线：体验版、标准版、高级版。