飞书 OAuth 认证与 Token 管理#

feishu-cli 通过 OAuth 2.0 Authorization Code Flow 获取 User Access Token，用于搜索等需要用户身份的 API。

核心概念#

Token 存储位置：所有 OAuth Token 保存在 ~/.feishu-cli/token.json，包括 Access Token、Refresh Token、过期时间和授权 scope。登录、刷新、退出等操作都围绕此文件进行。

两种身份：

• App Access Token（应用身份）：通过 app_id/app_secret 自动获取，大多数文档操作使用此身份
• User Access Token（用户身份）：需 OAuth 授权，搜索 API 必须 使用此身份

Token 生命周期：

• Access Token： 2 小时 有效
• Refresh Token： 30 天 有效（需 offline_access scope）
• 过期后自动用 Refresh Token 刷新，用户无感

---

两步式非交互登录（AI Agent 推荐）#

AI Agent 的 Bash tool 无法进行交互式 stdin 输入，因此 --manual 模式不可用。使用 --print-url + auth callback 两步式流程：

步骤 1：生成授权 URL#

始终使用最大 scope 范围授权，一次性覆盖 feishu-cli 所有用户身份功能，避免后续因 scope 不足导致 99991679 错误：

bash

feishu-cli auth login --print-url --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read im:chat:readonly im:chat.members:read contact:user.base:readonly drive:drive.metadata:readonly"

输出 JSON（stdout）：

json

{
  "auth_url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize?...",
  "state": "随机64字符十六进制字符串",
  "redirect_uri": "http://127.0.0.1:9768/callback"
}

立即返回，不阻塞，不启动 HTTP 服务器。

将 auth_url 展示给用户，请用户在浏览器中打开并完成授权。授权后浏览器会跳转到一个无法访问的页面（ 127.0.0.1:9768/callback?code=xxx&state=yyy），这是正常的——让用户复制地址栏中的完整 URL。

步骤 2：用回调 URL 换 Token#

bash

feishu-cli auth callback "<回调URL>" --state "<步骤1输出的state>"

输出 JSON（stdout）+ 人类可读信息（stderr）：

json

{
  "status": "success",
  "expires_at": "2026-03-09T04:31:11+08:00",
  "scope": "auth:user.id:read search:docs:read search:message offline_access"
}

Token 自动保存到 ~/.feishu-cli/token.json。

auth callback 常见错误#

错误原因解决code has expired授权 code 有效期约 5 分钟，用户复制回调 URL 太慢重新执行步骤 1 获取新的授权 URL，提醒用户尽快完成state 不匹配``--state 参数与回调 URL 中的 state 不一致，或混用了不同次 --print-url 的结果确保 --state 使用的是同一次 --print-url 输出的 state 值网络超时 / 连接失败无法访问飞书 OAuth 服务器（网络不通或代理问题）检查网络连通性，确认能访问 open.feishu.cn；如有代理需配置 HTTPS_PROXY

完整示例#

bash

# 步骤 1（使用最大 scope 范围）
feishu-cli auth login --print-url --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read im:chat:readonly im:chat.members:read contact:user.base:readonly drive:drive.metadata:readonly"
# → 展示 auth_url 给用户，用户浏览器授权后复制回调 URL

# 步骤 2（用步骤 1 的 state 和用户提供的回调 URL）
feishu-cli auth callback "http://127.0.0.1:9768/callback?code=xxx&state=yyy" --state "yyy"

---

Scope 配置#

scope 决定了 Token 能访问哪些 API。登录时通过 --scopes 指定（空格分隔）。scope 名称 = 飞书开放平台开发者后台的权限名称，最多 50 个，多次授权 累加 生效。

默认策略：始终使用最大 scope#

每次登录都使用以下完整 scope 列表，一次性覆盖 feishu-cli 全部用户身份功能。避免因 scope 不足导致部分命令报 99991679 错误：

text

offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read im:chat:readonly im:chat.members:read contact:user.base:readonly drive:drive.metadata:readonly

Token 使用策略#

feishu-cli 命令按 Token 要求分为三类：

必须 User Token：搜索命令（ search docs/messages/apps）和消息/群聊互动命令（ msg get/list/history/pins/pin/unpin/reaction/delete、 msg search-chats、 chat get/update/delete、 chat member list/add/remove）通过 resolveRequiredUserToken 强制使用 User Token，自动从 token.json 加载。

