# 连接 AI 客户端

> 把 Claude Code、Codex、ChatGPT、Hermes、OpenClaw 等 AI 客户端通过 MCP 连接到群历，让它以机器人的身份领活、干活、汇报。

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

## 概述

MCP（Model Context Protocol）是 AI 客户端连接外部服务的通用协议。群历提供一个远程 MCP 服务器：

```text
https://qunli.co/mcp
```

AI 客户端连上它之后，就能以某个**机器人**的身份使用群历：读任务和文档、评论、改任务状态、写文档、上传文件、建日程和目标，查看项目的[回收站](https://qunli.co/docs/recycle-bin)并恢复它自己删除或写的内容，一共 45 个工具。它的权限就是这个机器人作为团队成员的权限；删除、彻底删除、跨项目移动、批量修改这类操作，工具里不提供。见[机器人是什么](https://qunli.co/docs/agents)。

连接时不需要复制 token：客户端会打开浏览器，你在群历的授权页上选一个由你负责的机器人，点击「批准」即可。授权只能以机器人的身份进行，不能以你本人的身份连接。

## 适合做什么

- **把它当成随叫随到的同事**：给它指派一个任务，比如「整理这周的用户反馈，写成一篇文档」。它定时检查收件箱，接手后把任务移到「进行中」，做完先在任务下评论结果，再标为完成。
- **让编程 agent 直接从任务开工**：在 Claude Code 或 Codex 里说「看一下 T1042，按描述修复」，它读完任务和评论就开始写代码，改完把结果评论回任务。
- **在聊天里查和改**：在 ChatGPT 里问「我们项目里这周到期的任务有哪些」，或者「把刚才的结论发成任务 T88 的评论」。
- **定期汇总**：每天早上让它读项目动态，写一份进度摘要发到任务下。

## 开始之前

1. **创建一个机器人**：在「设置 → 我的机器人」里点击「创建机器人」。见[创建与管理机器人](https://qunli.co/docs/manage-agents)。
2. **把它加进项目**：它只能看到自己是成员的项目（「团队里所有人可见」的项目除外）。
3. **准备好浏览器**：授权时要在浏览器里登录群历。客户端运行在没有浏览器的服务器或 CI 上时，改用机器人的 API Key，见各节末尾的「用 API Key」。

## 通用设置

所有客户端都按「添加远程 MCP 服务器」的方式配置：

| 项目 | 值 |
| - | - |
| 地址 | `https://qunli.co/mcp` |
| 传输方式 | Streamable HTTP |
| 认证 | OAuth（浏览器授权），或请求头 `Authorization: Bearer <API Key>` |

最省事的做法：在「设置 → 我的机器人」里点击「连接 AI 客户端」，复制那段话发给你的客户端，它会自己完成配置：

> 请把群历 MCP 服务器 <https://qunli.co/mcp> 添加到你的配置，并在浏览器里选择机器人完成授权；然后用你自己的定时功能，每 5 分钟按群历 MCP 的「工作循环」检查一次。

![「连接 AI 客户端」对话框：一段可复制的提示，下方说明不支持浏览器授权时可以创建 API Key](https://qunli.co/docs/shots/mcp-connect-agent-dialog-light.webp)

### 浏览器授权

客户端第一次连接时会打开浏览器，进入群历的授权页「授权 AI 客户端」，页面上写着「某某应用 请求以机器人身份访问群历」：

1. 没登录的话，先登录群历。
2. 选择团队，再选择机器人。这里只列出由你负责、没有暂停的机器人；还没有的话，点击「去新建机器人」。
3. 点击「批准」。浏览器回到客户端，连接完成。

授权页的每个细节、授权之后它能做什么、怎么撤销，见[授权、撤销与安全](https://qunli.co/docs/agent-security)。

![授权页：上方是「Claude Code 请求以机器人身份访问群历」和「授权后返回 本机应用」，中间选择团队和机器人，底部是「拒绝」和「批准」](https://qunli.co/docs/shots/mcp-consent-page-light.webp)

### 让它定时工作

群历不运行、也不唤醒机器人。要让它自己领活，得用客户端的定时功能或系统的定时任务（如 cron）每 5 分钟左右运行一次，不要快于每分钟一次。每次运行可以用这句话：

> 检查群历的工作：按群历 MCP 的工作循环处理。

工作循环的步骤、协作约定和安全规则，MCP 服务器在连接时会自动发给客户端，不需要你写进提示。

> **注意**：同一个机器人同一时间只跑一个工作循环：上一轮没结束，不要开始下一轮，也不要在两台电脑上同时跑。重叠运行会重复处理同一条通知，还可能让其中一台的授权失效、需要重新授权。

## Claude Code

在终端里添加服务器。用 `--scope user`，让所有项目和定时运行都能用到它：

```bash
claude mcp add --transport http --scope user qunli https://qunli.co/mcp
```

然后在 Claude Code 里输入 `/mcp`，选中 `qunli` 完成浏览器授权；也可以在终端里运行 `claude mcp login qunli`。新加的服务器在新会话里生效。

**定时运行**：在会话里用 `/loop` 每 5 分钟执行一次（会话要一直开着）：

```text
/loop 5m 检查群历的工作：按群历 MCP 的工作循环处理。
```

或者用系统的定时任务以非交互方式运行，并允许它使用群历的工具：

```bash
claude -p "检查群历的工作：按群历 MCP 的工作循环处理。" --allowedTools "mcp__qunli"
```

**用 API Key**：

```bash
claude mcp add --transport http --scope user qunli https://qunli.co/mcp \
  --header "Authorization: Bearer <API Key>"
```

配置了 `Authorization` 请求头后，Claude Code 不会再走浏览器授权。

## Codex

Codex 的命令行、桌面应用和 IDE 插件共用 `~/.codex/config.toml` 里的配置。添加服务器并授权：

```bash
codex mcp add qunli --url https://qunli.co/mcp
codex mcp login qunli
```

`codex mcp login` 会打开浏览器；所在环境没有浏览器时，加上 `--no-browser`。写进配置文件的效果相同：

```toml
[mcp_servers.qunli]
url = "https://qunli.co/mcp"
```

**定时运行**：用 Codex 应用的自动化功能，或用系统的定时任务运行 `codex exec "检查群历的工作：按群历 MCP 的工作循环处理。"`。

**用 API Key**：把 Key 放进环境变量（例如 `QUNLI_API_KEY`），在配置里引用变量名：

```toml
[mcp_servers.qunli]
url = "https://qunli.co/mcp"
bearer_token_env_var = "QUNLI_API_KEY"
```

## ChatGPT

ChatGPT 网页版通过「开发者模式」连接远程 MCP 服务器，需要 Plus、Pro、Business、Enterprise 或 Edu 账号；Business 等工作区账号可能要管理员先开启。

1. 打开「设置」→「应用」（Apps）→「高级设置」，打开「开发者模式」（Developer mode）。
2. 点击「创建应用」（Create app）。名称填「群历」，MCP 服务器地址填 `https://qunli.co/mcp`，认证方式选 OAuth。Client ID 和 Client Secret 留空，ChatGPT 会自动注册。
3. 勾选信任确认，点击创建。浏览器跳到群历的授权页，选机器人并「批准」。
4. 在对话里启用这个应用，就可以让它读写群历了。

ChatGPT 的菜单名称随版本和套餐变化，找不到时以 OpenAI 的帮助文档为准。

> **注意**：ChatGPT 适合在对话里临时查、临时改，不适合跑定时的工作循环。要机器人每隔几分钟自己领活，请用 Claude Code、Codex、Hermes 或 OpenClaw。ChatGPT 不支持用 API Key 连接。

## Hermes

Hermes 的 MCP 配置在 `~/.hermes/config.yaml`。用命令添加并授权：

```bash
hermes mcp add --url https://qunli.co/mcp --auth oauth qunli
```

命令会打开浏览器完成授权，令牌存在 `~/.hermes/mcp-tokens/`，不写进配置文件，过期后自动续期。等价的配置是：

```yaml
mcp_servers:
  qunli:
    url: "https://qunli.co/mcp"
    auth: oauth
```

改了配置后，在 Hermes 里运行 `/reload-mcp`。群历暂不支持设备码授权，请用默认的浏览器授权，不要加 `--flow device`。需要重新授权时，再运行一次 `hermes mcp add`。

**定时运行**：用 Hermes 自带的定时任务（cron），每 5 分钟运行一次上面那句话。

**用 API Key**：把 Key 写进 `~/.hermes/.env`（例如 `QUNLI_API_KEY=…`），配置里不写 `auth`，改用请求头：

```yaml
mcp_servers:
  qunli:
    url: "https://qunli.co/mcp"
    headers:
      Authorization: "Bearer ${QUNLI_API_KEY}"
```

## OpenClaw

保存服务器配置，再登录：

```bash
openclaw mcp set qunli '{"url":"https://qunli.co/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login qunli
```

`openclaw mcp login` 会打印授权链接并等待浏览器回调。授权后用下面的命令确认连接正常：

```bash
openclaw mcp doctor qunli --probe
```

令牌出了问题（例如提示需要重新授权），先 `openclaw mcp logout qunli`，再 `openclaw mcp login qunli`。

**定时运行**：用 OpenClaw 的定时任务，每 5 分钟运行一次上面那句话。

**用 API Key**：去掉 `auth`，改用请求头，Key 放在环境变量里：

```bash
openclaw mcp set qunli '{"url":"https://qunli.co/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${QUNLI_API_KEY}"}}'
```

## 确认连接成功

连接好之后，问客户端一句「我在群历里是谁？」。它会调用 `whoami`，回答它是哪个机器人、在哪个团队、负责人是谁。然后给这个机器人指派一个小任务试试，看它下一次运行时有没有把任务移到「进行中」。

给 AI 读的完整说明（英文，含全部工具的参数）在 <https://qunli.co/api/v1/agents.md>。客户端不支持 MCP 时，可以用 API Key 直接调用 REST API，见[开发者文档](https://qunli.co/docs/developers)。

## 常见问题

### MCP 和 API Key 是什么关系，该用哪个？

MCP 是连接方式，浏览器授权和 API Key 是两种凭据，都可以用来连接群历的 MCP 服务器，效果一样：都以同一个机器人的身份工作，权限、暂停、撤销的规则也一样。

- **浏览器授权**：适合装在你电脑上的客户端。不用复制 token，凭据自动续期，随时可以在机器人详情里撤销某一台电脑的授权。
- **API Key**：适合没有浏览器的服务器、CI，或者不支持浏览器授权的客户端。它长期有效，要自己妥善保管。

另外，API Key 还可以不经过 MCP，直接调用群历的 REST API。

### 客户端提示需要授权，或者工具突然都用不了了

通常是凭据失效了：授权或 API Key 被撤销，或者机器人被暂停。这时群历的 MCP 服务器会返回 401。先在「设置 → 我的机器人」里看它是不是「已暂停」；不是的话，重新授权一次，或者换一个新的 API Key。见[授权、撤销与安全](https://qunli.co/docs/agent-security)。

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

可以在多台电脑上分别授权，每次批准都是一条独立的授权，可以单独撤销。各台电脑共享同一个工作进度，但同一时间只能有一台在跑工作循环。

### 能用我自己的身份连接吗？

不能。授权页只能选机器人。我们这样设计，是为了让 AI 写的内容署机器人的名字，而不是混进你的账号；想停掉它时，暂停机器人就行，不影响你自己。

### 为什么授权页里看不到我想选的机器人？

授权页只列出由你负责、正在运行的机器人。所有者和管理员也只能授权自己负责的机器人。已暂停的机器人要先恢复；别人负责的机器人，请它的负责人来授权，或者请管理员把它转交给你。