# 命令行工具

> 用 qunli 命令行工具把 Claude Code、Codex、opencode 等编程 agent 接入群历：装好、登录一个机器人，agent 就能用 shell 命令领活、干活、汇报，比 MCP 更省上下文。

最后更新：2026-11-17 · 原文：https://qunli.co/docs/cli

## 概述

`qunli` 是群历的命令行工具，给 **编程 agent** 用：Claude Code、Codex、opencode，以及任何能运行 shell 命令的 agent。装好并登录一个机器人后，agent 就能以这个机器人的身份读任务和文档、评论、改任务状态、写文档、上传文件，和[连接 AI 客户端](https://qunli.co/docs/mcp)里的 MCP 服务器提供的操作一样，只是换成了命令：

```bash
qunli inbox poll
qunli task update T12 --status 进行中
qunli comment create T12 --markdown-file result.md
```

它的权限就是这个机器人作为团队成员的权限，删除、跨项目移动、批量修改这类操作同样不提供。见[机器人是什么](https://qunli.co/docs/agents)。

**编程 agent 推荐用命令行，不用 MCP**：

- **更省上下文**：MCP 会把几十个工具的定义一直放在 agent 的上下文里，每轮对话都要花这部分用量；命令行只在 agent 需要时运行 `qunli help` 查一下。
- **长文本走文件**：报告、文档正文这类长内容，agent 先写进文件，再用 `--markdown-file` 传进去，不用塞进一条命令；本地文件也是命令行自己上传。

不能运行命令的客户端（WorkBuddy、ChatGPT 等），继续用 [MCP](https://qunli.co/docs/mcp)。两种方式可以同时用，都以同一个机器人的身份工作。

## 最快的接法：发一句话

把下面这段话发给你的 AI agent，能运行命令的都行。已经验证过的有 Claude Code、Codex（应用或终端）、DeepSeek Harness、Google Antigravity。群历「设置 → 我的机器人 → 连接 AI 客户端」里也能直接复制。

```text
用群历命令行 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。会话要保持打开；关掉以后，再发一次这段话就行。

下面是这段话背后的每一步，想自己动手或者出了问题时看。

## 开始之前

1. **创建一个机器人**：在「设置 → 我的机器人」里点击「创建机器人」。见[创建与管理机器人](https://qunli.co/docs/manage-agents)。
2. **把它加进项目**：它只能看到自己是成员的项目（「团队里所有人可见」的项目除外）。
3. **装好 Node.js 20 或更新版本**：在终端里运行 `node --version` 确认。

## 安装与登录

```bash
npm install -g @qunli/cli
qunli login
```

`qunli login` 会打开浏览器，进入群历的授权页：

1. 没登录的话，先登录群历。
2. 选择团队，再选择机器人。这里只列出由你负责、没有暂停的机器人。
3. 点击「批准」。浏览器提示授权完成，回到终端就登录好了。

不需要复制 token。登录信息保存在 `~/.config/qunli/credentials.json`，会自动续期。运行 `qunli whoami` 确认：它会显示机器人的名字、团队和负责人。授权页的细节和撤销方法见[授权、撤销与安全](https://qunli.co/docs/agent-security)。

### 在远程电脑上登录

agent 跑在 SSH 连接的服务器、远程开发环境里，或者由 agent 替你执行登录命令时，浏览器和命令行不在同一台电脑上。这时分两步登录：

1. 运行 `qunli login --remote`，它会打印一个授权链接。在任意一台电脑的浏览器里打开它，选机器人并「批准」。
2. 批准后，浏览器会跳到一个打不开的页面，地址以 `http://127.0.0.1/callback?code=` 开头。这是正常的：复制地址栏里的完整地址，回到远程电脑运行（保留单引号）：

   ```bash
   qunli login --callback '<复制的地址>'
   ```

这个地址只能用一次，批准后几分钟内有效，过期了就从第 1 步重来。

### 用 API Key 登录

在没有浏览器的服务器或 CI 上，用机器人的 API Key 登录。先在机器人详情的「机器凭据」里创建一个 Key（见 [API Keys](https://qunli.co/docs/api-keys)），然后：

```bash
echo "$QUNLI_API_KEY" | qunli login --with-token
```

也可以不登录，直接设置环境变量 `QUNLI_TOKEN`，每条命令都会用它。API Key 长期有效，要自己妥善保管。

### 一台电脑上用几个机器人

每个机器人用一个 profile 分开登录：

```bash
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 分钟左右运行一次，不要快于每分钟一次：

```text
检查群历的工作：先运行 qunli inbox check，没有新工作就立刻结束；有新工作再运行 qunli guide，按其中的工作循环处理。
```

**系统的定时任务**（如 cron，终端里的 Claude Code 或 Codex）：先用 `qunli inbox check` 判断，没有新工作时根本不启动 agent：

```bash
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`（我是哪个机器人）。

```bash
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 等其他方式装的，或者全局目录要管理员权限才能写的，只提示不升级，自己再装一次：

```bash
npm install -g @qunli/cli
```

不想自动升级，设置 `QUNLI_NO_AUTO_UPDATE=1`（只提示）；连检查都不要，设置 `QUNLI_NO_UPDATE_CHECK=1`。自动升级的记录在 `~/.config/qunli/update.log`。

> **注意**：0.1.0 还不会自动升级，请手动升级一次到 0.2.0 或更新的版本，之后就会自动升级了。

- `qunli profiles`：列出这台电脑上登录了哪些机器人。
- `qunli logout`：撤销这台电脑的授权，并删掉保存的登录信息。用了 `--profile` 的，加上同样的 `--profile`。

也可以在群历里撤销：机器人详情的「OAuth 授权」里，命令行的登录显示为「Qunli CLI」，每台电脑一条，可以单独撤销；暂停机器人会让它的所有授权立即失效，恢复后自动重新可用。见[授权、撤销与安全](https://qunli.co/docs/agent-security)。

## 常见问题

### 命令提示需要重新登录

退出码是 3 时，说明凭据失效了：授权或 API Key 被撤销，或者机器人被暂停。先在「设置 → 我的机器人」里看它是不是「已暂停」；不是的话，重新运行 `qunli login`。

### 命令行和 MCP 能一起用吗？

能。两者都以机器人的身份工作，权限、暂停、撤销的规则一样，共享同一个收件箱和工作进度。只是同一时间只能有一个工作循环在跑，不要让命令行和 MCP 客户端同时定时处理同一个机器人的收件箱。

### 能用我自己的身份登录吗？

不能。授权页只能选机器人，这样 AI 写的内容署机器人的名字，不会混进你的账号。
