基本概念

Agim（阿吉姆）是一个常驻 Node.js 进程，把 IM 渠道（微信、Telegram、飞书、钉钉、Discord、邮件）和 AI agent（Claude Code、OpenCode、Codex、Copilot，或任意 ACP 端点）桥接到一起。单进程，无需 Docker / Redis。

会话 (session) 以 platform:channel:thread 为键，记录最近一次活跃的 agent、模型、历史消息，30 分钟无新消息自动归档。
意图分类器 走轻量启发式（中英双语关键词），无明确 /前缀 时智能选 agent，再用 sticky 锁定一段对话。
审批总线 拦截 agent 的工具调用（写文件、跑 shell、访问网络），在 IM 里推一张审批卡，用户回 y/n/all 才放行。
持久存储 全在 SQLite —— ~/.agim/（从 0.x 升级则继续用 ~/.im-hub/）下 jobs.db / memos.db / reminders.db / audit.db / 会话文件，重启不丢，30 天自动修剪。

快速开始

完整安装路径有三种（脚本 / npm / 源码），见安装页。最简流程：

npm install -g agim-cli      # 需要 Node ≥ 18
agim                         # 双语方向键向导（推荐）
agim start                   # 前台启动

向导会带你过一遍：选语言 → 选启用哪些 IM → 给每个 IM 走配置（微信扫码 / 飞书 App Secret / 钉钉 ClientID …）→ 选启用哪些 agent → 配 SMTP（提醒邮件）/ 百度地图 AK（地址解析）。

IM 渠道

每个 IM 在向导里有自己的子菜单，包含状态展示、Configure / Re-configure / Remove。配置存到 ~/.agim/config.json （升级用户为 ~/.im-hub/config.json；chmod 600）。

渠道	凭据 / 连接	富媒体	触发条件
WeChat iLink	扫码登录，凭据存 `~/.agim/wechat-credentials.json`	图片 / 文件 / 语音 / 视频	私聊或群里 @bot
Telegram	@BotFather token + channel id	图片 / 语音 / 音频（whisper 转写）	私聊或群里 @bot
Feishu / Lark	企业自建应用 App ID + Secret，长连接	图片 / 文件 / 原生位置消息	私聊或群里 @bot
DingTalk 钉钉 Stream	企业内部应用 ClientID + ClientSecret，Stream WebSocket	图片（下载 → multimodal Read）/ 语音（服务端 ASR + whisper 兜底）	私聊或群里 @bot
Discord	Bot token + allowed guild/channel ids	—	配置的频道里直接发
Email 仅推送	SMTP host / port / user / pass / from	—	只发，不收（用于 /remind 投递）

钉钉细节：必须创建「企业内部应用」并开启 Stream 模式（不是「群聊机器人 Webhook」 —— 那个只能单向推送）。1 人企业也算，注册个人企业即可。钉钉服务端不会向 bot 投递「位置消息」，要做位置请用 /memo here 走捕获链接，或者直接打字描述地址让 agent 走百度地图 geocode。

AI agent

每个 agent 对应一个本地 CLI 二进制；向导会用 <cmd> --version 探测安装状态，标记「已安装 / 未安装」并给出安装命令。

Agent	安装	说明
Claude Code	`npm i -g @anthropic-ai/claude-code`	多模态（可识别图片附件标签）；工具调用走审批总线；支持 --resume 续命
OpenCode	`npm i -g opencode-ai@latest`	HTTP driver（Agim 内置 daemon），sessionID 由 opencode 自己生成；登录走 `opencode auth login`
Codex	`npm i -g @openai/codex`	codex --thread 续命；可见完整 imhub MCP 工具表（reminder + memo）
GitHub Copilot CLI	`npm i -g @github/copilot`	多种安装路径（npm / gh extension / brew / VSCode），插件自动识别
Remote ACP	—	任意 HTTP agent；通过向导里「Remote ACP agents → Add」加入，验证 manifest，支持 Bearer / apikey 鉴权

斜杠命令

所有 IM 通用，平台无关。除 /memo 等本地命令外，多数都通过 agent 的 MCP 工具实现，因此自然语言也能触发同样的能力。

