From da275823cd5591f858c3b1c98f9cb167dbf81998 Mon Sep 17 00:00:00 2001
From: Renu-Cybe <83443471@qq.com>
Date: Wed, 1 Apr 2026 04:22:59 +0800
Subject: [PATCH] docs: improve Browser Bridge troubleshooting guide

- Add step-by-step extension installation instructions
- Add post-installation verification checklist
- Add login requirements table by platform
- Add extension installation issues troubleshooting
- Add login state issues troubleshooting
- Add tool call warnings explanation (parameter validation warnings)
- Add verification commands for setup testing

These improvements are based on real-world troubleshooting experience
and help users quickly diagnose and resolve common setup issues.
---
 SKILL.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/SKILL.md b/SKILL.md
index 4b38d7a2..3dcb8f82 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -47,6 +47,38 @@ Browser commands require:
 
 Public API commands (`hackernews`, `v2ex`) need no browser.
 
+### Browser Bridge Extension Installation
+
+**Step-by-step installation:**
+
+1. **Open Chrome Extensions page**: Navigate to `chrome://extensions` in Chrome
+2. **Enable Developer Mode**: Toggle the "Developer mode" switch in the top-right corner
+3. **Load the extension**: Click "Load unpacked" button
+4. **Select extension directory**: Choose the `extension/` folder from your opencli installation:
+   - **npm global install**: `~/.openclaw/skills/opencli/extension` (OpenClaw users)
+   - **From source**: `<opencli-source-dir>/extension`
+5. **Verify installation**: The extension should appear as "OpenCLI" with status "Enabled"
+
+**Post-installation checklist:**
+
+| Step | Command/Action | Expected Result |
+|------|---------------|-----------------|
+| 1. Check public API | `opencli hackernews top --limit 5` | Returns top 5 HN stories |
+| 2. Check browser connection | `opencli doctor` | Shows "Browser Bridge: connected" |
+| 3. Test logged-in site | `opencli bilibili hot --limit 5` | Returns B站 hot videos (requires login) |
+
+**Login requirements by platform:**
+
+| Platform | Login Required | Notes |
+|----------|---------------|-------|
+| HackerNews | ❌ No | Public API |
+| V2EX | ❌ No (most commands) | Some commands like `daily`, `me` require login |
+| Bilibili | ✅ Yes | Log in at bilibili.com |
+| 知乎 | ✅ Yes | Log in at zhihu.com |
+| 小红书 | ✅ Yes | Log in at xiaohongshu.com |
+| Twitter/X | ✅ Yes | Log in at x.com |
+| 雪球 | ✅ Yes | Log in at xueqiu.com |
+
 ## Commands Reference
 
 ### Data Commands
@@ -877,3 +909,56 @@ ${{ index + 1 }}
 | `Target page context` error | Add `navigate:` step before `evaluate:` in YAML |
 | Empty table data | Check if evaluate returns correct data path |
 | Daemon issues | `curl localhost:19825/status` to check, `curl localhost:19825/logs` for extension logs |
+
+### Extension Installation Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Extension not appearing | Developer mode not enabled | Toggle "Developer mode" in `chrome://extensions` |
+| Wrong extension path | Incorrect directory selected | Use `~/.openclaw/skills/opencli/extension` (OpenClaw) or `<source>/extension` |
+| Extension shows errors | Corrupted extension files | Re-install opencli: `npm update -g @jackwener/opencli` |
+
+### Login State Issues
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| Commands return empty data | Not logged in to target site | Log in via Chrome before running commands |
+| "需要登录" errors | Session expired | Re-login in Chrome, retry command |
+| Commands work in browser but not CLI | Wrong Chrome profile | Ensure extension is installed in the same profile where you're logged in |
+
+### Tool Call Warnings
+
+If you see warnings like:
+```
+[agent/embedded] read tool called without path
+```
+
+**What this means:**
+- This is a **parameter validation warning**, not a functional error
+- Occurs when embedded agents (e.g., memory plugins, sub-agents) call tools with missing parameters
+- **Severity**: Low — does not affect core functionality
+
+**Common sources:**
+- MemOS auto-memory features
+- Sub-agent invocations
+- Background automation tasks
+
+**Action required:** None — this is informational only. If the warning appears frequently, check your plugin configurations, but it does not indicate a problem with opencli itself.
+
+### Verification Commands
+
+Use these commands to verify your setup:
+
+```bash
+# 1. Check daemon status
+curl localhost:19825/status
+
+# 2. Run diagnostics
+opencli doctor
+
+# 3. Test public API (no browser needed)
+opencli hackernews top --limit 5
+
+# 4. Test browser + login state
+opencli bilibili hot --limit 5   # Requires B站 login
+```