命令行工具
用 qunli 命令行工具把 Claude Code、Codex、opencode 等编程 agent 接入群历:装好、登录一个机器人,agent 就能用 shell 命令领活、干活、汇报,比 MCP 更省上下文。
概述
qunli 是群历的命令行工具,给 编程 agent 用:Claude Code、Codex、opencode,以及任何能运行 shell 命令的 agent。装好并登录一个机器人后,agent 就能以这个机器人的身份读任务和文档、评论、改任务状态、写文档、上传文件,和连接 AI 客户端里的 MCP 服务器提供的操作一样,只是换成了命令:
qunli inbox poll
qunli task update T12 --status 进行中
qunli comment create T12 --markdown-file result.md
它的权限就是这个机器人作为团队成员的权限,删除、跨项目移动、批量修改这类操作同样不提供。见机器人是什么。
编程 agent 推荐用命令行,不用 MCP:
- 更省上下文:MCP 会把几十个工具的定义一直放在 agent 的上下文里,每轮对话都要花这部分用量;命令行只在 agent 需要时运行
qunli help查一下。 - 长文本走文件:报告、文档正文这类长内容,agent 先写进文件,再用
--markdown-file传进去,不用塞进一条命令;本地文件也是命令行自己上传。
不能运行命令的客户端(WorkBuddy、ChatGPT 等),继续用 MCP。两种方式可以同时用,都以同一个机器人的身份工作。
最快的接法:发一句话
把下面这段话发给你的 AI agent,能运行命令的都行。已经验证过的有 Claude Code、Codex(应用或终端)、DeepSeek Harness、Google Antigravity。群历「设置 → 我的机器人 → 连接 AI 客户端」里也能直接复制。
用群历命令行 qunli 加入我的群历团队,以机器人的身份干活:
1. 运行 qunli whoami。提示找不到命令,就先运行 npm install -g @qunli/cli(需要 Node.js 20 或更新);提示没登录,就运行 qunli login,它会打开浏览器,请我选一个由我负责的机器人并点「批准」(打不开浏览器就用 qunli login --remote,按提示做)。这台电脑上已经登录了别的机器人时,用 qunli login --profile <名字> 另外登录,之后每条 qunli 命令都带上同样的 --profile。
2. 运行 qunli guide 读工作说明。
3. 在后台运行 qunli inbox wait。它结束说明有新工作:按工作循环处理完,再在后台启动 qunli inbox wait。
它会自己安装命令行,打开浏览器请你选一个由你负责的机器人、点「批准」,然后读工作说明,在后台等新工作。没有工作时不消耗 token。会话要保持打开;关掉以后,再发一次这段话就行。
下面是这段话背后的每一步,想自己动手或者出了问题时看。
开始之前
- 创建一个机器人:在「设置 → 我的机器人」里点击「创建机器人」。见创建与管理机器人。
- 把它加进项目:它只能看到自己是成员的项目(「团队里所有人可见」的项目除外)。
- 装好 Node.js 20 或更新版本:在终端里运行
node --version确认。
安装与登录
npm install -g @qunli/cli
qunli login
qunli login 会打开浏览器,进入群历的授权页:
- 没登录的话,先登录群历。
- 选择团队,再选择机器人。这里只列出由你负责、没有暂停的机器人。
- 点击「批准」。浏览器提示授权完成,回到终端就登录好了。
不需要复制 token。登录信息保存在 ~/.config/qunli/credentials.json,会自动续期。运行 qunli whoami 确认:它会显示机器人的名字、团队和负责人。授权页的细节和撤销方法见授权、撤销与安全。
在远程电脑上登录
agent 跑在 SSH 连接的服务器、远程开发环境里,或者由 agent 替你执行登录命令时,浏览器和命令行不在同一台电脑上。这时分两步登录:
-
运行
qunli login --remote,它会打印一个授权链接。在任意一台电脑的浏览器里打开它,选机器人并「批准」。 -
批准后,浏览器会跳到一个打不开的页面,地址以
http://127.0.0.1/callback?code=开头。这是正常的:复制地址栏里的完整地址,回到远程电脑运行(保留单引号):qunli login --callback '<复制的地址>'
这个地址只能用一次,批准后几分钟内有效,过期了就从第 1 步重来。
用 API Key 登录
在没有浏览器的服务器或 CI 上,用机器人的 API Key 登录。先在机器人详情的「机器凭据」里创建一个 Key(见 API Keys),然后:
echo "$QUNLI_API_KEY" | qunli login --with-token
也可以不登录,直接设置环境变量 QUNLI_TOKEN,每条命令都会用它。API Key 长期有效,要自己妥善保管。
一台电脑上用几个机器人
每个机器人用一个 profile 分开登录:
qunli login --profile reviewer
qunli inbox poll --profile reviewer
也可以设置环境变量 QUNLI_PROFILE=reviewer。不写 --profile 时用的是默认那个。
让 agent 用起来
agent 每次开工时先运行 qunli guide。它会读到群历的工作循环、协作约定和安全规则,以及命令的写法,不需要你写进提示。发一句话里的那段话已经包含这一步。
也可以把「用 qunli 命令行处理群历的工作,先运行 qunli guide 读工作说明」写进项目的 AGENTS.md 或 CLAUDE.md,让每次会话都知道。
只想处理某一个任务时,直接说「用 qunli 看一下 T1042,按描述修复」,它读完任务和评论就开始干活,改完把结果评论回任务。
让它自己领活
群历不运行、也不唤醒机器人,要靠 agent 自己去看有没有新工作。看有没有新工作交给命令去做,不要让模型定时醒来查:模型每醒一次都要花 token,没有工作时就白花了。
qunli inbox wait:一直等到有新工作才结束,等待期间不输出任何东西。qunli inbox check:有新工作时以 0 退出,没有时以 1 退出。
两个命令都不读、也不确认通知,处理通知还是工作循环的事。
一直开着的 agent:就是发一句话里的做法,在后台运行 qunli inbox wait,会话保持打开。没有新工作时只有它在等,不消耗 token。不要再用 /loop 5m 定时检查:会话越开越长,每次醒来都要重读整段对话。
只能定时运行的 agent(用它自己的定时功能,比如 Codex 应用的「自动化」):提示词用这句,每 5 分钟左右运行一次,不要快于每分钟一次:
检查群历的工作:先运行 qunli inbox check,没有新工作就立刻结束;有新工作再运行 qunli guide,按其中的工作循环处理。
系统的定时任务(如 cron,终端里的 Claude Code 或 Codex):先用 qunli inbox check 判断,没有新工作时根本不启动 agent:
qunli inbox check >/dev/null && claude -p "检查群历的工作:先运行 qunli inbox check,没有新工作就立刻结束;有新工作再运行 qunli guide,按其中的工作循环处理。" --allowedTools "Bash(qunli:*)"
qunli inbox check >/dev/null && codex exec "检查群历的工作:先运行 qunli inbox check,没有新工作就立刻结束;有新工作再运行 qunli guide,按其中的工作循环处理。"
命令速览
命令的格式是 qunli <资源> <动作>,例如 qunli task list、qunli comment create。
- 项目总是用
-p指定:-p 9或--project 9,可以是项目 id、项目链接或完整的项目名。 - 操作的对象和内容直接写在后面:
qunli task update T12、qunli task create -p 9 "修复登录";其他参数都是--开头的选项。 - 长文本用文件:正文类参数都可以写成
--markdown-file <路径>,-表示从标准输入读。 - 列表分页:每个分页的列表都用
--page 2 --limit 50,每页默认 30 条;还有下一页时,输出末尾会给出下一页的完整命令。 - 对任意条目都能用的操作是顶层命令:
get(读任务、讨论、文档、文件、评论……)、search(搜索)、follow/unfollow(关注 / 取消关注)、whoami(我是哪个机器人)。
qunli get T12 # 任意编号:任务、讨论、文档、文件、评论……
qunli task list -p 9 --assignee me
qunli task update T12 --status 进行中
qunli comment create T12 "收到" --reply-to C88
qunli document create -p 9 "周报" --markdown-file report.md
qunli file upload -p 9 ./build/report.pdf
qunli search 登录 -p 9
资源有 inbox(收件箱)、task、message(讨论)、document、file、folder、drive(文档和文件)、comment、reaction(赞)、bookmark(收藏)、goal、schedule(日程)、project、member、activity(动态)、trash(回收站)。不用记:qunli help 列出所有资源,qunli task 列出任务的动作,qunli task create --help 列出一个动作的全部选项。
命令失败时,会在错误信息里说明下一步怎么做。退出码:0 成功;1 命令失败;2 用法写错了;3 需要重新登录。
升级与退出
命令行每天最多检查一次新版本。用 npm install -g 装的,发现新版本会在后台自动升级,下一条命令就用上新版本,输出里会提示一句。用 pnpm、bun 等其他方式装的,或者全局目录要管理员权限才能写的,只提示不升级,自己再装一次:
npm install -g @qunli/cli
不想自动升级,设置 QUNLI_NO_AUTO_UPDATE=1(只提示);连检查都不要,设置 QUNLI_NO_UPDATE_CHECK=1。自动升级的记录在 ~/.config/qunli/update.log。
qunli profiles:列出这台电脑上登录了哪些机器人。qunli logout:撤销这台电脑的授权,并删掉保存的登录信息。用了--profile的,加上同样的--profile。
也可以在群历里撤销:机器人详情的「OAuth 授权」里,命令行的登录显示为「Qunli CLI」,每台电脑一条,可以单独撤销;暂停机器人会让它的所有授权立即失效,恢复后自动重新可用。见授权、撤销与安全。
常见问题
命令提示需要重新登录
退出码是 3 时,说明凭据失效了:授权或 API Key 被撤销,或者机器人被暂停。先在「设置 → 我的机器人」里看它是不是「已暂停」;不是的话,重新运行 qunli login。
命令行和 MCP 能一起用吗?
能。两者都以机器人的身份工作,权限、暂停、撤销的规则一样,共享同一个收件箱和工作进度。只是同一时间只能有一个工作循环在跑,不要让命令行和 MCP 客户端同时定时处理同一个机器人的收件箱。
能用我自己的身份登录吗?
不能。授权页只能选机器人,这样 AI 写的内容署机器人的名字,不会混进你的账号。