命令	作用
`<text>`	直接发，路由到 sticky agent；无 sticky 时用意图分类器选默认 agent。
`/cc` / `/oc` / `/cx` / `/co`	强制切到 Claude Code / OpenCode / Codex / Copilot。
`/new`	开新会话（清历史，清 sticky）。
`/remind 1m 喝水`	一次性提醒；支持 `every:5m` / `daily:08:00` / `weekly:1,3,5:09:00` 。LLM 自动润色投递文案；可走邮件或 IM。
`/memo` / `/memo list` / `/memo show <id>`	管理已存的 memo（5W1H）。要新增请直接说自然语言（"帮我记下：周五带电脑回家"），agent 会调 save_memo。
`/memo here [what]`	返回一个短链，浏览器打开后授权 GPS，自动写一条带坐标的 memo。在钉钉等不投递 location 的 IM 上特别有用。
`/agents` / `/status` / `/help`	列已注册 agent / 连接状态 / 帮助菜单。
`/model` / `/think on\|off`	查看或切换模型 / 开关 extended thinking。
`/plan on\|off`	让 agent 走只读 plan 模式（claude-code 自动加 --permission-mode plan）。

配置

Agim 读三处配置源，优先级依次为：

~/.agim/config.json （升级用户为 ~/.im-hub/config.json） — 主配置：启用哪些 IM、哪些 agent、默认 agent、各 IM 的凭据对象、acpAgents 列表。chmod 600，向导写入。
~/.agim/env （或 ~/.im-hub/env） — 简单 KEY=value 文件，存 SMTP 凭据和百度地图 AK 等敏感环境变量。chmod 600。systemd 单元通过 EnvironmentFile= 加载。
process.env — 运行时进程环境，向导读取时会作为前两者的回退（systemd unit Environment= 行也走这条）。

常用环境变量：

变量	作用
`IMHUB_SMTP_HOST` / `_PORT` / `_USER` / `_PASS` / `_FROM`	邮件提醒投递。
`IMHUB_BAIDU_MAP_AK`	/memo 地址解析（geocoding）。
`IMHUB_WEB_BIND`	Web 控制台监听地址，默认 127.0.0.1，公网部署建议加反代。
`IMHUB_WEB_REQUIRE_AUTH`	0 = 关闭 token 登录（仅 localhost 推荐），1 = 强制开启。默认根据 bind 自动判断。
`IMHUB_APPROVAL_DISABLED`	=1 关闭工具调用审批（默认开启）。
`OPENAI_API_KEY` / `IMHUB_WHISPERCPP_BIN`	语音转写后备（钉钉自带 ASR 优先；微信走 STT 优先）。

服务生命周期

三种运行模式自动识别：

systemd — 安装脚本以 root 跑时落 /etc/systemd/system/agim.service（升级用户为 im-hub.service）。后续用 systemctl 或 agim restart 管理。
后台守护进程 — agim start --bg 用 nohup + setsid + pid 文件，跨平台（Linux / macOS / WSL2）。
前台进程 — agim start 直接挂在你的终端上，Ctrl-C 退出。

agim status 一键探测当前是哪种模式 + pid + uptime + Web URL。

架构

入站消息归一化后交给 router；router 选 agent，agent 输出走出站到原 IM。

┌─ Messenger ingress ──────────────────────────────┐
│ WeChat iLink   (long-poll + image/voice/file)    │
│ Telegram       (grammy + photo/voice/audio)      │
│ Feishu         (Lark SDK WebSocket)              │
│ DingTalk       (Stream WebSocket + ASR baked in) │
│ Discord        (discord.js Gateway)              │
│ Web Chat       (browser WebSocket)               │
└───────────────────────┬──────────────────────────┘
                        │ MessageContext
                        ▼
                  Router + Session
                        │
                        ▼
                Approval bus (HITL)
                        │
                        ▼
                Agent adapters
            ┌────────────┴────────────┐
        Local CLI                 Remote ACP
   (Claude / Codex / OC / Co)  (HTTP /events)

获取帮助

GitHub README — github.com/benking007/imhub （双语，长版的安装 / 配置 / 命令参考）。
CHANGELOG — 完整版本历史。
问题反馈 — github.com/benking007/imhub/issues。