feishu-e2e-test

Feishu 端到端测试框架

使用 agent-browser CLI 与 Feishu 网页应用交互，进行本地开发测试。

前提条件

• 已在 Feishu 网页端登录：https://feishu.cn/next/messenger
• 已安装 agent-browser CLI
• 已在本地安装 OpenClaw
• Feishu 机器人 appid/secret 已在聊天中提供或写入 .env
• 用户已提供机器人名称，该名称会显示在 Feishu 网页 UI 中

重要说明

每次修改扩展代码后，都必须重启 OpenClaw Gateway，修改才能生效。

# Restart gateway (required after code changes)
openclaw gateway restart

# Check if gateway is running
ps aux | grep openclaw

# View gateway logs
tail -f ~/.openclaw/logs/gateway.log

agent-browser 用法

始终使用 --headed 模式，以便用户查看浏览器并协助登录：

agent-browser --headed --session feishu-test open "https://feishu.cn/next/messenger"

Feishu 网页 UI 提示

Feishu 网页 UI 比较复杂，直接点击不太可靠。请使用以下策略：

1. 使用搜索（Cmd+K），而不是点击

点击聊天列表项时经常会点错或选中错误的项目。请使用全局搜索：

# Open search
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"

# Select first result
agent-browser --session feishu-test press "Enter"

2. 使用“/”键聚焦输入框

进入聊天后，按“/”键聚焦消息输入框：

agent-browser --session feishu-test press "/"
agent-browser --session feishu-test press "Backspace"  # Remove the "/"
# Then type your message

3. 逐个输入字符

type 命令经常无法处理特殊字符。请使用 press 逐个输入字符：

# Instead of: 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"

4. 无法输入中文字符

**无法使用 press 命令输入中文字符。**请仅使用英文：

# BAD - Chinese won't render
for char in $(echo "读取文档" | grep -o .); do
  agent-browser --session feishu-test press "$char"  # Will fail silently
done

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

5. 输入空格

空格必须写成 " "：

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

6. 高效输入长字符串

使用 for 循环输入 URL 或长文本：

# Type a full 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

7. 避免在 Feishu 上使用 JS eval

请勿使用 eval 设置输入框的值，这可能会导致页面故障：

# BAD - will corrupt page
agent-browser eval "document.activeElement.innerText = 'text'"

# GOOD - use keyboard input
agent-browser press "t" && agent-browser press "e" ...

8. 使用完整 URL 优于使用 ID

测试文档工具时，请发送完整 URL，而不只是文档 ID：

# Better - bot recognizes as document link
"https://feishu.cn/docx/YOUR_DOC_TOKEN"

# Less reliable - may not trigger tool
"read YOUR_DOC_TOKEN"

验证工具调用

日志模式

监控 Gateway 日志以验证工具执行情况：

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 - 已发送响应

验证工具使用情况

明确询问机器人是否使用了工具：

use feishu_doc tool to read YOUR_DOC_TOKEN

查看响应中是否有类似这样的确认：

“我已经用 Feishu Doc Tool 读过了这个文档”

常见错误

权限错误（99991672）

Access denied. One of the following scopes is required: [contact:contact.base:readonly...]

这表示机器人缺少联系人权限。不会影响核心消息功能，但无法解析发送者姓名。

其他日志位置

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

# All log files
ls -la ~/.openclaw/logs/

# Raw agent session records (tool calls, responses, etc.)
ls ~/.openclaw/agents/main/sessions/
# View specific session
cat ~/.openclaw/agents/main/sessions/<session-id>.json

测试工作流

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. 截图并检查日志以进行验证

测试 feishu_doc 工具

# 1. Focus input
agent-browser --session feishu-test press "/" && \
agent-browser --session feishu-test press "Backspace"

# 2. Type full doc 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

# 3. Send
agent-browser --session feishu-test press "Enter"

# 4. Wait and check logs
sleep 15 && tail -30 ~/.openclaw/logs/gateway.log