name: lark-cli-install description: Install and configure lark-cli (飞书官方 CLI) from source, bind to Hermes Agent, and complete OAuth authorization. version: 1.0.0 author: Hermes Agent license: MIT

lark-cli 安装与配置

lark-cli（github.com/larksuite/cli）是飞书官方开源的命令行工具，覆盖飞书 2500+ API，面向 AI Agent 设计。

安装

❌ 不要用 npm 全局安装

npm install -g @larksuite/cli     # 会卡在 node scripts/install.js 超时
npx @larksuite/cli@latest install # 同样会超时

✅ 从源码编译（推荐）

cd /tmp
git clone --depth=1 https://github.com/larksuite/cli.git
cd cli
make build                          # 编译，自动下载依赖
cp lark-cli /usr/local/bin/        # 安装到系统 PATH
lark-cli --version                  # 验证

绑定到 Hermes Agent

前提条件

Hermes 的 feishu extra 配置中已有 app_id 和 app_secret（在 ~/.hermes/config.yaml 的 feishu.extra 下）。前提条件

Hermes 的 feishu extra 配置中已有 app_id 和 app_secret（在 ~/.hermes/config.yaml 的 feishu.extra 下）。### 步骤

确保 .env 里有 App ID 和 Secret

# ~/.hermes/profiles/friend/.env 需要包含：
FEISHU_APP_ID=cli_a9xxxxxxxxxxxxx
FEISHU_APP_SECRET=JaqF9g...JcKT

如果缺少，从 ~/.hermes/config.yaml 的 feishu.extra.app_id / app_secret 抄过来。

绑定（不要用 config init）

在 Hermes 上下文中，lark-cli config init 会被拒绝。必须用：

lark-cli config bind --source hermes --app-id <APP_ID> --identity user-default

--identity 选项： - bot-only（安全默认）— 仅机器人身份，不能访问个人资源 - user-default — 可模拟用户身份，能访问个人日历/邮件/云盘等

用户 OAuth 授权

授权有两种方式：

### 方式 A：主动等待模式（推荐，较简单）

lark-cli auth login --recommend

这条命令会在 stderr 输出一个授权 URL，格式如：

https://accounts.feishu.cn/oauth/v1/device/verify?flow_id=...&user_code=XXXX-XXXXX

将 URL 原样逐字发给用户在浏览器中打开授权。注意： - 不要做 URL 编码/解码 - 不要改写成 Markdown 链接 - 用纯文本或代码块输出 - 命令最长等待约 10 分钟，timeout 要设够（建议 600s） - 不要短 timeout 反复重试，每次重启会作废上一轮的 device code - 用户授权完成后，命令会自动退出（exit code 0）

### 方式 B：无等待 + 续轮询（适合有 timeout 限制的环境）

如果 CLI runner timeout 小于 600s，或者后台进程会被 SIGTERM（exit code 143）：

# 第一步：生成链接但不等待（获取 device_code）
lark-cli auth login --no-wait --json
# 输出类似：{"device_code": "xxx", "user_code": "XXXX-XXXXX", "url": "https://..."}

# 第二步：把 url 发给用户授权，然后用 device_code 续上轮询
lark-cli auth login --device-code <device_code>

注意：lark-cli 2>重定向 stdout 可能无输出，输出可能只在 stderr。如果担心，用 2>/tmp/lark-auth.log 捕获 stderr 再读取。

   注意：lark-cli 2>重定向 stdout 可能无输出，输出可能只在 stderr。如果担心，用 `2>/tmp/lark-auth.log` 捕获 stderr 再读取。4. **验证**

   ```bash
   lark-cli doctor
   ```
4. **验证**

   ```bash
   lark-cli doctor
   ```## 验证是否正常

```bash
lark-cli doctor
lark-cli auth status

常用命令

lark-cli im +send-message --chat-id <chat_id> --text "hello"    # 发消息
lark-cli im +chat-history --chat-id <chat_id>                    # 看聊天历史
lark-cli contact +search-user --query "name"                     # 搜联系人
lark-cli calendar +agenda                                        # 看日程

已知坑点

npm 全局安装超时 — 必须从源码编译，make build 是稳定的方式
Hermes 上下文禁止 config init — 必须用 config bind
授权 URL 必须原样发送 — 任何改动（编码、Markdown、空格）都会导致授权失败
重复 auth login 会作废前一个链接 — 不要超时重试，一次生成一个链接即可