Agent Autoloop 是什么？
Claude Code、Codex 等命令行 Agent 通常需要人在终端旁持续交互：输入任务、等待执行、回答问题，再让它继续。如果终端关闭或人暂时离开，流程往往就会中断。
Agent Autoloop 是一个面向命令行 Agent 的轻量自动化中台。它将任务调度放进零运行时依赖的内核，并把事件来源、Agent、通知通道和交付流水线拆成可替换的插件。它可以在本地 Mac 或 Linux 电脑上运行，无需购买云服务器，也不要求开放公网端口。
它的核心工作方式是：事件进入后按规则派给 Agent；Agent 完成一轮便退出；只有遇到删除数据、重启服务、花钱或对外发送消息等不确定操作时，系统才通过通知卡片请你决策。你回答后，它会续接原来的会话并完成剩余任务。
核心特性
- 本地运行：一台 macOS 或 Linux 电脑即可部署，不需要单独的云端后台。
- Agent 接入简单：能够接收提示词并输出最终回复的命令行工具，都可以通过通用命令插件接入。
- 挂起期间零 Agent 消耗：等待人工答复时，Agent 进程直接退出，不继续消耗 Token；等待状态保存在数据库中。
- 规则驱动：通过
rules.json描述什么事件交给哪个 Agent，以及在哪个目录执行，无需编写胶水代码。 - 按需通知：支持桌面通知、飞书，以及钉钉、企微、Slack、Discord Webhook 模板。
- 会话续接：人工回答后，可接着原有对话继续处理，而不是从头重复任务。
- 可追溯：状态由只追加日志计算得到，可以查询每一轮任务的触发原因与处理结果。
- 插件化：事件来源、Agent、通知通道和 CI/CD 交付流程均可扩展或替换。
安装前准备
开始前，请确认系统为 macOS 或 Linux，并已安装以下工具：
- Node 24
- Git
- curl
- 至少一个已安装并登录的命令行 Agent，例如 Claude Code 或 Codex
安装和本地试跑不需要 GitHub 账号。Agent Autoloop 会直接调用你本机已有的命令行工具，不读取或转存这些工具的账号凭据。
第一步：安装 Agent Autoloop
在终端执行官方安装脚本：
curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh如果希望先检查安装细节，可以阅读项目的 安装说明。README 也建议将这份说明交给本机 Agent，由它协助完成安装。
第二步：完成首次交互试跑
安装完成后，执行：
agent-autoloop try这个命令会使用本机 Agent 演示完整流程：发送任务、Agent 提问、退出等待、接收你的决定，然后续接会话完成任务。
试跑过程中，你会看到类似下面的结果：
事件发出去了，Agent 开始干活……
Agent 结束了这一轮，问了你一个问题。它现在不占进程、不花 Token。
【等你决定】#1 试跑：选一个颜色
这是一次试跑，选哪个都行。
1. 蓝色
2. 绿色在交互式终端中，可以直接输入选项数字并回车。在非交互式终端中，可显式回答第 1 张卡片，并选择第 2 个选项：
agent-autoloop answer 1 2随后查询整体状态：
agent-autoloop status如果流程正常，你会看到 Agent 续接原会话并确认选择结果。状态命令还会显示当天及最近 7 天的运行轮数、Token 和费用统计。
第三步：理解任务如何自动运转
- 事件进入：定时任务、GitHub Issue 或业务系统错误被转换为标准事件。
- 规则匹配：内核根据本机规则决定使用哪个 Agent，以及在哪个工作目录执行。
- 执行一轮：Agent 处理任务，并在最后一条回复中交代结果，随后进程退出。
- 必要时请示：如果存在需要人工判断的操作，中台发送通知卡片并保存等待状态。
- 回答后续接：你提交选择后，系统恢复原有对话并继续完成任务。
对于无需人工参与的任务，Agent 可以直接结束，也可以预约稍后复查。系统还会合并同一件事在排队期间收到的新消息，以一轮任务集中处理。
第四步：编写第一条自动化规则
日常配置位于：
~/.agent-autoloop/rules.json每条规则至少需要说明何时触发、交给谁以及在哪个目录工作。其中 to 必须引用配置中 agents 已存在的名称。
示例：每天早上 9 点生成早报
{
"name": "早报",
"when": { "cron": "0 9 * * *" },
"to": "codex",
"cwd": "~/notes",
"prompt": "整理昨天的笔记和提交，写今天的早报。"
}这条规则会每天 9 点把任务交给名为 codex 的 Agent，并让它在 ~/notes 目录中整理笔记和 Git 提交。
示例：处理新建的 GitHub Issue
外部事件规则的结构类似，但需要先在 sources 中登记对应事件来源。以下规则监听 GitHub 的 issues.opened 事件：
{
"name": "处理 issue",
"when": {
"source": "github",
"types": ["issues.opened"]
},
"to": "codex",
"cwd": "~/code/app",
"skill": "handle-issue",
"parallel": 3
}skill 指定处理任务所需的 Skill，parallel 将并行数设置为 3。事件来源的登记方式应按照项目的配置手册完成。
规则保存后会在几秒内自动生效。建议立即运行检查：
agent-autoloop check如果新规则存在错误，系统会继续使用旧规则运行，并通过卡片提示具体问题，避免错误配置直接中断现有自动化。
第五步：让 Agent 请求人工决策
Agent Autoloop 对 Agent 的主要约定是：在最后一条回复中交代结果。如果任务已经完成，正常输出结论即可；如果需要人工选择，则在回复末尾加入一个 agent-autoloop 回执代码块。
订单已经核对完毕，库存充足。
```agent-autoloop
{
"ask": [{
"title": "怎么发货？",
"text": "两种方式今天都能发出。",
"options": ["快递", "自提"],
"key": "shipping"
}]
}
```这里的 ask 会生成一张包含两个选项的决策卡片。除了提问，回执还支持以下动作：
notice：发送通知。resolve：关闭已经解决的卡片。later：预约未来某个时间复查。events：触发新的事件。
如果 Agent 输出的 JSON 有误，中台只会要求它在原会话中重写最后一段回执，不会重新执行已经完成的业务操作。如果重写仍然失败，系统会保留原始结论，并通知你回执没有生效。
使用现成场景模板
项目提供多套包含规则、任务 Skill 和启用说明的模板，可作为实际配置的起点：
- 每日早报：整理本地笔记和 Git 提交，并写入按日期命名的文件。
- GitHub Issue 跟进：定期检查新 Issue，在本地修改代码并通知你查看；默认不提交、不推送，也不回复 Issue。
- 线上告警排查：接收错误并对照代码分析原因，遇到重启操作时先请求批准。
- 用户反馈处理：检查反馈状态、修复问题、核实交付并准备回复，需要决策时通过飞书询问。
- 网站巡检：定期检查状态和关键内容，避免持续异常造成重复通知，并在恢复后更新原卡片。
- 飞书周报与业务摘要：按权限读取汇报和指定表格，将完整摘要保存在本地，只向飞书发送简短内容。
- PR 自动交付：从代码审查开始，等待 CI、合并 PR、等待部署，最后核对线上版本。
启用模板时，需要把任务 Skill 放入所用 Agent 的 skills 目录，将示例规则合并到 ~/.agent-autoloop/rules.json，替换路径和电脑名，然后执行 agent-autoloop check。
README 特别说明：反馈处理、网站巡检和飞书摘要中的样例数据是虚构的，相关脚本与回执只通过本地 HTTP 和模拟飞书 CLI 验证，尚未在真实账号上完成完整业务实测。
接入不同的 Agent 与通知通道
内置 Agent 插件
项目内置 Claude Code、Codex、ACP 和通用命令插件。Claude Code、Codex 以及官方 Codex ACP 适配器已经完成多轮问答和跨进程会话续接测试。
通过通用命令接入其他 Agent
对于其他命令行 Agent，可以设置 use: "command" 并提供命令数组。占位符 {prompt} 会作为独立参数传入，不会被当作 Shell 代码执行。
README 根据各工具官方文档列出了 DeepSeek Harness、pi、OpenClaw、Hermes、Cursor 和 WorkBuddy／CodeBuddy 等命令示例，但同时明确说明这些命令尚未逐个实测。因此，正式使用前应先在隔离目录中验证参数、输出格式和会话行为。
安装第三方插件
第三方插件可通过 Git 地址安装：
agent-autoloop add <git 地址>如果需要自行开发插件，可以从项目提供的最小 Agent、通道和事件插件模板开始，并参考插件开发说明。
选择通知通道
桌面通知默认开启。飞书已经实测发送、按钮回调和卡片更新。钉钉、企微、Slack 与 Discord 使用 Webhook 模板，目前只在本地模拟服务上验证。
这些文字通道通过回答链接提交决策，因此必须将 hub.publicUrl 配置为手机或电脑能够访问的地址。是否需要公网访问取决于你选择的通道和网络环境，而不是基础本地运行本身。
高级技巧与可靠性设计
查询一轮任务为什么执行
使用 why 命令查看指定轮次的触发事件、规则版本、领取者与最终结果：
agent-autoloop why 1这对于排查错误规则、重复事件或意外派活尤其有用。
理解四项内核机制
- 挂起零消耗：等待人工回答时，Agent 进程退出，状态留在数据库中；回答后再恢复原会话。
- 事件溯源：所有状态从只追加日志计算，日志和索引在同一事务中写入磁盘，格式变化后可以从日志重建状态。
- 指令与数据分离：Issue 标题和正文等外部内容作为资料保存，不直接拼入提示词。Agent、工作目录和权限只由本机规则决定；事件中的
cwd、agent、access字段会被拒收。 - 跳数熔断：Agent 触发的新事件会累加层数，人工提问和定时复查不会重置。超过 8 层后只记录而不继续派活，并向用户发送卡片。
运行模拟与性能测试
进入程序目录：
cd ~/.agent-autoloop/app随后可以运行 README 提供的验证命令：
node sim/random.ts 24301 200000
node sim/crash.ts 1000 12648430
npm run benchmark第一条命令模拟断网、丢包、崩溃和重复提交；第二条命令通过反复强杀进程检查已确认记录是否丢失；第三条命令运行性能基准。README 中的达标线基于 Apple M5 Pro、24 GB 内存和 Node 24.21.0，其他机器可能因硬件差异显示未达标。
随着历史日志增长，状态汇总会变慢，日志和索引也会持续占用磁盘。数据格式发生变化后的首次启动可能需要全量重建，因此长期运行时应关注磁盘空间和启动耗时。
交付流水线的使用边界
Agent Autoloop 提供 delivery 插件。给 GitHub PR 添加 deliver 标签后，可以按“审查代码、等待 CI、合并 PR、等待部署、核对线上版本”的顺序持续跟进。
审查与交付配置只从 main 分支读取，并且不会在接单电脑上检出或运行 PR 中的代码。排队、并发与重试沿用同一套内核机制。正式启用前，应结合仓库权限和发布流程阅读安全边界说明。
用量与合规建议
模型调用消耗计入你自己的账号，额度和使用范围受对应模型厂商服务条款约束。README 提醒，高频自动化场景通常更适合使用 API Key；个人订阅额度主要面向日常人工交互。如果使用该工具对外提供服务，应采用 API Key，并自行确认服务条款与合规要求。
Agent Autoloop 是独立开源项目，与 Anthropic、OpenAI 等模型厂商没有隶属或背书关系。
结语
Agent Autoloop 的重点不是让 Agent 永久在线，而是让任务能够可靠地暂停、等待和续接。你可以先用 agent-autoloop try 验证交互闭环，再从每日早报或 GitHub Issue 模板开始编写规则。确认本地流程稳定后，再逐步接入飞书、Webhook、外部事件和 PR 交付流水线。