把 agent-autoloop 装在 Mac 上:用本机 Node 实跑一次「接活—提问—拍板—接着干」,再用 cpolar 把它的状态页开给不在工位的自己

Agent 跑完一轮就问你一句,人一走它就干等:把 agent-autoloop 装在 Mac 上,用本机 Node 实跑一次「接活---提问---拍板---接着干」,再用 cpolar 把它的状态页开给不在工位的自己

命令行 Agent 最别扭的地方,不在它会不会写代码,而在它总在你最不方便的时候停下来。

我在 Mac mini 上跑 Codex,让它整理提交记录、顺手把几个小需求改掉。它干到一半,弹出一句「这个分支要不要合到 main」。我那时候正在地铁上,手机里只能看到通知,等回到工位坐下,半小时过去了,Agent 的终端早就安静地停在那儿,一行日志都没多。

这就是「干等」------人不在,进程占着,Token 也不花,但活也不会往前走。

这篇就干一件事:把 agent-autoloop 装在本机,用 Node 26 的运行时真实跑一遍「接活 → 提问 → 拍板 → 接着干」,然后给它补一个它自己没有的状态页,最后用 cpolar 把这个页面开到手机上。

1 先说清楚:agent-autoloop 在这篇里负责什么

它不是一个聊天工具,也不是又一个 Agent。它的定位是「自动化中台」,README 里写得挺直白:让命令行 Agent 在后台自己接活、自己跟进到底,平时不烦你,遇到拿不准的事才发一张卡片找你拍板。

它有四个机制,这篇里真正用到的是三个:

  • 挂起零消耗:等你拍板的时候,Agent 进程直接退出,等待状态存进本地数据库。你三天没回,这三天就没有 Agent 进程在跑,也不花 Token;你一回答,它接上原来的会话继续干。
  • 事件溯源:所有状态都从一条只追加的日志算出来,写完才应答。所以状态页读出来的东西和命令行看到的是同一份。
  • 指令数据分离 :用哪个 Agent、在哪个目录、给什么权限,只由本机 rules.json 决定。别人写在 Issue 里的字进不了提示词。

关键点在这里:这个项目本身没有网页界面 。作者的选择是,需要你拍板就推到飞书、桌面通知这类通道,想看全局就敲命令行。它在 skills/agent-autoloop/SKILL.md 里写得很清楚------「用户想要一个页面看全局,就替他写一个:读 GET /v1/state」。

所以这篇的后半段,就是我们自己写那个页面,再通过 cpolar 让它能在外网打开。这一步不是硬加的,是它自己留的口子。

2 环境准备:Node、Git、一个已经登录的 Agent

先别急着下安装脚本,两个前置条件不满足,后面全卡在这儿。

2.1 检查 Node 版本

项目 package.json 里写的是 "node": ">=24"。我这台机器是 Homebrew 装的 Node,版本如下:

bash 复制代码
node --version
text 复制代码
v26.8.1

版本比 24 高就行,不需要 Docker、不需要 JDK、不需要 Maven。这一点挺省事------很多同类项目要先起一个 Postgres 或者 Redis,它连运行时依赖都是 0。

如果你机器上是 Homebrew 的 node@24,路径默认不进 PATH,记得先 export PATH="$(brew --prefix node@24)/bin:$PATH"。这一步别跳过,不然 node --version 报的是另一套老版本,后面跑类型测试会莫名其妙不认 TS 文件。

2.2 确认 Agent 已经登录

中台不保存也碰不到你的登录凭据,它只负责启动你本机已经登录好的命令行工具。所以先用你平时的方式确认一下,比如:

bash 复制代码
codex --version

能正常打出复合版本号,说明登录态在,可以往下走。Claude Code 同理,换成 claude --version。

2.3 顺手把源码拉下来

安装脚本会装 Release 版本。但我建议同时把源码拉一份到 /tmp,一方面可以看它到底怎么跑,另一方面后面验证协议用得上。

