# ACTIVE.md - Syntax Library & Pre-Flight Checklist

**Read the relevant section BEFORE using any tool. This is your syntax reference.**

**Core Philosophy: Quality over speed. Thorough and correct beats fast and half-baked.**

---

## 📖 How to Use This File

1. **Identify the tool** you need to use
2. **Read that section completely** before writing any code
3. **Check the checklist** items one by one
4. **Verify against examples** - correct and wrong
5. **Execute only after validation**

---

## 🔧 `read` - Read File Contents

### Purpose
Read contents of text files or view images (jpg, png, gif, webp).

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_path` | string | **YES** | Path to the file (absolute or relative) |
| `offset` | integer | No | Line number to start from (1-indexed) |
| `limit` | integer | No | Maximum lines to read |

### Instructions
- **ALWAYS** use `file_path`, never `path`
- **ALWAYS** provide the full path
- Use `offset` + `limit` for files >100 lines
- Images are sent as attachments automatically
- Output truncated at 2000 lines or 50KB

### Correct Examples
```python
# Basic read
read({ file_path: "/root/.openclaw/workspace/ACTIVE.md" })

# Read with pagination
read({ 
  file_path: "/root/.openclaw/workspace/large_file.txt",
  offset: 1,
  limit: 50 
})

# Read from specific line
read({ 
  file_path: "/var/log/syslog",
  offset: 100,
  limit: 25 
})
```

### Wrong Examples
```python
# ❌ WRONG - 'path' is incorrect parameter name
read({ path: "/path/to/file" })

# ❌ WRONG - missing required file_path
read({ offset: 1, limit: 50 })

# ❌ WRONG - empty call
read({})
```

### Checklist
- [ ] Using `file_path` (not `path`)
- [ ] File path is complete
- [ ] Using `offset`/`limit` for large files if needed

---

## ✏️ `edit` - Precise Text Replacement

### Purpose
Edit a file by replacing exact text. The old_string must match exactly (including whitespace).

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_path` | string | **YES** | Path to the file |
| `old_string` | string | **YES** | Exact text to find and replace |
| `new_string` | string | **YES** | Replacement text |

### Critical Rules
1. **old_string must match EXACTLY** - including whitespace, newlines, indentation
2. **Parameter names are** `old_string` and `new_string` - NOT `oldText`/`newText`
3. **Both parameters required** - never provide only one
4. **Surgical edits only** - for precise changes, not large rewrites
5. **If edit fails 2+ times** - switch to `write` tool instead

### Instructions
1. Read the file first to see exact content
2. Copy the exact text you want to replace (including whitespace)
3. Provide both `old_string` and `new_string`
4. If edit fails, verify the exact match - or switch to `write`

### Correct Examples
```python
# Simple replacement
edit({
  file_path: "/root/.openclaw/workspace/config.txt",
  old_string: "DEBUG = false",
  new_string: "DEBUG = true"
})

# Multi-line replacement (preserve exact whitespace)
edit({
  file_path: "/root/.openclaw/workspace/script.py",
  old_string: """def old_function():
    return 42""",
  new_string: """def new_function():
    return 100"""
})

# Adding to a list
edit({
  file_path: "/root/.openclaw/workspace/ACTIVE.md",
  old_string: "- Item 3",
  new_string: """- Item 3
- Item 4"""
})
```

### Wrong Examples
```python
# ❌ WRONG - missing new_string
edit({ 
  file_path: "/path/file", 
  old_string: "text to replace" 
})

# ❌ WRONG - missing old_string
edit({ 
  file_path: "/path/file", 
  new_string: "replacement text" 
})

# ❌ WRONG - wrong parameter names (newText/oldText)
edit({ 
  file_path: "/path/file", 
  oldText: "old",
  newText: "new"
})

# ❌ WRONG - whitespace mismatch (will fail)
edit({
  file_path: "/path/file",
  old_string: "  indented",  # two spaces
  new_string: "    new"      # four spaces - but old didn't match exactly
})
```

### Recovery Strategy
```python
# If edit fails twice, use write instead:

# 1. Read the full file
content = read({ file_path: "/path/to/file" })

# 2. Modify content in your mind/code
new_content = content.replace("old", "new")

# 3. Rewrite entire file
write({
  file_path: "/path/to/file",
  content: new_content
})
```

### Checklist
- [ ] Using `old_string` and `new_string` (not newText/oldText)
- [ ] Both parameters provided
- [ ] old_string matches EXACTLY (copy-paste from read output)
- [ ] Considered if `write` would be better
- [ ] Plan to switch to `write` if this fails twice

