task-experience-summaries

OpenClaw 任务的经验总结，包括常见安装问题、故障排除步骤以及软件包、配置和工具的最佳实践。当遇到安装问题、面临未知错误消息或需要包名称和配置方法指导时使用。也可以在记录新经验以供将来参考时使用。

## 概述（中文）

OpenClaw 任务的经验总结，包括常见安装问题、故障排除步骤以及软件包、配置和工具的最佳实践。当遇到安装问题、面临未知错误消息或需要包名称和配置方法指导时使用。也可以在记录新经验以供将来参考时使用。

## 原文

# Task Experience Summaries

## Overview

This skill provides curated experience summaries from real OpenClaw tasks, including:

- Installation/packaging problems and solutions
- Common error messages and root causes
- Package search and discovery methods
- Configuration patterns and environment setups
- Tool-specific troubleshooting steps
- Best practices for documenting new experiences

Each entry includes: Problem → Solutions → Key Lessons → Prevention Steps.

## Common Installation Packages

### ClawHub CLI

**Purpose:** Search, install, update, and publish OpenClaw skills from clawhub.com.

**Installation:**
```bash
npm install -g clawhub
```

**Usage:**
```bash
# Search for skills
clawhub search "keyword"

# Install a skill
clawhub install "skill-name"

# List installed skills
clawhub list

# Publish a new skill (when ready)
clawhub publish "skill-directory"
```

**Authentication:**
- Token: `clh_<token>`
- Username: `@<username>`
- Available at: https://clawhub.ai

### Tavily Search

**Purpose:** AI-optimized web search via Tavily API.

**Configuration:**
```bash
# Set environment variable
set TAVILY_API_KEY=your-api-key-here
```

**Usage:**
- Search query: `web_search` tool
- API key location: `<skill-dir>/README_CONFIG.md`
- Quality: High relevance for AI agents

---

## Troubleshooting Categories

### 1. Package Installation Issues

#### Problem: npm 404 Not Found

**Scenario:** Install command fails with "404 Not Found"

**Solutions:**
1. Check package name spelling
2. Search ClawHub: `clawhub search "keyword"`
3. Try npm search: `npm search "keyword"`
4. Verify the package exists in npm registry

**Typical Fixes:**
- Wrong package name (e.g., `tavily-search` → correct: `tavily-mcp`)
- Package removed or renamed
- Typo in command

**Key Lesson:** Always verify package existence before installation. Use search tools.

#### Problem: Windows Permission EEXIST Error

**Scenario:** Installation fails with "EEXIST: file already exists"

**Solution:**
```bash
npm i -g clawhub --force
```

**Root Cause:** Old version files remain, blocking installation

**Prevention:** Use `--force` for global installations on Windows if issues occur

#### Problem: Unknown Package Name

**Scenario Package not found in npm registry**

