基本概念
Agim 是一个把 IM、Web 控制台和 Agent 连接在一起的轻量中枢。你可以在微信、飞书、钉钉、Telegram 或 Web 里发消息，让 Claude Code、Codex、Cursor、Kimi Code、Qoder、PI、MiMo Code、Antigravity、OpenCode 或内置 Agim Agent 帮你处理事情。
它不替代你已经在用的 Agent，也不要求你把工作流搬到一个新后台里。Agim 做的是消息路由、会话保持、审批、记忆、任务恢复和审计，让“在聊天里交代任务”变成一个可持续使用的入口。
- 消息入口：IM、Web 控制台、终端 TUI 都能进入同一套服务。
- Agent 调度：可以固定某个 Agent，也可以在对话里用命令临时切换。
- 安全控制：涉及文件、命令和网络访问的动作可以先发起审批。
- 长期任务：提醒、目标、定时任务、后台任务和崩溃恢复都由 Agim 接住。
- 本地数据：配置、会话、记忆和审计默认保存在
~/.agim，方便备份和迁移。
快速开始
更完整的脚本、npm 和源码安装方式见 安装页 。第一次使用建议先跑通 Web 和一个 Agent，再连接 IM。
npm install -g agim-cli
agim go
agim web
agim doctor-
agim go会检查环境，帮你配置一个可用 Agent，并启动服务。 - 如果已经安装 Claude Code、Codex、Cursor 等 CLI Agent，Agim 会尝试识别它们。
- 如果还没有安装 CLI Agent，也可以直接配置大模型 API，使用内置的 Agim Agent。
- Web 对话跑通后，再到设置里连接微信、飞书、钉钉、Telegram 或邮件通知。
IM 渠道
IM 渠道不需要一次全开。先选择你最常用的一个，把消息收发、审批和 Agent 回复跑通，再逐步增加其他入口。
| 入口 | 准备什么 | 适合做什么 |
|---|---|---|
| 微信 / 企业微信 | 扫码或按企业应用方式完成授权，适合个人、团队群和移动端高频沟通。 | 日常对话、审批、提醒、长任务进度回传。 |
| 飞书 / Lark | 创建企业自建应用，填入 App ID、Secret 与事件订阅配置。 | 团队协作、群内 @bot、卡片审批、文件和图片消息。 |
| 钉钉 | 使用企业内部应用与 Stream 模式，不是单向 Webhook 群机器人。 | 企业群、移动端审批、语音和图片类消息处理。 |
| Telegram / Discord | 属于可选全局 IM 渠道，启用后按 Bot Token 或应用凭据连接。 | 跨境团队、开源社区、备用通知通道。 |
| 邮件 | 配置 SMTP 发信信息。 | 提醒、告警和长任务完成通知，通常作为补充通道。 |
| Web 控制台 | 启动服务后打开本地 Web 地址即可使用。 | 首次调试、配置 Agent、查看任务、处理审批和检查日志。 |
一个实用顺序是：先 Web 控制台，后 IM；先私聊，后群聊；先文字，后文件、图片和语音。这样排查起来更清楚。
主流 Agent
Agim 会把不同 Agent 放到同一条消息总线上。你可以设置默认 Agent，也可以在一段对话里临时切换。下面这些是当前主要支持的后端。
| Agent | 常用命令 | 准备什么 | 适合场景 |
|---|---|---|---|
| Agim Agent | /agim, /na, /llm | 不需要额外 CLI。配置一个大模型 API 即可使用。 | 默认助手、问答、总结、提醒、轻量工具调用和没有安装 CLI Agent 的场景。 |
| Claude Code | /cc, /claude | 安装 Claude Code 并完成登录。 | 代码理解、项目修改、复杂多步任务。 |
| Codex | /cx, /codex | 安装并登录 Codex CLI。 | 代码审查、修改、测试、与本地仓库协作。 |
| Cursor | /cs, /cursor | 安装 cursor-agent，并完成 OAuth 或 API Key 配置。 | 熟悉 Cursor 工作流的开发团队。 |
| Kimi Code | /kimi, /km | 安装 Kimi Code CLI，并完成首次登录。 | 中文代码与文档场景。 |
| Qoder | /qd, /qodercli | 安装 Qoder CLI 并登录。 | Qoder 用户的远程调度入口。 |
| PI | /pi, /pi-agent | 安装 PI CLI，并完成认证。 | 已有 PI 工作流的团队。 |
| MiMo Code | /mo, /mimo-code | 安装 MiMo Code CLI，并完成登录。 | MiMo 生态与国内模型工作流。 |
| Antigravity | /agy, /ag | 安装 Antigravity CLI，并完成首次授权。 | Google 系 Agent 工作流。 |
| OpenCode | /oc | 安装 OpenCode 并完成认证。 | 自托管、开源工具链和可控环境。 |
建议先选一个你最熟悉的 Agent 做默认入口。等稳定后，再把其他 Agent 作为专项工具接进来，例如让 Codex 跑测试、让 Claude Code 做复杂规划、让 Agim Agent 处理日常问答。
Agim Agent（系统内置）
Agim Agent 是系统内置的 Agent。它不依赖外部 CLI，只需要配置一个大模型 API，就能接入 OpenAI 兼容、Anthropic 兼容、Ollama、vLLM 或国内常见模型服务。
它适合做默认助手：回答问题、总结内容、创建提醒、写入记忆、处理轻量文件和工具调用。如果你还没有安装 Claude Code、Codex、Cursor 等主流 Agent，Agim Agent 可以先把整个系统跑起来。
-
模型配置放在
llmBackends和llmRoles中，密钥单独保存。 -
角色说明可以写在
~/.agim-workspaces/native/AGENTS.md，改完可直接生效。 - 它同样使用审批、审计、记忆、提醒和任务恢复能力，不是一个孤立的聊天模型。
常用命令
这里列的是日常最常用的一组命令。实际使用时，不必每次都记命令；很多能力可以用自然语言触发。
| 命令 | 说明 |
|---|---|
agim go | 第一次启动推荐用它：检查环境、引导配置一个 Agent，并启动 Web 与服务。 |
agim web | 打开 Web 控制台，适合调试、配置和查看任务。 |
agim doctor | 检查 Node、CLI Agent、配置文件、端口和常见依赖。 |
agim config | 重新进入配置向导，修改 IM、Agent、模型 API、Web 端口等。 |
agim start / status / restart / stop | 按当前运行方式管理服务。 |
/agents | 查看当前可用的 Agent。 |
/cc, /cx, /cs, /kimi, /qd, /pi, /mo, /agy, /agim | 在当前会话里切换指定 Agent。 |
/new | 开一个新会话，清掉当前上下文和固定 Agent。 |
/remind | 创建一次性或周期提醒，可通过 IM 或邮件送达。 |
/memo | 管理长期记忆。也可以直接说“帮我记一下……”，让 Agent 自动保存。 |
/goal 或 /long_task | 给当前线程设定长目标，让后续对话围绕同一件事推进。 |
/heartbeat | 让 Agent 定期检查是否有待处理的事情。 |
/job 或 /tasks | 查看后台任务、长任务和定时任务状态。 |
/audit 或 /stats | 查看调用记录、成本、耗时和运行状态。 |
长任务与目标
IM 很适合交代任务，但长任务不能只靠一条聊天消息硬撑。Agim 把这些工作拆成几个可恢复的对象：目标、提醒、定时任务、后台任务和输出投递。
- 目标：用
/goal或/long_task给当前线程设定持续目标，后续对话会围绕它推进。 - 提醒：用
/remind创建一次性或周期提醒，也可以让 Agent 根据自然语言帮你设置。 - 定时任务：用
/cron周期性触发某个 Agent，例如日报、周报、巡检和资料整理。 - 后台任务：长时间运行的任务会进入任务队列，状态可以在 Web 或
/job中查看。 - 可靠投递：回复先进入本地 outbox，再发送到 IM 或 Web；服务重启后也能继续处理。
对使用者来说，你只需要知道：复杂事情可以拆开交代，Agim 会尽量保留进度，并把结果带回到原来的会话里。
安全与审批
Agim 的安全策略不是靠“希望模型听话”，而是在服务层做限制。你可以把它理解成一组在 Agent 和真实系统之间的护栏。
- 审批：写文件、执行命令、访问网络等高风险动作可以先推送审批卡。
- 敏感路径保护：密钥、配置、系统账号、Agent 指令文件等内容默认不允许被读出并发回 IM。
- Web 鉴权：Web 控制台支持 token 访问控制，公网部署时建议放在反向代理和 TLS 后面。
- 管理员：重启、停止服务和高风险设置建议只开放给管理员账号。
- 审计：调用记录、执行结果、耗时和错误会被记录，方便排查和复盘。
如果只是自己本机试用，可以先保持默认设置；如果放到团队或服务器上，建议先配置管理员、Web 访问方式和备份策略。
配置
大多数配置可以通过 agim go、agim config 或 Web
设置完成。只有自动化部署、服务器迁移或排障时，才需要直接看文件。
| 位置 | 用途 |
|---|---|
~/.agim/config.json | 主配置：启用的 IM、Agent、Web 端口、默认 Agent、远端 Agent 等。 |
~/.agim/llm-secrets.json | Agim Agent 使用的大模型 API 密钥。 |
~/.agim/env | 适合放环境变量，例如 SMTP、地图服务、可选功能开关。 |
~/.agim-workspaces/<agent>/ | 每个 Agent 的独立工作区、角色文件和长期上下文。 |
推荐做法是：用向导写配置，用 Web 检查状态；手工编辑前先备份 ~/.agim。
Web 控制台
Web 控制台是最适合首次配置和日常查看状态的入口。它不只是聊天页面，也承担配置、审计和任务面板的作用。
- 聊天：在浏览器里直接和 Agent 对话，确认模型、审批和回复链路是否正常。
- 设置：启用 IM、切换默认 Agent、配置模型 API、管理远端 Agent。
- 任务：查看长任务、定时任务、后台任务和失败重试。
- 记忆：查看和维护长期事实、备忘和用户画像。
- 审计：排查某次调用发生了什么、用了哪个 Agent、是否失败。
本机使用时可以直接打开；服务器使用时，建议通过反向代理和 HTTPS 暴露，并保留 token 鉴权。
终端 TUI
agim tui 是本地终端里的聊天界面。它不依赖 IM，适合在服务器上调试
Agent、快速测试模型配置，或者临时跑一段本地对话。
agim tui
agim tui --agent codex
agim tui --agent native
agim tui --resume last
TUI 的价值在于排障：如果 TUI 能正常和 Agent 对话，而 IM 不行，问题大概率在 IM 凭据或消息回调；如果 TUI 也不行，就先检查 Agent 安装、登录和模型配置。
技能系统
技能是给 Agent 的可复用能力包，通常由一个 SKILL.md
加上脚本、参考资料或模板组成。它适合放稳定的工作方法，而不是每次都在聊天里重复交代。
-
把技能放到
~/.agim/skills/<name>/SKILL.md后，Agim 可以在需要时让 Agent 读取。 - 技能可以描述流程、约束、示例，也可以引用脚本和素材。
- 命令行 Agent 与 Agim Agent 都可以使用同一套技能。
例子：日报生成、PR 审查规范、客服回复风格、内部系统操作步骤，都适合做成技能。
服务生命周期
Agim 最常见的运行方式是先用 agim go
跑起来，再根据使用场景选择前台、后台或 systemd。
| 方式 | 适合场景 | 常用命令 |
|---|---|---|
| 前台运行 | 本机调试、看实时日志。 | agim start |
| 后台运行 | 个人机器长期挂着。 | agim start --bg |
| systemd | Linux 服务器、团队部署、需要随系统启动。 | systemctl restart agim |
日常排查先看 agim status 和 agim doctor；需要改配置时用 agim config 或 Web 设置。
架构
从使用者角度看，Agim 的链路可以理解成下面这样：入口负责收消息，路由层选择 Agent，安全层处理审批和审计，最后由投递层把结果送回原来的地方。
IM / Web / TUI
│
▼
Agim Router ── Session / Memory / Goal
│
▼
Approval / Audit / Recovery
│
▼
Agents: CLI Agent / Agim Agent / Remote Agent
│
▼
Outbox → IM / Web / Notification这也是为什么建议先跑通 Web 和一个 Agent：核心链路确认后，再接入更多 IM、更多 Agent 和更复杂的团队规则。