---

## 📝 `write` - Create or Overwrite File

### Purpose
Write content to a file. Creates if doesn't exist, overwrites if it does.

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_path` | string | **YES*** | Path to the file |
| `path` | string | **YES*** | Alternative parameter name (skills legacy) |
| `content` | string | **YES** | Content to write |

*Use `file_path` for standard operations, `path` for skill files

### Critical Rules
1. **Overwrites entire file** - no partial writes
2. **Creates parent directories** automatically
3. **Must have complete content** ready before calling
4. **Use after 2-3 failed `edit` attempts** instead of continuing to fail

### When to Use
- Creating new files
- Rewriting entire file after failed edits
- Major refactors where most content changes
- When exact text matching for `edit` is too difficult

### Instructions
1. Have the COMPLETE file content ready
2. Double-check the file path
3. For skills: use `path` parameter (legacy support)
4. Verify content includes everything needed

### Correct Examples
```python
# Create new file
write({
  file_path: "/root/.openclaw/workspace/new_file.txt",
  content: "This is the complete content of the new file."
})

# Overwrite existing (after failed edits)
write({
  file_path: "/root/.openclaw/workspace/ACTIVE.md",
  content: """# ACTIVE.md - New Content

Complete file content here...
All sections included...
"""
})

# For skill files (uses 'path' instead of 'file_path')
write({
  path: "/root/.openclaw/workspace/skills/my-skill/SKILL.md",
  content: "# Skill Documentation..."
})
```

### Wrong Examples
```python
# ❌ WRONG - missing content
write({ file_path: "/path/file" })

# ❌ WRONG - missing path
write({ content: "text" })

# ❌ WRONG - partial content thinking it will append
write({ 
  file_path: "/path/file",
  content: "new line"  # This REPLACES entire file, not appends!
})
```

### Checklist
- [ ] Have COMPLETE content ready
- [ ] Using `file_path` (or `path` for skills)
- [ ] Aware this OVERWRITES entire file
- [ ] All content included in the call

---

## ⚡ `exec` - Execute Shell Commands

### Purpose
Execute shell commands with background continuation support.

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `command` | string | **YES** | Shell command to execute |
| `workdir` | string | No | Working directory (defaults to cwd) |
| `timeout` | integer | No | Timeout in seconds |
| `env` | object | No | Environment variables |
| `pty` | boolean | No | Run in pseudo-terminal (for TTY UIs) |
| `host` | string | No | Host: sandbox, gateway, or node |
| `node` | string | No | Node name when host=node |
| `elevated` | boolean | No | Run with elevated permissions |

### Critical Rules for Cron Scripts
1. **ALWAYS exit with code 0** - `sys.exit(0)`
2. **Never use exit codes 1 or 2** - these log as "exec failed"
3. **Use output to signal significance** - print for notifications, silent for nothing
4. **For Python scripts:** use `sys.exit(0)` not bare `exit()`

### Instructions
1. **For cron jobs:** Script must ALWAYS return exit code 0
2. Use `sys.exit(0)` explicitly at end of Python scripts
3. Use stdout presence/absence to signal significance
4. Check `timeout` for long-running commands

### Correct Examples
```python
# Simple command
exec({ command: "ls -la /root/.openclaw/workspace" })

# With working directory
exec({ 
  command: "python3 script.py",
  workdir: "/root/.openclaw/workspace/skills/my-skill"
})

# With timeout
exec({ 
  command: "long_running_task",
  timeout: 300
})

# Cron script example (MUST exit 0)
# In your Python script:
import sys

if significant_update:
    print("Notification: Important update found!")
    sys.exit(0)  # ✅ Output present = notification sent
else:
    sys.exit(0)  # ✅ No output = silent success
```

### Wrong Examples
```python
# ❌ WRONG - missing command
exec({ workdir: "/tmp" })

# ❌ WRONG - cron script with non-zero exit
# In Python script:
if no_updates:
    sys.exit(1)  # ❌ Logs as "exec failed" error!

if not important:
    sys.exit(2)  # ❌ Also logs as error, even if intentional!
```

### Python Cron Script Template
```python
#!/usr/bin/env python3
import sys

def main():
    # Do work here
    result = check_something()
    
    if result["significant"]:
        print("📊 Significant Update Found")
        print(result["details"])
        # Output will trigger notification
    
    # ALWAYS exit 0
    sys.exit(0)

if __name__ == "__main__":
    main()
