飞书 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 模式不可用。使用 --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：

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 的命令

命令类别	需要的 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 白名单：

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

how to use feishu-cli-auth
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use feishu-cli-auth on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add feishu-cli-auth
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/riba2534/feishu-cli --skill feishu-cli-authcopy
The skills CLI fetches feishu-cli-auth from GitHub repository riba2534/feishu-cli and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/feishu-cli-auth
Reload or restart Cursor to activate feishu-cli-auth. Access the skill through slash commands (e.g., /feishu-cli-auth) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?