版本：8.2.0

个人访问令牌（PAT）使用指南

更新时间：2026-07-27 11:47:06

功能简介

个人访问令牌（Personal Access Token，简称 PAT）是一串以 gdpat_ 开头的密钥字符串，独立于账号密码和浏览器登录状态，用于让程序以你的身份访问观远 BI。

PAT 适用于以下场景：

使用 GuanCLI 命令行工具，如 GuanCLI、GuanVis、GuanETL，读取数据、创建仪表板或创建 ETL。
通过 GuanMCP，让 WorkBuddy、Qoder、Codex、Cursor 等支持 MCP 的 AI 客户端用自然语言查询 BI 数据。
在终端、服务器、CI/CD 或自建脚本中调用 BI 接口，避免在脚本中保存用户密码。
为不同环境或任务配置独立凭证，便于单独授权和撤销。

PAT 只拥有创建时主动勾选的权限，可以随时删除，也可以设置到期日期。PAT 最终可以执行哪些操作，由以下条件共同决定：

当前 BI 环境是否支持 PAT。
PAT 创建时勾选了哪些权限。
目标功能是否已经接入 PAT 鉴权。

PAT 不是管理员登录状态，不会自动获得全部权限。

重要

PAT 代表你的身份。通过 PAT 执行的操作会记录在你的名下，请像保管密码一样保管令牌，不要将其泄露给他人。

使用前提

使用 PAT 前，请确认满足以下条件：

当前环境已开通 CLI 功能。该功能由 License 控制，未开通时请联系观远商务团队。
管理员已在「管理中心 > 用户管理 > CLI 用户」中添加你本人或你所在的用户组。

满足条件后，点击页面右上角头像，菜单中会显示「个人访问令牌」入口。如果未显示该入口，请联系管理员。

说明

如果当前环境暂不支持 PAT，GuanCLI 和本地模式的 GuanMCP 还可以使用账号密码或 uIdToken 鉴权，作为过渡方案。长期使用时推荐 PAT。

创建令牌

点击页面右上角头像，选择「个人访问令牌」。
点击「创建新令牌」。
配置令牌信息。

配置项	说明
令牌名称	必填，支持 1～20 个字符。建议填写具体用途，例如「Cursor 查数」或「CLI 使用」。
到期日期	选填。不填写表示长期有效；到期后令牌自动失效。
快捷授权	按常用 CLI 工具批量勾选权限，不影响已经勾选的其他权限。
权限范围	逐项选择该令牌可以执行的查看、编辑或导出操作。此处的权限来自于当前用户本身具有的权限与 CLI 用户中开通权限的交集。

配置完成后点击「确定」；确定后点击「复制」，立即保存以 gdpat_ 开头的令牌。
重要
- 令牌明文只显示一次。关闭弹窗后，任何人（包括管理员）都无法再次查看。令牌丢失时，请删除原令牌并重新创建。
- 令牌创建后不能修改权限和有效期。如需调整，请创建新令牌并替换原令牌。

在 GuanCLI 中使用

在 GuanCLI 中选择「直接输入 Personal Access Token」即可使用 PAT 登录。交互式登录、非交互式登录、状态验证和常见问题，详见：登录方式。

在 GuanMCP 中使用

GuanMCP 用于连接 AI 客户端和观远 BI。接入后，可以在 AI 客户端中用自然语言搜索 BI 资源、查看指标口径和查询有权限的数据。GuanMCP 聚焦只读查询，不创建、修改或发布 BI 资源。

产品能力介绍详见：GuanMCP 使用指南。

选择连接方式

连接方式	说明	适用场景
本地 stdio	AI 客户端在本机启动 GuanMCP。需要 Node.js 20 或更高版本，并且可以执行 `npx`。	个人使用，推荐 PAT 鉴权。
远程 Streamable HTTP	连接管理员部署的 GuanMCP 服务，地址通常以 `/mcp` 结尾。	客户端无法在本地启动服务，或企业统一接入。

各客户端的支持情况：

客户端	本地 stdio	远程 Streamable HTTP	说明
WorkBuddy	支持	不支持	使用本地 stdio。
Qoder	支持	支持	个人使用优先选择「本地 stdio + PAT」。
Codex	支持	支持	个人使用优先选择「本地 stdio + PAT」。
Cursor	支持	支持	个人使用优先选择「本地 stdio + PAT」。
飞书 Aily	不支持	支持	使用企业邮箱身份映射，不使用个人 PAT，由 Aily 管理员配置。

