连接 AI 客户端 · 群历帮助文档

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

概述

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

https://qunli.co/mcp

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

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

适合做什么

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

开始之前

创建一个机器人：在「设置 → 我的机器人」里点击「创建机器人」。见创建与管理机器人。
把它加进项目：它只能看到自己是成员的项目（「团队里所有人可见」的项目除外）。
准备好浏览器：授权时要在浏览器里登录群历。客户端运行在没有浏览器的服务器或 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 客户端」，页面上写着「某某应用请求以机器人身份访问群历」：

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

授权页的每个细节、授权之后它能做什么、怎么撤销，见授权、撤销与安全。

授权页：上方是「Claude Code 请求以机器人身份访问群历」和「授权后返回本机应用」，中间选择团队和机器人，底部是「拒绝」和「批准」

让它定时工作

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

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

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

Claude Code

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

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

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

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

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

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

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

用 API Key：

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 里的配置。添加服务器并授权：

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

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

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

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

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

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

ChatGPT

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

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

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

Hermes

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

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

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

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，改用请求头：

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

OpenClaw

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

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

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

openclaw mcp doctor qunli --probe

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

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

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

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，见开发者文档。

常见问题

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

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

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

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

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

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

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

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

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

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

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

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