---
name: lark-action-as-bot
version: 1.0.0
description: "飞书 Bot 身份操作指南：指导每个 agent 如何以自己的应用（bot）身份执行 lark-cli 命令。包含环境变量配置、凭证隔离、bot 身份调用规范。当 agent 需要以 bot 身份操作飞书资源（知识库、文档、消息等）时使用。"
metadata:
  requires:
    bins: ["lark-cli"]
---

# 以 Bot 身份操作飞书

本技能指导你（AI agent）如何以**自己的应用身份（bot）**独立执行飞书操作。

## 核心机制

每个 agent 拥有独立的飞书应用凭证，存放在各自的配置目录中。通过设置 `LARKSUITE_CLI_CONFIG_DIR` 环境变量，让 `lark-cli` 读取对应 agent 的凭证，实现身份隔离。

## Agent 凭证目录

| Agent | 配置目录 |
|-------|---------|
| xiaoxi（小溪） | `/root/.openclaw/credentials/xiaoxi/` |
| xiaoban（小斑） | `/root/.openclaw/credentials/xiaoban/` |
| xiaobian（小编） | `/root/.openclaw/credentials/xiaobian/` |
| xiaoyan（小研） | `/root/.openclaw/credentials/xiaoyan/` |
| xiaokui（小葵） | `/root/.openclaw/credentials/xiaokui/` |
| may（May） | `/root/.openclaw/credentials/may/` |

每个目录下包含 `config.json`，格式为：

```json
{
  "apps": [
    {
      "appId": "<该agent的appId>",
      "appSecret": "<该agent的appSecret>",
      "brand": "feishu",
      "lang": "zh",
      "users": []
    }
  ]
}
```

## 调用规范

### 基本格式

**所有 lark-cli 命令前必须加上环境变量前缀：**

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> lark-cli <command> --as bot
```

### 确定你的 agent_name

你需要根据自己的身份确定 `agent_name`。查看你的 IDENTITY.md 或 workspace 目录名称来确认。例如：
- 如果你是小斑，`agent_name` 为 `xiaoban`
- 如果你是小溪，`agent_name` 为 `xiaoxi`

### 常用操作示例

#### 读取知识库文档

```bash
# 1. 解析 wiki 链接获取真实文档 token
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
  lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --as bot

# 2. 获取文档内容
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
  lark-cli docs +fetch --doc <obj_token> --as bot
```

#### 编辑知识库文档

```bash
# 追加内容
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
  lark-cli docs +update --doc <obj_token> --as bot --markdown '要追加的内容' --mode append

# 覆盖内容
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
  lark-cli docs +update --doc <obj_token> --as bot --markdown '新的完整内容' --mode overwrite
```

#### 搜索文档

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
  lark-cli docs +search --query '搜索关键词' --as bot
```

#### 发送消息

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
  lark-cli im messages create --as bot --data '{"receive_id":"<id>","msg_type":"text","content":"{\"text\":\"消息内容\"}"}'
```

## Wiki 链接处理（重要）

知识库链接格式为 `https://<domain>.feishu.cn/wiki/<wiki_token>`，其中 `wiki_token` **不能直接用于文档操作**。必须先通过 `wiki spaces get_node` 获取 `obj_token`，再用 `obj_token` 调用 `docs` 相关命令。详见 `lark-doc` 和 `lark-wiki` 技能。

## Bot 身份注意事项

- **始终使用 `--as bot`**：agent 自主操作时统一使用 bot 身份，无需 `auth login`
- **Bot 只能访问被授权的资源**：知识库需管理员将 bot 应用添加为知识空间成员
- **Bot 创建的内容归属应用**：创建的文档、发送的消息均以应用名义
- **权限不足时**：检查错误中的 `console_url`，引导管理员在飞书开发者后台开通对应 scope
- **禁止对 bot 执行 `auth login`**

## 凭证初始化（新 agent）

如果某个 agent 的凭证目录尚未创建，按以下步骤初始化：

1. 从 `openclaw.json` 的 `channels.feishu.accounts` 中获取该 agent 的 `appId` 和 `appSecret`
2. 创建目录和配置文件：

```bash
mkdir -p /root/.openclaw/credentials/<agent_name>
cat > /root/.openclaw/credentials/<agent_name>/config.json << 'EOF'
{
  "apps": [
    {
      "appId": "<appId>",
      "appSecret": "<appSecret>",
      "brand": "feishu",
      "lang": "zh",
      "users": []
    }
  ]
}
EOF
```

## 安全规则

- **禁止在终端明文输出 appSecret 或 accessToken**
- **写入/删除操作前必须确认用户意图**
- 使用 `--dry-run` 预览危险请求