企业 AI 平台接入

飞书 Aily 等企业 AI 平台采用企业身份映射方式接入 GuanMCP，不使用个人 PAT。具体配置请参考：对接飞书 Aily 使用指南和 GuanMCP 部署指南。

配置本地 stdio

本地模式通过环境变量传入 BI 地址和鉴权信息：

{
  "BI_BASE_URL": "https://bi.example.com",
  "BI_PUBLIC_PATH": "",
  "BI_PAT": "<你的令牌>"
}

BI_BASE_URL：BI 站点根地址。
BI_PUBLIC_PATH：BI 以子路径部署时填写对应路径。例如 BI 地址为 https://bi.example.com/guanbi 时，填写 /guanbi。
BI_PAT：PAT 明文。

如果当前环境暂不支持 PAT，可以改用以下方式之一：

账号密码：BI_LOGIN_DOMAIN、BI_LOGIN_ID、BI_LOGIN_PASSWORD。
uIdToken：BI_UID_TOKEN。

同一服务只配置一种鉴权方式。如果同时配置多种，鉴权优先级为：

PAT > uIdToken > 账号密码

以 Cursor 为例，编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "guanbi": {
      "command": "npx",
      "args": ["-y", "@guandata/guanbi-mcp-server@latest"],
      "env": {
        "BI_BASE_URL": "https://bi.example.com",
        "BI_PUBLIC_PATH": "",
        "BI_PAT": "<你的令牌>"
      }
    }
  }
}

各客户端的配置入口：

客户端	配置入口
WorkBuddy	插件 > MCP 服务器 > 配置 MCP。也可以编辑 `~/.workbuddy/mcp.json` 或项目级 `.workbuddy/mcp.json`。
Qoder	头像 > 个人设置 > MCP > My Servers > Add。Type 选择 `STDIO`，Command 填写 `npx`，Arguments 填写 `-y @guandata/guanbi-mcp-server@latest`。
Codex	Settings > MCP servers，或编辑 `~/.codex/config.toml`。
Cursor	MCP 设置，或编辑 `~/.cursor/mcp.json`。

配置远程 Streamable HTTP

向管理员获取完整的 MCP 地址，在客户端中填写地址并添加以下请求头：

X-Personal-Token: <你的令牌>

以 Cursor 为例：

{
  "mcpServers": {
    "guanbi": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "X-Personal-Token": "<你的令牌>"
      }
    }
  }
}

说明

远程 PAT 鉴权必须使用 X-Personal-Token 请求头，不能使用 Authorization: Bearer <PAT>。

返回 401 时，检查 PAT 和请求头名称。
返回 404 时，确认地址是否完整，远程地址通常以 /mcp 结尾。

验证 GuanMCP 配置

保存配置并重新加载客户端后，建议依次提问：

“当前 GuanMCP 可以使用哪些 BI 能力？”用于确认工具是否可用。
“帮我查找名称中包含『销售』的页面、卡片和数据集。”用于确认能否搜索到有权限的资源。
“查询本周销售额，并说明数据范围和来源。”用于核对数据权限。
询问一个你明确无权访问的资源，确认 GuanMCP 不会返回数据。

说明

PAT 模式当前不提供 ChatBI 工具，这不是安装失败。如需在企业 AI 平台使用 ChatBI，请采用飞书 Aily 等企业身份映射方式。

其他工具也可能因 BI 版本、模块开通情况或权限而不显示。

在自建脚本或程序中使用

在 HTTP 请求中携带以下两个请求头：

curl -H "X-Personal-Token: gdpat_你的令牌" \
     -H "X-Guandata-Client: guancli" \
     "https://你的观远BI地址/..."

请求头	说明
`X-Personal-Token`	PAT 明文。
`X-Guandata-Client`	调用来源。CLI 工具使用 `guancli` 等以 `guan` 开头的值，AI 助手使用 `mcp`。

两个请求头都必须携带，否则请求会被拒绝。

使用限制

PAT 不支持以下操作：

登录观远 BI 网页。
调用使用独立 Public Token 的 Public API。
创建、删除或管理 PAT 本身。
执行“管理员设置”类操作，即使 PAT 所属用户是管理员。

