feishu-cli-auth：飞书OAuth认证与Token管理命令行工具，支持AI Agent两步式登录 | SkillsMDfeishu-cli-auth：飞书OAuth认证与Token管理命令行工具，支持AI Agent两步式登录
feishu-cli-auth by riba2534/feishu-cli
npx skills add https://github.com/riba2534/feishu-cli --skill feishu-cli-auth🇨🇳中文介绍
飞书 OAuth 认证与 Token 管理
feishu-cli 通过 OAuth 2.0 Authorization Code Flow 获取 User Access Token，用于搜索等需要用户身份的 API。
feishu-cli ：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。
核心概念
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 模式不可用。使用 + 两步式流程：
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
--print-url
auth callback
步骤 1：生成授权 URL
始终使用最大 scope 范围授权 ，一次性覆盖 feishu-cli 所有用户身份功能，避免后续因 scope 不足导致 99991679 错误：
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": "https://accounts.feishu.cn/open-apis/authen/v1/authorize?...",
"state": "随机64字符十六进制字符串",
"redirect_uri": "http://127.0.0.1:9768/callback"
}
将 auth_url 展示给用户，请用户在浏览器中打开并完成授权。授权后浏览器会跳转到一个无法访问的页面（127.0.0.1:9768/callback?code=xxx&state=yyy），这是正常的——让用户复制地址栏中的完整 URL。
步骤 2：用回调 URL 换 Token
feishu-cli auth callback "<回调URL>" --state "<步骤1输出的state>"
输出 JSON（stdout）+ 人类可读信息（stderr）：
{
"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 |
完整示例
# 步骤 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 错误：
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, Unauthorized | Token 的 scope 不包含目标 API 权限 | 重新登录，使用最大 scope |
| Refresh Token 为空 | 缺少 offline_access scope | 重新登录，使用最大 scope |
error=20027 | 开发者后台未启用该权限 | 在飞书开放平台启用对应权限后重新授权 |
Token 状态检查
# 人类可读格式
feishu-cli auth status
# JSON 格式（AI Agent 推荐）
feishu-cli auth status -o 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"
}
状态判断逻辑
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：
--user-access-token 命令行参数FEISHU_USER_ACCESS_TOKEN 环境变量~/.feishu-cli/token.json：
- access_token 有效 → 直接使用
- access_token 过期 + refresh_token 有效 → 自动刷新并保存新 Token
- 都过期 → 报错"已过期，请重新登录"
config.yaml 中的 user_access_token 静态配置- 全部为空 → 报错"缺少 User Access Token"，列出 4 种获取方式
刷新过程对用户透明 ：stderr 输出 [自动刷新] 刷新成功...，命令正常执行。
User Access Token 的使用场景
必需 User Access Token 的命令
| 命令类别 | 需要的 scope |
|---|
search 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：
| 命令类别 | 需要的 scope |
|---|
wiki 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 |
登录前的检查流程
# 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 的两步式外，还有三种人类用户直接使用的模式：
# 本地桌面环境（默认）：自动打开浏览器 + 本地 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 中添加：
http://127.0.0.1:9768/callback
如果使用自定义端口（--port 8080），需添加对应的重定向 URL。
Device Flow（--method device）无需此配置。
Device Flow 说明
--method device 是 Authorization Code Flow 的平替方案，区别仅在于无需配置重定向 URL 白名单：
- 执行
feishu-cli auth login --method device
- 终端显示用户码和验证链接，在浏览器中打开链接并输入用户码完成授权
- 命令自动轮询等待授权完成，成功后保存 Token
Device Flow 支持 --scopes 参数指定 OAuth scope（会自动追加 offline_access）。未指定时默认请求 offline_access。
退出登录
删除 ~/.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 不足 | 重新登录，加上缺失的 scope |
| Refresh Token 为空 | 未包含 offline_access scope | 重新登录，加上 offline_access |
| "state 不匹配" | auth callback 的 --state 与 URL 中的 state 不一致 | 确保使用同一次 --print-url 的 state |
| "端口被占用" | 9768 端口已被其他进程使用 | 使用 --port 其他端口，并在飞书平台添加对应回调 URL |
auth login --manual 在 AI Agent 中卡住 | stdin 阻塞 | 改用 --print-url + auth callback 两步式 |
Lark CLI妙记查询工具：快速获取飞书妙记元信息（标题、封面、时长）
39,100 周安装