可选 User Token：wiki、calendar、task、doc export 等命令通过 resolveOptionalUserToken 默认使用 App Token（租户身份），不会自动从 token.json 加载。仅在通过 --user-access-token 参数或 FEISHU_USER_ACCESS_TOKEN 环境变量显式指定时才使用 User Token。

仅 App Token：文档创建/导入、消息发送/回复/转发、权限管理等命令仅使用 App Token，不支持 User Token。

Scope 完整说明#

scope作用对应命令offline_access获取 Refresh Token（30 天有效）必须包含，否则 2 小时后需重新登录search:docs:read搜索云文档search docs``search:message搜索消息search messages``drive:drive.search:readonly搜索云空间文件search docs（补充权限）wiki:wiki:readonly知识库读取（用户身份）wiki get/export/nodes``calendar:calendar:read日历读取calendar list/get/primary``calendar:calendar.event:read日历事件读取calendar event-search``calendar:calendar.event:create创建日历事件calendar create-event``calendar:calendar.event:update更新日历事件calendar event-reply``calendar:calendar.event:reply回复日历事件calendar event-reply``calendar:calendar.free_busy:read忙闲查询calendar freebusy``task:task:read任务读取task list/get``task:task:write任务写入task create/complete``task:tasklist:read任务列表读取tasklist list/get``task:tasklist:write任务列表写入tasklist create/delete``im:message:readonly消息历史读取msg history/get``im:message.group_msg:get_as_user用户身份读取群消息msg list/history（User Token 读群消息必需）im:chat:read群聊搜索（User Token）msg search-chats``im:chat:readonly群聊信息只读（User Token）chat get、 chat member list``im:chat.members:read群成员列表读取（User Token）chat member list``im:message.pins消息置顶管理（User Token）msg pin/unpin/pins``im:message.reactions消息 Reaction 管理（User Token）msg reaction add/remove/list``contact:user.base:readonly用户信息读取user info/search``drive:drive.metadata:readonly文件元数据读取file list/meta``auth:user.id:read用户身份信息通常自动包含

前提条件#

scope 中的权限必须先在飞书开放平台 → 应用详情 → 权限管理中启用。未启用的权限在授权时会被忽略或报错 20027。

常见错误#

错误原因解决error=99991679, UnauthorizedToken 的 scope 不包含目标 API 权限重新登录，使用最大 scopeRefresh Token 为空缺少 offline_access scope重新登录，使用最大 scopeerror=20027开发者后台未启用该权限在飞书开放平台启用对应权限后重新授权

---

Token 状态检查#

bash

# 人类可读格式
feishu-cli auth status

# JSON 格式（AI Agent 推荐）
feishu-cli auth status -o json

当已登录且 Token 有效时：

json

{
  "logged_in": true,
  "access_token_valid": true,
  "access_token_expires_at": "2026-03-09T04:32:19+08:00",
  "refresh_token_valid": true,
  "refresh_token_expires_at": "2026-03-16T02:32:19+08:00",
  "scope": "auth:user.id:read search:docs:read search:message offline_access"
}

当未登录时：

json

{"logged_in": false}

状态判断逻辑#

text

logged_in=false           → 从未登录，需要 auth login
access_token_valid=true   → 正常可用
access_token_valid=false + refresh_token_valid=true → 下次调用时自动刷新，无需操作
access_token_valid=false + refresh_token_valid=false → 需要重新 auth login
scope 中无目标权限         → 需要重新登录并补充 scope

---

Token 自动刷新机制#

搜索、消息互动、群聊管理等 必须 User Access Token 的命令（ resolveRequiredUserToken）通过 ResolveUserAccessToken() 按以下优先级链查找。其他可选命令（ resolveOptionalUserToken）仅检查第 1、2 项，默认使用 App Token：

1. --user-access-token 命令行参数

2. FEISHU_USER_ACCESS_TOKEN 环境变量

3. ~/.feishu-cli/token.json：

   • access_token 有效 → 直接使用
   • access_token 过期 + refresh_token 有效 → 自动刷新并保存新 Token
   • 都过期 → 报错"已过期，请重新登录"

4. config.yaml 中的 user_access_token 静态配置

5. 全部为空 → 报错"缺少 User Access Token"，列出 4 种获取方式

