Back to Details

feishu-e2e-test

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Feishu E2E Test Framework

飞书E2E测试框架

Local development testing using 
agent-browser
CLI to interact with Feishu web app.
使用
agent-browser
CLI与飞书Web应用进行本地开发测试。

Prerequisites

前置条件

  • Feishu web logged in at 
    https://feishu.cn/next/messenger
  • agent-browser
    CLI available
  • OpenClaw locally installed
  • Feishu bot appid/secret given in chat or in .env
  • User given bot name which will display in Feishu web UI
  • 已在
    https://feishu.cn/next/messenger
    登录飞书Web端
  • 已安装
    agent-browser
    CLI
  • 已本地安装OpenClaw
  • 聊天窗口或.env文件中提供了飞书机器人的appid/密钥
  • 已指定将在飞书Web UI中显示的机器人名称

Important Notes

重要提示

Every time you modify extension code, you MUST restart OpenClaw Gateway for changes to take effect.
bash
undefined
每次修改扩展代码后，必须重启OpenClaw Gateway才能使更改生效。
bash
undefined

Restart gateway (required after code changes)

重启网关（代码修改后必须执行）

openclaw gateway restart
openclaw gateway restart

Check if gateway is running

检查网关是否在运行

ps aux | grep openclaw
ps aux | grep openclaw

View gateway logs

查看网关日志

tail -f ~/.openclaw/logs/gateway.log
undefined
tail -f ~/.openclaw/logs/gateway.log
undefined

agent-browser Usage

agent-browser 使用方法

Always use 
--headed
mode so user can see the browser and help with login:
bash
agent-browser --headed --session feishu-test open "https://feishu.cn/next/messenger"
始终使用
--headed
模式，以便用户可以看到浏览器并协助登录：
bash
agent-browser --headed --session feishu-test open "https://feishu.cn/next/messenger"

Feishu Web UI Tips

飞书Web UI技巧

Feishu web has complex UI that makes direct clicking unreliable. Use these strategies:
飞书Web端UI结构复杂，直接点击操作不可靠。请使用以下策略：

1. Use Search (Cmd+K) Instead of Clicking

1. 使用搜索（Cmd+K）替代点击

Clicking on chat list items often misses or selects wrong item. Use global search:
bash
undefined
点击聊天列表项经常会失准或选中错误项。使用全局搜索：
bash
undefined

Open search

打开搜索

agent-browser --session feishu-test press "Meta+k"
agent-browser --session feishu-test press "Meta+k"

Type bot name letter by letter

逐个输入机器人名称的字母

agent-browser --session feishu-test press "o" agent-browser --session feishu-test press "p" agent-browser --session feishu-test press "e" agent-browser --session feishu-test press "n"
agent-browser --session feishu-test press "o" agent-browser --session feishu-test press "p" agent-browser --session feishu-test press "e" agent-browser --session feishu-test press "n"

Select first result

选择第一个结果

agent-browser --session feishu-test press "Enter"
undefined
agent-browser --session feishu-test press "Enter"
undefined

2. Focus Input with "/" Key

2. 使用 "/" 键聚焦输入框

After entering a chat, press "/" to focus the message input:
bash
agent-browser --session feishu-test press "/"
agent-browser --session feishu-test press "Backspace"  # Remove the "/"
进入聊天窗口后，按 "/" 键聚焦消息输入框：
bash
agent-browser --session feishu-test press "/"
agent-browser --session feishu-test press "Backspace"  # 删除输入的 "/"

Then type your message

然后输入你的消息

undefined
undefined

3. Type Characters One by One

3. 逐个输入字符

The 
type
command often fails with special characters. Use 
press
for each character:
bash
undefined
type
命令在输入特殊字符时经常失败。使用
press
命令逐个输入字符：
bash
undefined

Instead of: agent-browser type "ping"

不推荐：agent-browser type "ping"