如果短时间内多次使用错误 PAT，系统会临时限流并提示“认证请求过于频繁”。请按照提示等待后重试。

管理令牌

在「个人访问令牌」页面中，可以执行以下操作：

查看列表：查看名称、创建日期、到期日期、状态和最后使用时间；支持按名称搜索和按状态筛选。
查看权限：查看 PAT 当前生效及已经失效的权限。
删除令牌：删除后 PAT 立即失效且无法恢复。怀疑 PAT 泄露时，请立即删除。

权限失效的常见原因：

你的用户权限发生变化，不再拥有对应权限。
管理员收紧全局策略，不再允许向 PAT 授予对应权限。

安全须知

每人最多同时持有 5 个有效 PAT。达到上限后，需要先删除旧令牌。
PAT 与网页登录状态互相独立，修改密码或退出网页登录不会影响 PAT。
账号被停用、锁定或删除后，PAT 立即失效。
不要在 Git 仓库、工单、聊天记录、截图或 CI 日志中保存 PAT 明文。
PAT 通常保存在 ~/.guancli/config.json、~/.cursor/mcp.json 等本地配置文件中。确保文件仅本人可读，不要将配置文件提交到代码仓库。
远程 GuanMCP 地址应使用 HTTPS。
在共享设备上优先使用交互式方式输入 PAT。

权限生效规则

PAT 每次调用时，系统根据以下规则实时计算权限：

PAT 实际权限 = 用户当前权限 ∩ PAT 勾选的权限 ∩ 管理员全局策略

这意味着：

用户权限降低后，PAT 权限同步降低，不会出现用户已经失去权限但 PAT 仍保留权限的情况。
管理员收紧全局策略后，所有 PAT 立即受新策略约束。
PAT 不会放大用户权限，也不会继承管理员特权。
无论通过 GuanCLI、GuanMCP 还是脚本调用，同一个问题由不同用户的 PAT 发起时，返回结果可能不同。这是权限隔离的正常表现。

常见问题

没有「个人访问令牌」入口

确认当前环境已开通 CLI 功能，并联系管理员将你本人或所在用户组添加到「管理中心 > 用户管理 > CLI 用户 > 成员」中。

PAT 不可用时，GuanCLI 和本地模式的 GuanMCP 可以按管理员要求使用账号密码或 uIdToken 过渡。

忘记保存令牌明文

PAT 明文无法找回。删除原令牌并重新创建。

提示 PAT 无效

依次检查：

PAT 是否复制完整。
PAT 是否已经过期或被删除。
管理员是否取消了你的 CLI 使用资格。
账号是否被停用、锁定或删除。

你也可以在「个人访问令牌」页面查看状态，或运行 guancli auth status 检查。

提示管理员已关闭 CLI 的 uIdToken 认证通道

管理员已经在「管理中心 > 用户管理 > CLI 」中开启「只允许 PAT 登录」。请创建 PAT 并改用 PAT 调用。

网页中有权限，但 PAT 调用提示无权限

PAT 只拥有创建时主动勾选的权限。检查「查看权限」中是否包含对应权限，以及该权限是否已经失效。需要新增权限时，请创建新令牌。

远程 GuanMCP 返回 401 或 404

返回 401：检查 PAT 是否有效，以及请求头是否为 X-Personal-Token，不能使用 Authorization: Bearer。
返回 404：确认使用管理员提供的完整地址，远程地址通常以 /mcp 结尾。

提示当前域未开通 CLI 调用能力

当前环境的 License 未包含 CLI 功能，请联系管理员或观远商务团队。如果页面出现试用到期提醒，请在到期前完成续费，否则 CLI 功能将不可用。

功能简介​

使用前提​

创建令牌​

在 GuanCLI 中使用​

在 GuanMCP 中使用​

选择连接方式​

配置本地 stdio​

配置远程 Streamable HTTP​

验证 GuanMCP 配置​

在自建脚本或程序中使用​

使用限制​

管理令牌​

安全须知​

权限生效规则​

常见问题​

没有「个人访问令牌」入口​

忘记保存令牌明文​

提示 PAT 无效​

提示管理员已关闭 CLI 的 uIdToken 认证通道​

网页中有权限，但 PAT 调用提示无权限​

远程 GuanMCP 返回 401 或 404​

提示当前域未开通 CLI 调用能力​