bash 复制代码
cd /tmp && mkdir -p al-probe && cd al-probe
curl -sL https://codeload.github.com/KKKKhazix/agent-autoloop/tar.gz/refs/heads/main -o al.tgz
tar xzf al.tgz && ls agent-autoloop-main

看到 kernel/、host/、cli/、tests/ 这些目录就对了。

3 安装和初始化

3.1 一行脚本装好

macOS 用官方 install.sh:

bash 复制代码
curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh

它会装最新的 Release,程序落在 ~/.agent-autoloop/app,配置和记录留在 ~/.agent-autoloop。命令优先放进 PATH 里已经可写的 ~/.local/bin,不需要 sudo,也不会覆盖你已有的同名命令。

装完先确认一下命令在不在:

bash 复制代码
agent-autoloop --version

如果提示 command not found,多半是 ~/.local/bin 没进 PATH。安装器会打印一条完整路径,用那条路径也能跑,先别急着改 shell 配置。

图1:--version 有输出、doctor 里中台和 Agent 都在线,安装这一步就算过了

3.2 初始化:这一步在做配置,不是在跑任务

bash 复制代码
agent-autoloop init --agent codex

不指定 --agent 的话它会自己检测本机装了什么命令行 Agent,第一种作为试跑对象。我指定 codex 是为了让后面演示一致。

这一步会做四件事:生成 ~/.agent-autoloop/config.json、写一份带「试一下」规则的 rules.json、给 worker 和 owner 各生成一个密钥、装上登录后常驻的服务。默认端口是 3350,监听地址是 127.0.0.1:3350------只开本机回环。

这里有个细节要注意 :config.json 里的 owner 那把密钥是后面状态页要用的,别随手贴到群里,也别截图发出去。

3.3 用 doctor 看一眼链路

bash 复制代码
agent-autoloop doctor

它会把中台、Agent、桌面通道的在线情况列出来。桌面通知默认开启,第一次运行时 macOS 会弹权限请求,点允许就行。

如果这一屏显示服务没在跑,先别改配置,直接看 ~/.agent-autoloop 下的日志。最常见的原因是端口被占,换个端口重来即可(init --port 4000)。

4 实跑一次:接活---提问---拍板---接着干

这是全文最核心的一段,建议真跑一遍,后面写状态页才知道每个字段是从哪来的。

4.1 发起试跑

bash 复制代码
agent-autoloop try

它会往中台发一条 try.* 类型的事件,规则「试一下」接住它,交给 Codex 跑一轮。终端里你会先看到:

text 复制代码
事件发出去了,Agent 开始干活......

然后 Codex 跑完,进程退出,终端打印出卡片:

text 复制代码
Agent 结束了这一轮,问了你一个问题。它现在不占进程、不花 Token。

【等你决定】#1 试跑:选一个颜色
这是一次试跑,选哪个都行。
  1. 蓝色
  2. 绿色
回答:agent-autoloop answer 1 <序号>

这一步不是测试而测试。它验证的是「挂起零消耗」这个机制------上一秒还在跑 Agent,下一秒进程没了,等待状态只在数据库里躺着。

如果没看到卡片 ,先检查三处:agent-autoloop doctor 里 Agent 是否在线、rules.json 里「试一下」这条规则的 to 字段是不是写着你真实的 Agent 名字、桌面通知有没有被系统拒掉。

4.2 拍板

bash 复制代码
agent-autoloop answer 1 2

1 是卡片编号,2 是选项序号(绿色)。交互终端里直接输入数字回车也行。

回答不是简单记一笔,它本身就是一条新事件,会被派回给「试一下」这条规则,接着上一次的会话往下跑。

4.3 看它接上了没有

bash 复制代码
agent-autoloop status

正常的话能看到 你选了绿色,试跑通过 这样的结论,外加今天和最近 7 天的轮数、Token 和费用统计。首行是几个计数:等你、在跑、排队、今天做完。