agent-browser --session feishu-test press "p" agent-browser --session feishu-test press "i" agent-browser --session feishu-test press "n" agent-browser --session feishu-test press "g"
undefined
agent-browser --session feishu-test press "p" agent-browser --session feishu-test press "i" agent-browser --session feishu-test press "n" agent-browser --session feishu-test press "g"
undefined

4. Chinese Characters Do NOT Work

4. 中文输入不生效

Chinese characters cannot be typed with 
press
command. Use English only:
bash
undefined
press
命令无法输入中文。请仅使用英文：
bash
undefined

BAD - Chinese won't render

错误示例 - 中文无法正常显示

for char in $(echo "读取文档" | grep -o .); do agent-browser --session feishu-test press "$char" # Will fail silently done
for char in $(echo "读取文档" | grep -o .); do agent-browser --session feishu-test press "$char" # 会静默失败 done

GOOD - Use English

正确示例 - 使用英文

for char in r e a d " " d o c; do agent-browser --session feishu-test press "$char" done
undefined
for char in r e a d " " d o c; do agent-browser --session feishu-test press "$char" done
undefined

5. Typing Spaces

5. 输入空格

Spaces must be quoted as 
" "
:
bash
undefined
空格必须用
" "
包裹：
bash
undefined

Type "read doc"

输入 "read doc"

for char in r e a d " " d o c; do agent-browser --session feishu-test press "$char" done
undefined
for char in r e a d " " d o c; do agent-browser --session feishu-test press "$char" done
undefined

6. Typing Long Strings Efficiently

6. 高效输入长字符串

Use a for loop to type URLs or long text:
bash
undefined
使用for循环输入URL或长文本：
bash
undefined

Type a full URL

输入完整URL

url="https://feishu.cn/docx/YOUR_DOC_TOKEN" for char in $(echo "$url" | grep -o .); do agent-browser --session feishu-test press "$char" 2>/dev/null || true done
undefined
url="https://feishu.cn/docx/YOUR_DOC_TOKEN" for char in $(echo "$url" | grep -o .); do agent-browser --session feishu-test press "$char" 2>/dev/null || true done
undefined

7. Avoid JS eval on Feishu

7. 避免在飞书页面使用JS eval

Do NOT use 
eval
to set input values - it can break the page:
bash
undefined
请勿使用
eval
设置输入框值 - 这会破坏页面：
bash
undefined

BAD - will corrupt page

错误示例 - 会损坏页面

agent-browser eval "document.activeElement.innerText = 'text'"
agent-browser eval "document.activeElement.innerText = 'text'"

GOOD - use keyboard input

正确示例 - 使用键盘输入

agent-browser press "t" && agent-browser press "e" ...
undefined
agent-browser press "t" && agent-browser press "e" ...
undefined

8. Full URLs Work Better Than IDs

8. 完整URL比ID更可靠

When testing document tools, send full URLs rather than just document IDs:
bash
undefined
测试文档工具时，请发送完整URL而非仅文档ID：
bash
undefined

Better - bot recognizes as document link

推荐 - 机器人可识别为文档链接

"https://feishu.cn/docx/YOUR_DOC_TOKEN"
"https://feishu.cn/docx/YOUR_DOC_TOKEN"

Less reliable - may not trigger tool

可靠性低 - 可能无法触发工具

"read YOUR_DOC_TOKEN"
undefined
"read YOUR_DOC_TOKEN"
undefined

Verifying Tool Calls

验证工具调用

Log Patterns

日志模式

Monitor gateway logs to verify tool execution:
bash
tail -f ~/.openclaw/logs/gateway.log
Key log entries:
  • [feishu] received message from ...
    - incoming message
  • [feishu] dispatching to agent
    - sent to agent
  • [feishu] added typing indicator reaction
    - bot is processing
  • [feishu] deliver called: text=...
    - agent response
  • [feishu] dispatch complete
    - response sent