```

### Checklist
- [ ] `command` provided
- [ ] **If cron script:** MUST `sys.exit(0)` always
- [ ] Using output presence for significance (not exit codes)
- [ ] Appropriate `timeout` set if needed
- [ ] `workdir` specified if not using cwd

---

## 🌐 `browser` - Browser Control

### Purpose
Control browser via OpenClaw's browser control server.

### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | **YES** | Action: status, start, stop, profiles, tabs, open, snapshot, screenshot, navigate, act, etc. |
| `profile` | string | No | "chrome" for extension relay, "openclaw" for isolated |
| `targetUrl` | string | No | URL to navigate to |
| `targetId` | string | No | Tab target ID from snapshot |
| `request` | object | No | Action request details (for act) |
| `refs` | string | No | "role" or "aria" for snapshot refs |

### Critical Rules
1. **Chrome extension must be attached** - User clicks OpenClaw toolbar icon
2. **Use `profile: "chrome"`** for extension relay
3. **Check gateway status** first if unsure
4. **Fallback to curl** if browser unavailable

### Instructions
1. Verify gateway is running: `openclaw gateway status`
2. Ensure Chrome extension is attached (badge ON)
3. Use `profile: "chrome"` for existing tabs
4. Use `snapshot` to get current page state
5. Use `act` with refs from snapshot for interactions

### Correct Examples
```python
# Check status first
exec({ command: "openclaw gateway status" })

# Open a URL
browser({ 
  action: "open", 
  targetUrl: "https://example.com",
  profile: "chrome"
})

# Get page snapshot
browser({ 
  action: "snapshot",
  profile: "chrome",
  refs: "aria"
})

# Click an element (using ref from snapshot)
browser({ 
  action: "act",
  profile: "chrome",
  request: {
    kind: "click",
    ref: "e12"  # ref from snapshot
  }
})

# Type text
browser({
  action: "act",
  profile: "chrome",
  request: {
    kind: "type",
    ref: "e5",
    text: "Hello world"
  }
})

# Screenshot
browser({
  action: "screenshot",
  profile: "chrome",
  fullPage: true
})
```

### Fallback When Browser Unavailable
```python
# If browser not available, use curl instead
exec({ command: "curl -s https://example.com" })

# For POST requests
exec({ 
  command: 'curl -s -X POST -H "Content-Type: application/json" -d \'{"key":"value"}\' https://api.example.com'
})
```

### Checklist
- [ ] Gateway running (`openclaw gateway status`)
- [ ] Chrome extension attached (user clicked icon)
- [ ] Using `profile: "chrome"` for relay
- [ ] Using refs from snapshot for interactions
- [ ] Fallback plan (curl) if browser fails

---

## ⏰ `openclaw cron` - Scheduled Tasks

### Purpose
Manage scheduled tasks via OpenClaw's cron system.

### CLI Commands
| Command | Purpose |
|---------|---------|
| `openclaw cron list` | List all cron jobs |
| `openclaw cron add` | Add a new job |
| `openclaw cron remove <name>` | Remove a job |
| `openclaw cron enable <name>` | Enable a job |
| `openclaw cron disable <name>` | Disable a job |

### Critical Rules
1. **Use `--cron`** for the schedule expression (NOT `--schedule`)
2. **No `--enabled` flag** - jobs enabled by default
3. **Use `--disabled`** if you need job disabled initially
4. **Scripts MUST always exit with code 0**

### Parameters for `cron add`
| Parameter | Description |
|-----------|-------------|
| `--name` | Job identifier (required) |
| `--cron` | Cron expression like "0 11 * * *" (required) |
| `--message` | Task description |
| `--model` | Model to use for this job |
| `--channel` | Channel for output (e.g., "telegram:12345") |
| `--system-event` | For main session background jobs |
| `--disabled` | Create as disabled |

### Instructions
1. Always check `openclaw cron list` first when user asks about cron
2. Use `--cron` for the time expression
3. Ensure scripts exit with code 0
4. Use appropriate channel for notifications

### Correct Examples
```bash
# Add daily monitoring job
openclaw cron add \
  --name "monitor-openclaw" \
  --cron "0 11 * * *" \
  --message "Check OpenClaw repo for updates" \
  --channel "telegram:1544075739"

# List all jobs
openclaw cron list

# Remove a job
openclaw cron remove "monitor-openclaw"

# Disable temporarily
openclaw cron disable "monitor-openclaw"
```

### Wrong Examples
```bash
# ❌ WRONG - using --schedule instead of --cron
openclaw cron add --name "job" --schedule "0 11 * * *"

