Productivity
feishu-cli-auth▌
riba2534/feishu-cli · updated Apr 8, 2026
$npx skills add https://github.com/riba2534/feishu-cli --skill feishu-cli-auth
summary
feishu-cli 通过 OAuth 2.0 Authorization Code Flow 获取 User Access Token，用于搜索等需要用户身份的 API。
skill.md
飞书 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_accessscope） - 过期后自动用 Refresh Token 刷新，用户无感
两步式非交互登录（AI Agent 推荐）
AI Agent 的 Bash tool 无法进行交互式 stdin 输入，因此 --manual 模式不可用。使用 --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.members:read contact:user.base:readonly drive:drive.metadata:readonly"
输出 JSON（stdout）：
{
"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
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.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.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:read |
群聊信息只读（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
当已登录且 Token 有效时：
{
"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}
状态判断逻辑
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:read |
chat update/delete |
im:chat |
chat member list/add/remove |
im:chat:read、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.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.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.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 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 不足 | 重新登录，加上缺失的 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 两步式 |
| 99991672 Access denied, scope required | 应用未开通所需权限 | 使用 config add-scopes --domain <域> 申请 |
创建飞书应用（自动注册）
对于第一次使用 feishu-cli 的用户，无需手动到飞书开放平台创建应用，可通过 CLI 一键完成：
# 创建新应用（交互式，输出授权链接，用户扫码确认）
feishu-cli config create-app
# 创建并自动保存到配置文件
feishu-cli config create-app --save
# Lark 国际版
feishu-cli config create-app --brand lark
流程：
- CLI 向
accounts.feishu.cn/oauth/v1/app/registration发起 Device Flow 注册 - 终端输出授权链接和用户码，用户在浏览器打开链接扫码确认
- CLI 轮询等待，用户确认后自动获取 App ID 和 App Secret
- 加
--save时自动写入~/.feishu-cli/config.yaml
参数：
| 参数 | 说明 |
|---|---|
--brand |
平台（feishu/lark，默认 feishu） |
--save |
自动保存到配置文件 |
-o json |
JSON 格式输出 app_id 和 app_secret |
创建成功后的下一步：
# 1. 申请需要的权限
feishu-cli config add-scopes --domain all
# 2. 登录授权
feishu-cli auth login
为应用申请开通权限
当命令返回 99991672 Access denied 或 99991679 Unauthorized 时，说明应用缺少对应权限。使用 config add-scopes 批量申请：
# 按域批量申请（推荐）
feishu-cli config add-scopes --domain calendar,task,vc
# 申请所有常用权限
feishu-cli config add-scopes --domain all
# 指定具体 scope
feishu-cli config add-scopes --scopes "vc:meeting:readonly minutes:minutes:readonly"
# 只输出链接（不打开浏览器）
feishu-cli config add-scopes --domain doc,im --print-only
可用的域名：
| 域名 | 包含的权限 |
|---|---|
calendar |
日历读写（calendar:calendar, calendar:calendar:readonly, calendar:calendar.event:read/write） |
task |
任务读写（task:task:read/write, task:comment:read/write, task:tasklist:read/write） |
vc |
视频会议（vc:meeting:readonly, vc:room:readonly） |
minutes |
妙记（minutes:minutes:readonly） |
doc |
文档/知识库/云空间（docx:document, wiki:wiki:readonly, drive:drive 等） |
im |
消息/群聊（im:message, im:chat 等） |
bitable |
多维表格（bitable:app） |
sheet |
电子表格（sheets:spreadsheet:create/read/write_only，注意：不存在 sheets:spreadsheet:readonly） |
contact |
通讯录（contact:user.base:readonly） |
search |
搜索（search:docs:read, search:message） |
export |
导出（drive:export:readonly, docs:document:export） |
all |
以上全部 |
操作流程：命令生成飞书开放平台的权限申请链接 → 在浏览器中打开 → 点击「开通权限」即可。