这里有个很实用的技巧:agent-autoloop status --json 输出的是 /v1/state 的原始结构,给脚本和看板用。我们下一步写状态页,读的就是同一份数据。

*图2

:首行四个计数(等你、在跑、排队、今天做完),下面是对应会话的结论和今日统计*

4.4 顺便把「预演」也练熟

改规则之前,用 emit --dry-run 先看会派给谁:

bash 复制代码
agent-autoloop emit try.start --dry-run

它不连中台、不写日志,只按本机现在的 rules.json 告诉你这条事件会落到哪条规则、哪个 Agent。规则写错的时候,这一步比真跑一轮再翻日志快得多。

5 它自己的接口长什么样

写页面前得先知道要读什么。docs/protocol.md 里「本人」一节定义了三个口子:

text 复制代码
GET  /v1/state              Authorization: Bearer <本人的密钥>
POST /v1/cards/56/answer    { "choice": 1 } 或 { "text": "别的想法" }
POST /v1/runs/12/cancel     {}

/v1/state 返回的顶层字段有 seq、totals、cards、agents、channels、lines、runs、spending、now、timezone。对我们做页面来说,够用的就是这几块:

  • cards:现在等你拍板的卡片,带标题、正文、选项
  • totals:运行中、排队、今天做完的数量
  • spending.today:今天的轮数、Token、费用
  • seq:当时的日志序号,想跟着变化就从这个序号接 /v1/stream

还有个 /healthz,返回 {"ok": true},不需要密钥。这个端点后面配 cpolar 的时候很有用------它是判断「隧道通了没有」的最轻的探针。

先手动验一遍鉴权行为,这样后面页面拿 401 的时候你不会慌:

bash 复制代码
curl -s http://127.0.0.1:3350/healthz
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3350/v1/state

第一条应该返回 {"ok":true,"commit":"..."},第二条应该返回 401。401 是对的,说明不带 owner 密钥谁都读不到状态,这个边界必须在。

再带上密钥试一次:

bash 复制代码
OWNER=$(node -e 'console.log(JSON.parse(require("fs").readFileSync(process.env.HOME+"/.agent-autoloop/config.json","utf8")).owner)')
curl -s -H "Authorization: Bearer $OWNER" http://127.0.0.1:3350/v1/state | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);console.log(Object.keys(j).join(", "))})'

应该能把 seq, totals, cards, runs, spending... 这一串字段名打出来。能打出来就说明密钥读对了。

6 写那个 30 行的状态页

中台没有页面,我们自己补一个。页面只做只读展示,回答卡片还是走命令行------这样最省事,也不给公网多开一个写入口。

把下面这段存成 ~/.agent-autoloop/board.mjs:

javascript 复制代码
import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { createServer } from "node:http";

const home = process.env.AGENT_AUTOLOOP_HOME || `${homedir()}/.agent-autoloop`;
const { owner, url } = JSON.parse(readFileSync(`${home}/config.json`, "utf8"));
const port = Number(process.env.BOARD_PORT || 8787);

const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);

const page = async () => {
  const res = await fetch(`${url}/v1/state`, { headers: { authorization: `Bearer ${owner}` } });
  if (!res.ok) return `<h1>读不到状态:${res.status}</h1>`;
  const s = await res.json();
  const cards = s.cards.length
    ? s.cards.map((c) => `<li><b>#${c.id} ${esc(c.title)}</b><br>${esc(c.text)}<br>${(c.options || []).map((o, i) => `<span>${i + 1}. ${esc(o)}</span>`).join(" · ")}</li>`).join("")
    : "<li>没有等你拍板的卡片</li>";
  const t = s.spending?.today ?? {};
  return `<h1>Agent 中台</h1>
    <p>等你 ${s.cards.length} · 在跑 ${s.totals.running} · 排队 ${s.totals.queued} · 今天做完 ${s.totals.doneToday}</p>
    <p>今天 ${t.rounds ?? 0} 轮 · ${t.tokens ?? 0} Token · $${Number(t.cost ?? 0).toFixed(2)}</p>
    <h2>等你拍板</h2><ul>${cards}</ul>
    <p style="color:#888">seq ${s.seq} · ${esc(s.now)} · ${esc(s.timezone)}</p>`;
};