# ❌ WRONG - using --enabled (not a valid flag)
openclaw cron add --name "job" --cron "0 11 * * *" --enabled

# ❌ WRONG - script with exit code 1
# (In the script being called)
if error_occurred:
    sys.exit(1)  # This will log as "exec failed"
```

### Checklist
- [ ] Using `--cron` (not `--schedule`)
- [ ] No `--enabled` flag used
- [ ] Script being called exits with code 0
- [ ] Checked `openclaw cron list` first

---

## 🔍 General Workflow Rules

### 1. Discuss Before Building
- [ ] Confirmed approach with user?
- [ ] User said "yes do it" or equivalent?
- [ ] Wait for explicit confirmation, even if straightforward

### 2. Search-First Error Handling
```
Error encountered:
  ↓
Check knowledge base first (memory files, TOOLS.md)
  ↓
Still stuck? → Web search for solutions
  ↓
Simple syntax error? → Fix immediately (no search needed)
```

### 3. Verify Tools Exist
Before using any tool, ensure it exists:
```bash
openclaw tools list  # Check available tools
```

**Known undocumented:** `searx_search` is documented in skills but NOT enabled. Use `curl` to SearXNG instead.

### 4. Memory Updates
After completing work:
- `memory/YYYY-MM-DD.md` - Daily log of what happened
- `MEMORY.md` - Key learnings (main session only)
- `SKILL.md` - Tool/usage patterns for skills
- `ACTIVE.md` - If new mistake pattern discovered

### 5. Take Your Time
- [ ] Quality over speed
- [ ] Thorough and correct beats fast and half-baked
- [ ] Verify parameters before executing
- [ ] Check examples in this file

---

## 🚨 My Common Mistakes Reference

| Tool | My Common Error | Correct Approach |
|------|-----------------|------------------|
| `read` | Using `path` instead of `file_path` | Always `file_path` |
| `edit` | Using `newText`/`oldText` instead of `new_string`/`old_string` | Use `_string` suffix |
| `edit` | Partial edit, missing one param | Always provide BOTH |
| `edit` | Retrying 3+ times on failure | Switch to `write` after 2 failures |
| `exec` | Non-zero exit codes for cron | Always `sys.exit(0)` |
| `cron` | Using `--schedule` | Use `--cron` |
| `cron` | Using `--enabled` flag | Not needed (default enabled) |
| General | Acting without confirmation | Wait for explicit "yes" |
| General | Writing before discussing | Confirm approach first |
| General | Rushing for speed | Take time, verify |
| Tools | Using tools not in `openclaw tools list` | Verify availability first |

---

## 📋 Quick Reference: All Parameter Names

| Tool | Required Parameters | Optional Parameters |
|------|---------------------|---------------------|
| `read` | `file_path` | `offset`, `limit` |
| `edit` | `file_path`, `old_string`, `new_string` | - |
| `write` | `file_path` (or `path`), `content` | - |
| `exec` | `command` | `workdir`, `timeout`, `env`, `pty`, `host`, `node` |
| `browser` | `action` | `profile`, `targetUrl`, `targetId`, `request`, `refs` |

---

## 📚 Reference Files Guide

| File | Purpose | When to Read |
|------|---------|--------------|
| `SOUL.md` | Who I am | Every session start |
| `USER.md` | Who I'm helping | Every session start |
| `AGENTS.md` | Workspace rules | Every session start |
| `ACTIVE.md` | This file - tool syntax | **BEFORE every tool use** |
| `TOOLS.md` | Tool patterns, SSH hosts, preferences | When tool errors occur |
| `SKILL.md` | Skill-specific documentation | Before using a skill |
| `MEMORY.md` | Long-term memory | Main session only |

---

## 🆘 Emergency Recovery

### When `edit` keeps failing
```python
# 1. Read full file
file_content = read({ file_path: "/path/to/file" })

# 2. Calculate changes mentally or with code
new_content = file_content.replace("old_text", "new_text")

# 3. Write complete file
write({
  file_path: "/path/to/file",
  content: new_content
})
```

### When tool parameters are unclear
1. Check this ACTIVE.md section for that tool
2. Check `openclaw tools list` for available tools
3. Search knowledge base for previous usage
4. Read the file you need to modify first

---

**Last Updated:** 2026-02-05

**Check the relevant section BEFORE every tool use**

**Remember: Quality over speed. Verify before executing. Get it right.**