刷新过程对用户透明：stderr 输出 [自动刷新] 刷新成功...，命令正常执行。

---

User Access Token 的使用场景#

必需 User Access Token 的命令#

命令类别需要的 scopesearch docs "关键词"``search:docs:read``search messages "关键词"``search:message``search apps "关键词"（需确认应用是否已开通搜索应用权限）msg get``im:message:readonly``msg list/history``im:message:readonly、 im:message.group_msg:get_as_user``msg pin/unpin/pins``im:message.pins``msg reaction add/remove/list``im:message.reactions``msg delete``im:message``msg search-chats``im:chat:read``chat get``im:chat:readonly``chat update/delete``im:chat``chat member list/add/remove``im:chat:readonly、 im:chat.members:read、 im:chat.members

可选 User Access Token 的命令#

以下命令默认使用 App Token（租户身份），仅在通过 --user-access-token 参数或 FEISHU_USER_ACCESS_TOKEN 环境变量显式指定时才使用 User Token：

命令类别需要的 scopewiki get/export/nodes``wiki:wiki:readonly``calendar list/get/event-search/freebusy``calendar:calendar:read 等task create/complete/list``task:task:read task:task:write``tasklist create/list/delete``task:tasklist:read task:tasklist:write``user info/search``contact:user.base:readonly

登录前的检查流程#

bash

# 1. 检查是否已登录且 Token 有效
feishu-cli auth status -o json

# 2. 如果未登录或已过期，执行两步式登录（使用最大 scope）
feishu-cli auth login --print-url --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read im:chat:readonly im:chat.members:read contact:user.base:readonly drive:drive.metadata:readonly"
# ... 用户授权 ...
feishu-cli auth callback "<回调URL>" --state "<state>"

# 3. 登录后搜索命令自动从 token.json 读取 Token
feishu-cli search docs "产品需求"
# 其他命令默认使用 App Token，需要时可显式传 --user-access-token
feishu-cli wiki export <node_token> -o doc.md
feishu-cli task create --summary "待办事项"

---

其他登录模式#

除 AI Agent 的两步式外，还有三种人类用户直接使用的模式：

bash

# 本地桌面环境（默认）：自动打开浏览器 + 本地 HTTP 回调
feishu-cli auth login --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read im:chat:readonly im:chat.members:read contact:user.base:readonly drive:drive.metadata:readonly"

# 远程 SSH 环境：打印 URL，用户手动粘贴回调 URL（交互式 stdin）
feishu-cli auth login --manual --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read im:chat:readonly im:chat.members:read contact:user.base:readonly drive:drive.metadata:readonly"

# Device Flow：无需在飞书开放平台配置重定向 URL 白名单
feishu-cli auth login --method device

# Device Flow + 指定 scope
feishu-cli auth login --method device --scopes "offline_access search:docs:read"

Authorization Code Flow 前置条件#

在飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL 中添加：

text

http://127.0.0.1:9768/callback

如果使用自定义端口（ --port 8080），需添加对应的重定向 URL。

Device Flow（ --method device）无需此配置。

Device Flow 说明#

--method device 是 Authorization Code Flow 的平替方案，区别仅在于无需配置重定向 URL 白名单：

1. 执行 feishu-cli auth login --method device
2. 终端显示用户码和验证链接，在浏览器中打开链接并输入用户码完成授权
3. 命令自动轮询等待授权完成，成功后保存 Token

Device Flow 支持 --scopes 参数指定 OAuth scope（会自动追加 offline_access）。未指定时默认请求 offline_access。

---

退出登录#

bash

feishu-cli auth logout

删除 ~/.feishu-cli/token.json，不影响 App Access Token（app_id/app_secret）。

---

排错指南#

问题诊断解决"缺少 User Access Token"从未登录执行 auth login"User Access Token 已过期"token.json 中 access + refresh 都过期重新 auth login搜索报 99991679 权限错误scope 不足重新登录，加上缺失的 scopeRefresh Token 为空未包含 offline_access scope重新登录，加上 offline_access"state 不匹配"auth callback 的 --state 与 URL 中的 state 不一致确保使用同一次 --print-url 的 state"端口被占用"9768 端口已被其他进程使用使用 --port 其他端口，并在飞书平台添加对应回调 URLauth login --manual 在 AI Agent 中卡住stdin 阻塞改用 --print-url + auth callback 两步式