监控网关日志以验证工具执行：
bash
tail -f ~/.openclaw/logs/gateway.log
关键日志条目：
  • [feishu] received message from ...
    - 收到消息
  • [feishu] dispatching to agent
    - 已发送至Agent
  • [feishu] added typing indicator reaction
    - 机器人正在处理
  • [feishu] deliver called: text=...
    - Agent返回响应
  • [feishu] dispatch complete
    - 响应已发送

Verify Tool Usage

验证工具使用情况

Ask bot explicitly to confirm tool usage:
use feishu_doc tool to read YOUR_DOC_TOKEN
Look for confirmation in response like:
"我已经用 Feishu Doc Tool 读过了这个文档"
直接询问机器人以确认工具使用：
use feishu_doc tool to read YOUR_DOC_TOKEN
在响应中查找类似如下的确认信息：
"我已经用 Feishu Doc Tool 读过了这个文档"

Common Errors

常见错误

Permission Error (99991672)

权限错误（99991672）

Access denied. One of the following scopes is required: [contact:contact.base:readonly...]
This means bot lacks contact permission. Doesn't affect core messaging but prevents resolving sender names.
Access denied. One of the following scopes is required: [contact:contact.base:readonly...]
这表示机器人缺少联系人权限。不会影响核心消息功能，但会导致无法解析发送者名称。

Other Log Locations

其他日志位置

bash
undefined
bash
undefined

Error logs

错误日志

tail -f ~/.openclaw/logs/gateway.err.log
tail -f ~/.openclaw/logs/gateway.err.log

All log files

所有日志文件

ls -la ~/.openclaw/logs/
ls -la ~/.openclaw/logs/

Raw agent session records (tool calls, responses, etc.)

原始Agent会话记录（工具调用、响应等）

ls ~/.openclaw/agents/main/sessions/
ls ~/.openclaw/agents/main/sessions/

View specific session

查看指定会话

cat ~/.openclaw/agents/main/sessions/<session-id>.json
undefined
cat ~/.openclaw/agents/main/sessions/<session-id>.json
undefined

Test Workflow

测试流程

  1. Start browser: 
    agent-browser --headed --session feishu-test open "https://feishu.cn/next/messenger"
  2. User scans QR to login
  3. Search for bot: 
    Cmd+K
    → type bot name → 
    Enter
  4. Focus input: press 
    /
    then 
    Backspace
  5. Type message (English only, letter by letter)
  6. Press 
    Enter
    to send
  7. Wait 10-20 seconds for response
  8. Take screenshot and check logs to verify
  1. 启动浏览器：
    agent-browser --headed --session feishu-test open "https://feishu.cn/next/messenger"
  2. 用户扫码登录
  3. 搜索机器人：
    Cmd+K
    → 输入机器人名称 → 
    Enter
  4. 聚焦输入框：按
    /
    后按
    Backspace
  5. 输入消息（仅英文，逐个字母输入）
  6. 按
    Enter
    发送
  7. 等待10-20秒获取响应
  8. 截图并检查日志进行验证

Testing feishu_doc Tool

测试feishu_doc工具

bash
undefined
bash
undefined

1. Focus input

1. 聚焦输入框

agent-browser --session feishu-test press "/" &&
agent-browser --session feishu-test press "Backspace"
agent-browser --session feishu-test press "/" &&
agent-browser --session feishu-test press "Backspace"

2. Type full doc URL

2. 输入完整文档URL

url="https://feishu.cn/docx/YOUR_DOC_ID" for char in $(echo "$url" | grep -o .); do agent-browser --session feishu-test press "$char" 2>/dev/null || true done
url="https://feishu.cn/docx/YOUR_DOC_ID" for char in $(echo "$url" | grep -o .); do agent-browser --session feishu-test press "$char" 2>/dev/null || true done

3. Send

3. 发送

agent-browser --session feishu-test press "Enter"
agent-browser --session feishu-test press "Enter"

4. Wait and check logs

4. 等待并查看日志

sleep 15 && tail -30 ~/.openclaw/logs/gateway.log
undefined
sleep 15 && tail -30 ~/.openclaw/logs/gateway.log
undefined