createServer(async (req, res) => {
  if (req.url === "/healthz") return res.end("ok");
  try {
    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
    res.end(`<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><body style="font:16px/1.6 -apple-system,sans-serif;padding:16px">${await page()}</body>`);
  } catch (e) {
    res.writeHead(500).end(`<h1>${esc(e.message)}</h1>`);
  }
}).listen(port, "127.0.0.1", () => console.log(`board on http://127.0.0.1:${port}`));

跑起来:

bash 复制代码
node ~/.agent-autoloop/board.mjs

看到 board on http://127.0.0.1:8787,浏览器打开就能看到今天的轮数和等你拍板的卡片。

三个设计上的取舍,写的时候想清楚了:

  • owner 密钥只在本机进程里用 ,页面本身不带鉴权。所以它只能监听 127.0.0.1,对外暴露要另外想办法------这一步下面用 cpolar 解决。
  • 只读不写 。回答卡片继续走 agent-autoloop answer,页面上不放按钮。少一个写接口,就少一个能被人乱点的地方。
  • 按需拉取,不做长连接 。/v1/state 每次请求都读一次,手机上刷新一下就行,不用处理断线重连。

如果页面显示「读不到状态:401」 ,说明 config.json 里的 owner 读错了。检查一下是不是拿成了 worker.key------worker 那把密钥访问 /v1/state 也是 401,协议里写明了只有本人的密钥能读。

图3:只读状态页,能看到等你拍板的卡片和今天的轮数、Token、费用

7 用 cpolar 把状态页开到手机

到这儿还差最后一步。状态页只听 127.0.0.1,我在工位能看,出了门就打不开。

7.1 macOS 装 cpolar

官方给的是 Homebrew 方式:

bash 复制代码
brew tap probezy/core && brew install cpolar

装完注册成后台服务并启动:

bash 复制代码
sudo cpolar service install
sudo cpolar service start

后台服务要用 sudo,会要你输一次密码。验证服务有没有起来:

bash 复制代码
cpolar version
curl -s http://127.0.0.1:9200 || echo "服务未启动"

9200 是 cpolar 的本地 Web 管理界面。能返回内容就说明服务活着。

7.2 登录并写入 authtoken

去 https://dashboard.cpolar.com/ 注册登录,在后台的验证页面能看到你自己的 authtoken。两条路都能绑:

  • 打开 http://127.0.0.1:9200,在 Web 界面里登录,token 会自动写进配置
  • 命令行手动写:cpolar authtoken <你的 token>

我走的是第二条,因为要写进脚本里复现。

7.3 开一条 HTTP 隧道

bash 复制代码
cpolar http 8787

终端里会打印一段转发信息,其中 Forwarding 那一行就是公网地址,形如 https://xxxx-xx-xx-xx-xx.r4.cpolar.cn。手机上直接打开这个地址,看到的就是刚才那个状态页。

这条命令是前台临时隧道,关掉终端就断。只是想验证链路通不通,用这个就够;要长期挂着,用下面这步。

打不开先查三个地方 :本地 curl http://127.0.0.1:8787/healthz 通不通、curl -s http://127.0.0.1:9200 能不能进管理界面、公网地址有没有写错协议(cpolar 给的是 https,别手动改成 http)。

7.4 要长期可用就把隧道写进配置

免费套餐的公网地址 24 小时内会变,第二天打开旧链接就是 404。手机里存的书签第二天失效,这个体验很差。有两个办法:

一是升级到基础套餐或以上,保留一个固定的二级子域名,地址就固定下来了。二是如果只是自用、地址变了能接受,那就每天重新看一眼 http://127.0.0.1:9200 里的隧道列表,那里有当前地址。

配置持久化这一步要改的是 cpolar.yml,改完执行 sudo cpolar service start 重启服务生效。这一步别在管理界面和配置文件里同时改,容易两边打架。

图4:cpolar 后台的隧道列表,能看到 https 地址和在线状态

7.5 暴露到公网前必须补的几件事

状态页里会出现卡片标题和正文,而卡片正文由 Agent 写,里面常常带着项目名、分支名、报错摘要。所以在把链接发出去之前:

  • 不要把 cpolar 地址贴到群里或公开位置。链接持有即访问,没有账号这道关。
  • 不要同时暴露 3350 。中台的 /v1/state 要 owner 密钥,但没必要把管理接口也开到公网,一个只读页面足够了。
  • 回答卡片继续在本机命令行做。公网那份页面上不放按钮,这个边界一开始就定死了。

如果卡片内容比较敏感,最简单的做法是不把 text 渲染出来,只显示标题和编号,回到电脑前再用 agent-autoloop status 看完整正文。

8 总结

现在这套东西跑起来是这样的:Agent 在后台接活,干完一轮就退出,遇到拿不准的事发一张卡片,然后不占进程地等你;你在手机上打开 cpolar 给的那个地址,一眼看到今天跑了几轮、花多少 Token、哪张卡片在等你;回到工位敲一行 agent-autoloop answer,它接上原来的会话接着把活干完。

关键几步其实就四件事:

  • 用 install.sh 装好、init --agent codex 初始化,确认 doctor 里中台和 Agent 都在线
  • 跑一遍 agent-autoloop try → answer → status,确认「挂起零消耗」和「会话续接」这两个机制真的生效
  • 用 /v1/state 写一个只读状态页,监听 127.0.0.1,owner 密钥只留在本机
  • 用 cpolar http 8787 把它开到公网,长期用就配固定子域名,并且只暴露这一个只读页面

后面能扩的方向不少:读 /v1/stream?after=<seq> 把页面改成实时刷新;多台机器用 join 接到同一个中台,状态页上就能同时看到几台电脑的进度;规则跑多了以后接飞书通道,卡片直接推到手机私聊里,比打开网页更快。

但最省事的其实是第一步------先让它别再干等。这件事今天下午就能做完。

相关推荐
wy_hhxx3 小时前
《Agent设计模式 图解可复用智能体架构》下篇内容整理
人工智能·ai agent
SEO_juper7 小时前
Node.js 全站 SEO 体检报告生成器:一次查完标题、描述、canonical、H1、图片
开发语言·前端·node.js·html·bash
goehou1 天前
healthcheck 配了不生效,depends_on 默认只等容器起来
docker·容器编排·ai agent·healthcheck
木头左1 天前
【Node.js】Markdown 转带图片 Word 文档实战:docx 库转换器设计与 5 个踩坑
node.js·word·markdown·文档自动化
思特奇时空智能1 天前
大规模点要素地图渲染性能优化实践
vue.js·arcgis·性能优化·node.js·html·gis·webgl
吴名氏.1 天前
Java转AI Agent教程(第十五周)政策时效:过期政策不该被召回,也不能被删掉
java·人工智能·python·ai·ai agent
wy_hhxx2 天前
《Agent设计模式 图解可复用智能体架构》上篇内容整理
设计模式·架构·ai agent
cpolar技术支持2 天前
容器数是 6 个、6 个、还是 6 个,可服务早被换掉了:用一个 5.5MB 的 Go 单文件把机器每周的变化记下来,再给它套一层别人看不懂的入口
python·docker·ai·cpolar
w3296362713 天前
飞书接单到月度结算:我用一个 DSH 插件跑通鞋类采购 WMS,附 22 项验收
pdf·node.js·飞书·后端开发·ai agent