/feishu-e2e-test

name: feishu-e2e-test
description: Local E2E debug and test framework for clawd-feishu plugin development. Use when debugging message flow, testing bot responses, verifying Feishu web UI interactions, or performing end-to-end validation of the OpenClaw-Feishu integration during development.
allowed-tools: Bash(agent-browser:*)

Feishu E2E Test Framework

Local development testing using `agent-browser` CLI to interact with Feishu web app.

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

Important Notes

**Every time you modify extension code, you MUST restart OpenClaw Gateway for changes to take effect.**

# 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 Usage

Always use `--headed` mode so user can see the browser and help with login:

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

Feishu Web UI Tips

Feishu web has complex UI that makes direct clicking unreliable. Use these strategies:

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

Clicking on chat list items often misses or selects wrong item. Use global search:

# 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. Focus Input with "/" Key

After entering a chat, press "/" to focus the message input:

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

3. Type Characters One by One

The `type` command often fails with special characters. Use `press` for each character:

# 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. Chinese Characters Do NOT Work

**Chinese characters cannot be typed with `press` command.** Use English only:

# 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. Typing Spaces

Spaces must be quoted as `" "`:

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

6. Typing Long Strings Efficiently

Use a for loop to type URLs or long text:

# 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. Avoid JS eval on Feishu

Do NOT use `eval` to set input values - it can break the page:

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

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

8. Full URLs Work Better Than IDs

When testing document tools, send full URLs rather than just document IDs:

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

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

Verifying Tool Calls

Log Patterns

Monitor gateway logs to verify tool execution:

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

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** 读过了这个文档"

Common Errors

Permission Error (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.

Other Log Locations

# 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

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

Testing feishu_doc Tool

# 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