**Solutions:**
1. Use ClawHub search: `clawhub search "keyword"`
2. Try broader search terms
3. Check if the skill is hosted on ClawHub (OpenClaw's official registry)

**Example:**
```
Initial attempt: npm install "find-skills" → 404
Solution: clawhub search "find-skills" → Found "find-skills v0.1.0"
Result: clawhub install "find-skills" → Success
```

**Key Lesson:** ClawHub is the first place to check for OpenClaw skills

### 2. Configuration Issues

#### Environment Variables

**Standard Pattern:**
```bash
# SET in current session
set ENV_VAR=value

# For persistent settings, add to shell config
# (e.g., .bashrc, .zshrc, PowerShell profile)
```

**Common Variables:**
- `TAVILY_API_KEY` - For web search tools
- `OPENAI_API_KEY` - If needed for OpenAI-based skills
- Custom credentials for specific tools

**Verification:**
```bash
echo $TAVILY_API_KEY  # Unix-like
echo %TAVILY_API_KEY% # PowerShell/CMD
```

### 3. Tool-Specific Issues

#### OpenClaw Browser Extension

**Symptom:** "tab not found" errors after browser operations

**Solutions:**
1. Restart OpenClaw Gateway (OpenClaw.app → Restart)
2. Keep Chrome extension badge ON (not OFF)
3. Do not close browser tab between operations
4. Reseat connection: Open Extension → Attach Tab → Badge ON

**Best Practice:**
- Browser tool is for one-time operations or screenshots
- Not suitable for long-lived automated sessions
- Direct browser interaction is more reliable for persistent needs

#### Browser Profile Issues

**Symptom:** Multiple profiles causing conflicts

**Solutions:**
- Use `--profile=chrome` for managed Chrome browser
- Use `--profile=openclaw` for isolated browser
- Test with clean profile if issues persist

**Status Check:**
```bash
openclaw gateway status
```

---

## Problem-Solving Workflow

### Step 1: Identify the Category

Determine if the issue belongs to:
- Installation problems
- Configuration issues
- Tool-specific malfunctions
- Package discovery
- Platform-specific behavior (Windows/Linux/macOS)

### Step 2: Search the Summary

Use the tables and categorized entries above:
- Match symptoms to category
- Review associated solutions
- Try recommended fixes

### Step 3: Test Solutions

Apply suggested fixes in order:
1. Most common/simplest solution first
2. Platform-specific fixes second
3. Advanced configurations third

### Step 4: Document New Experiences

**When to Document:**
- Successfully resolved an unknown problem
- Discovered a pattern or workaround
- Learned a configuration trick
- Found that a documented solution works differently

**How to Document:**
1. Record the problem clearly
2. Note the solution steps
3. Include platform-specific details
4. Add prevention/prevention steps
5. Update relevant section in this SKILL.md

**Template for New Entry:**
```markdown
### Problem: [Clear description]

**Scenario:** [Context where problem occurs]

**Solution:** [Step-by-step resolution]

**Root Cause:** [Why this happens]

**Prevention:** [How to avoid]

**Platform Notes:** [If platform-specific]
```

### Step 5: Iterate and Refine

Review after using the skill:
- Are entries clear and actionable?
- Are symptoms and solutions well-matched?
- Is formatting consistent?
- Any missing common issues?

---

## Quick Reference Table

| Issue Type | Symptoms | Primary Tool | Key Command |
|-----------|----------|--------------|-------------|
| Package not found | 404, npm errors | npm, ClawHub | `clawhub search "keyword"` |
| Permission errors | EEXIST, access denied | npm install | `--force` flag |
| Configuration missing | Tool fails | Environment variables | `set VAR=value` |
| Browser connection | Tab not found | Browser tools | Restart Gateway + Badge ON |
| Unknown package | Cannot install | clawhub list | `clawhub install "name"` |

---

## Best Practices

1. **Search Before Guessing:** Always use search tools first
2. **Document Solutions:** Write down everything you learn
3. **Categorize Issues:** Group by type for easy lookup
4. **Platform Notes:** Track Windows/macOS/Linux differences
5. **Prevention Over Cure:** Add prevention steps to avoid recurrence
6. **Keep It Practical:** Focus on actionable steps, not theory

---

## Example Use Cases

### Example 1: Installing a New Skill

```bash
# User asks: "I need a weather skill for checking forecasts"

# Step 1: Search
clawhub search "weather"

# Step 2: Identify candidate
Found: "weather v1.0" - Get current weather and forecasts (no API key required)

# Step 3: Install
clawhub install "weather"

# Step 4: Configure (if needed)
# Check README_CONFIG.md for required environment variables

# Step 5: Use
# Use web_search tool with query: "weather today"
```

### Example 2: Troubleshooting Browser Issues

```bash
# Symptom: Browser tool reports "tab not found"

# Step 1: Restart Gateway (first fix)
OpenClaw.app → Restart

# Step 2: Check extension
✓ Badge indicator should be ON
✓ Running state
✓ CDP Ready (Chrome DevTools Protocol)

# Step 3: Reattach if needed
Click OpenClaw extension icon → Attach tab → Badge ON

# Step 4: Verify
Try browser open → snapshot
```

### Example 3: Finding Unknown Package

```bash
# Symptom: "I need an RSS feed parser" - package unknown

# Step 1: ClawHub search
clawhub search "rss"

# Step 2: Identify
Found: "rss-parser skill v0.5.0" with description "Parse RSS feeds"

# Step 3: Install
clawhub install "rss-parser"

# Result: Success
```

---

## Notes

- All entries are based on actual resolved issues
- Platform-specific behaviors are noted when applicable
- Configuration details refer to current workspace setup
- For newer issues, always consult official doc