feat: add new skills for context7-docs, cron-scheduling, excel-operations, hook-management, mcp-integration, notebook-edit, pdf-processing, and security-best-practices
This commit is contained in:
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: context7-docs
|
||||
description: Fetch up-to-date library documentation and code examples using Context7
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when the user asks to:
|
||||
- Look up library APIs (React, Next.js, Supabase, etc.)
|
||||
- Get current code examples for a specific library version
|
||||
- Find documentation for configuration or setup steps
|
||||
- Resolve ambiguous API questions with authoritative sources
|
||||
- Avoid outdated training data or hallucinated APIs
|
||||
|
||||
## Prerequisites
|
||||
- `npx` must be available (Node.js)
|
||||
- Internet connection (Context7 fetches latest docs)
|
||||
- No API key needed for basic usage (public mode)
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Find the library ID (if not known)
|
||||
If the user mentions a library name (e.g., "React", "Supabase"), first resolve to Context7 library ID:
|
||||
|
||||
```bash
|
||||
npx ctx7 library <library-name>
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
npx ctx7 library react
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
1. Title: React
|
||||
Context7-compatible library ID: /reactjs/react.dev
|
||||
...
|
||||
```
|
||||
|
||||
Pick the best match (usually highest benchmark score or official source).
|
||||
|
||||
### 2. Retrieve documentation
|
||||
Use the library ID to fetch relevant docs:
|
||||
|
||||
```bash
|
||||
npx ctx7 docs <library-id> --query "<user question>"
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
npx ctx7 docs /reactjs/react.dev --query "how to use useEffect with empty dependency array"
|
||||
```
|
||||
|
||||
### 3. Present results
|
||||
Context7 returns relevant code snippets and explanations. Structure the answer:
|
||||
- Brief summary of the solution
|
||||
- Code example(s) directly from docs
|
||||
- Link to full docs if needed
|
||||
|
||||
## Library ID Shortcuts
|
||||
Once you know the library ID, use it directly in prompts:
|
||||
|
||||
User: "How do I set up Next.js middleware? use context7"
|
||||
|
||||
You can parse "use context7" as a signal to call Context7 with:
|
||||
- library: inferred or ask user
|
||||
- query: the full question
|
||||
|
||||
## Common Libraries (pre-resolved)
|
||||
|
||||
| Library | Context7 ID |
|
||||
|---------|-------------|
|
||||
| React | /reactjs/react.dev or /websites/react_dev |
|
||||
| Next.js | /vercel/next.js |
|
||||
| Supabase | /supabase/supabase |
|
||||
| Vue | /vuejs/core |
|
||||
| Angular | /angular/core |
|
||||
| Node.js | /nodejs/node |
|
||||
| Express | /expressjs/express |
|
||||
| FastAPI | /tiangolo/fastapi |
|
||||
| Django | /django/django |
|
||||
| PostgreSQL | /postgres/postgres |
|
||||
| MongoDB | /mongodb/docs |
|
||||
|
||||
You can cache these mappings for faster lookup.
|
||||
|
||||
## Examples
|
||||
|
||||
<Good>
|
||||
User: "Implement basic authentication with Supabase"
|
||||
Assistant:
|
||||
1. Resolve library: `npx ctx7 library supabase` → /supabase/supabase
|
||||
2. Fetch docs: `npx ctx7 docs /supabase/supabase --query "basic email/password authentication"`
|
||||
3. Return code example from Context7 output
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
Skipping library resolution and guessing API from memory (may be outdated).
|
||||
</Bad>
|
||||
|
||||
## Tips
|
||||
|
||||
- Always verify the returned code matches the user's version if specified (Context7 auto-detects version from query)
|
||||
- If results are empty, try rephrasing the query or different library ID
|
||||
- For version-specific questions, include version in query: "Next.js 14 middleware"
|
||||
- Cache library IDs after first lookup to reduce API calls
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Library not found**: Try alternative names or check spelling
|
||||
- **No docs returned**: Query might be too vague; break into smaller questions
|
||||
- **Network error**: Retry once, then fall back to general knowledge (with disclaimer)
|
||||
|
||||
## Verification
|
||||
- [ ] Library ID is correct (from `ctx7 library` output)
|
||||
- [ ] Query clearly describes the needed information
|
||||
- [ ] Returned code is complete and runnable
|
||||
- [ ] Version matches user's context if specified
|
||||
|
||||
## Advanced: MCP Mode (Future)
|
||||
If OpenClaw adds MCP client support, you can register Context7 MCP server:
|
||||
```
|
||||
https://mcp.context7.com/mcp
|
||||
```
|
||||
With header `CONTEXT7_API_KEY` if you have one. Then use `ctx7` tools directly without shell calls.
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
name: cron-scheduling
|
||||
description: Schedule automated tasks with cron expressions or intervals using OpenClaw's cron system
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when the user asks to:
|
||||
- Run periodic checks (every hour, daily, weekly)
|
||||
- Schedule one-time future tasks
|
||||
- Automate recurring reports or backups
|
||||
- Set up monitoring alerts
|
||||
- Create time-based triggers
|
||||
|
||||
## Cron Basics
|
||||
|
||||
OpenClaw uses standard cron expressions:
|
||||
```
|
||||
* * * * *
|
||||
│ │ │ │ │
|
||||
│ │ │ │ └── Day of week (0-7, 0= Sunday)
|
||||
│ │ │ └──── Month (1-12)
|
||||
│ │ └────── Day of month (1-31)
|
||||
│ └──────── Hour (0-23)
|
||||
└────────── Minute (0-59)
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
- `0 * * * *` — every hour at minute 0
|
||||
- `30 3 * * *` — daily at 3:30 AM
|
||||
- `0 9 * * 1` — every Monday at 9:00 AM
|
||||
- `*/15 * * * *` — every 15 minutes
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Create a scheduled job
|
||||
```bash
|
||||
cron add \
|
||||
--name "daily-backup" \
|
||||
--schedule "0 2 * * *" \
|
||||
--task "clawteam task create backup 'Database backup' -o backup-agent"
|
||||
```
|
||||
|
||||
### 2. List scheduled jobs
|
||||
```bash
|
||||
cron list
|
||||
cron list --include-disabled true
|
||||
```
|
||||
|
||||
### 3. Manage jobs
|
||||
```bash
|
||||
# Disable (keep config)
|
||||
cron update --job-id <id> --enabled false
|
||||
|
||||
# Enable
|
||||
cron update --job-id <id> --enabled true
|
||||
|
||||
# Remove
|
||||
cron remove --job-id <id>
|
||||
```
|
||||
|
||||
### 4. Run manually (for testing)
|
||||
```bash
|
||||
cron run --job-id <id>
|
||||
```
|
||||
|
||||
### 5. View job history
|
||||
```bash
|
||||
cron runs --job-id <id> --limit 10
|
||||
```
|
||||
|
||||
## Job Configuration Options
|
||||
|
||||
| Flag | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `--name` | Human-readable name | "Health check" |
|
||||
| `--schedule` | Cron expression | "*/5 * * * *" |
|
||||
| `--task` | Command to execute | "oh -p 'Check system'" |
|
||||
| `--timezone` | IANA timezone | "Asia/Ho_Chi_Minh" |
|
||||
| `--enabled` | Start enabled/disabled | true/false |
|
||||
|
||||
## Advanced Scheduling
|
||||
|
||||
### Interval-based (every N minutes/hours)
|
||||
```bash
|
||||
cron add \
|
||||
--name "ping-every-10m" \
|
||||
--schedule-kind every \
|
||||
--every-ms 600000 \
|
||||
--task "oh -p 'Ping service'"
|
||||
```
|
||||
|
||||
### One-time future run
|
||||
```bash
|
||||
cron add \
|
||||
--name "deploy-at-noon" \
|
||||
--schedule-kind at \
|
||||
--at "2026-04-09T12:00:00Z" \
|
||||
--task "oh -p 'Deploy v2'"
|
||||
```
|
||||
|
||||
### Random jitter (avoid thundering herd)
|
||||
```bash
|
||||
cron add \
|
||||
--schedule-kind cron \
|
||||
--expr "*/10 * * * *" \
|
||||
--stagger-ms 120000 # ±2 min random
|
||||
```
|
||||
|
||||
## Task Payloads
|
||||
|
||||
### Simple command
|
||||
```bash
|
||||
--task "oh -p 'Check logs'"
|
||||
```
|
||||
|
||||
### With context
|
||||
```bash
|
||||
--task "oh -p 'Check logs' --contextMessages 5"
|
||||
```
|
||||
|
||||
### Agent turn (new conversation)
|
||||
```bash
|
||||
--task '{"kind":"agentTurn","message":"Check system health"}'
|
||||
```
|
||||
|
||||
### System event (inject into main session)
|
||||
```bash
|
||||
--task '{"kind":"systemEvent","text":"/healthcheck"}'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Descriptive names**: "daily-backup" not "job1"
|
||||
- **Error alerts**: Configure cron failure alerts (`--failure-alert`)
|
||||
- **Logging**: Ensure tasks have `--verbose` or logging enabled
|
||||
- **Test manually**: `cron run` before relying on schedule
|
||||
- **Avoid overlap**: Ensure tasks finish before next run (use `--timeout`)
|
||||
|
||||
## Examples
|
||||
|
||||
<Good>
|
||||
Daily health check at 2 AM:
|
||||
```bash
|
||||
cron add \
|
||||
--name "nightly-health" \
|
||||
--schedule "0 2 * * *" \
|
||||
--timezone "Asia/Ho_Chi_Minh" \
|
||||
--task "oh -p 'Run full healthcheck' --output-format json" \
|
||||
--failure-alert '{"channel":"alerts","to":"#devops"}'
|
||||
```
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
Running backup every minute without timeout — can overlap and cause issues.
|
||||
</Bad>
|
||||
|
||||
## Monitoring
|
||||
|
||||
Check cron status:
|
||||
```bash
|
||||
cron status
|
||||
```
|
||||
|
||||
View recent runs:
|
||||
```bash
|
||||
cron runs --limit 20
|
||||
```
|
||||
|
||||
Failed runs trigger alerts if configured.
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] Cron expression is correct (use crontab.guru to verify)
|
||||
- [ ] Task command works manually (`cron run`)
|
||||
- [ ] Timezone is set correctly
|
||||
- [ ] Failure alerts configured for critical jobs
|
||||
- [ ] Overlap is prevented (task duration < interval)
|
||||
- [ ] Job history shows successful runs
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: excel-operations
|
||||
description: Read, write, and manipulate Excel (.xlsx) and CSV files
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when the user asks to:
|
||||
- Read data from Excel or CSV files
|
||||
- Create new spreadsheets
|
||||
- Update existing spreadsheet data
|
||||
- Perform calculations or data transformations
|
||||
- Export data to CSV/Excel format
|
||||
- Validate spreadsheet structure
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Identify the file
|
||||
Determine file path and format (.xlsx, .csv, .tsv).
|
||||
|
||||
### 2. Read the data
|
||||
|
||||
OpenClaw's `read` is for text files. For Excel/CSV:
|
||||
|
||||
**For CSV** (plain text):
|
||||
```bash
|
||||
read path/to/data.csv
|
||||
```
|
||||
|
||||
**For .xlsx** (binary): Use Python or other tools:
|
||||
```bash
|
||||
python -c "
|
||||
import pandas as pd, json, sys;
|
||||
df = pd.read_excel('data.xlsx');
|
||||
print(df.to_json(orient='records'))
|
||||
"
|
||||
```
|
||||
|
||||
Or install `xlsx2csv` and convert first:
|
||||
```bash
|
||||
xlsx2csv data.xlsx temp.csv
|
||||
read temp.csv
|
||||
```
|
||||
|
||||
### 3. Process the data
|
||||
- Parse into structured format (list of objects, 2D array)
|
||||
- Validate headers/columns if needed
|
||||
- Perform transformations (filter, map, aggregate)
|
||||
|
||||
### 4. Write results
|
||||
|
||||
**For CSV**:
|
||||
```bash
|
||||
write output.csv --data "$csv_string"
|
||||
```
|
||||
|
||||
**For .xlsx**: Use Python:
|
||||
```bash
|
||||
python -c "
|
||||
import pandas as pd, json, sys;
|
||||
data = json.loads(sys.argv[1]);
|
||||
pd.DataFrame(data).to_excel('output.xlsx', index=False)
|
||||
" "$structured_data"
|
||||
```
|
||||
|
||||
## Supported Formats
|
||||
- **.xlsx** (Excel Open XML) — full support for sheets, formulas, formatting
|
||||
- **.csv** (Comma-separated) — plain text, delimiter detection
|
||||
- **.tsv** (Tab-separated) — tab delimiter
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Read specific sheet
|
||||
```bash
|
||||
read file.xlsx --sheet "Sheet2"
|
||||
```
|
||||
|
||||
### Read with range
|
||||
```bash
|
||||
read file.xlsx --range "A1:D100"
|
||||
```
|
||||
|
||||
### Write with formatting
|
||||
```bash
|
||||
write report.xlsx \
|
||||
--data "$table" \
|
||||
--header true \
|
||||
--autofit columns
|
||||
```
|
||||
|
||||
### Append to existing file
|
||||
```bash
|
||||
write file.xlsx --data "$new_rows" --append true
|
||||
```
|
||||
|
||||
## Data Structures
|
||||
|
||||
**Reading returns**:
|
||||
```json
|
||||
{
|
||||
"headers": ["Name", "Email", "Score"],
|
||||
"rows": [
|
||||
{"Name": "Alice", "Email": "a@example.com", "Score": 95},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Writing accepts**:
|
||||
- JSON array of objects
|
||||
- 2D array (array of arrays)
|
||||
- CSV string (if format=csv)
|
||||
|
||||
## Examples
|
||||
|
||||
<Good>
|
||||
User: "Tạo báo cáo điểm từ scores.csv"
|
||||
Assistant:
|
||||
1. Đọc scores.csv
|
||||
2. Tính toán điểm trung bình, xếp loại
|
||||
3. Ghi vào report.xlsx với định dạng đẹp
|
||||
4. Trả về đường dẫn file và tóm tắt kết quả
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
Ghi đè file gốc mà không backup, không thông báo.
|
||||
</Bad>
|
||||
|
||||
## Error Handling
|
||||
- **File not found**: Kiểm tra đường dẫn, dùng `glob` để tìm
|
||||
- **Format mismatch**: Đảm bảo file đúng định dạng, kiểm tra extension
|
||||
- **Large files**: Có thể cần chunk processing, kiểm tra memory limits
|
||||
- **Corrupted data**: Catch parse errors, report specific row/column
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] File exists and is readable
|
||||
- [ ] Format matches extension
|
||||
- [ ] Headers are present and correct
|
||||
- [ ] Data types are correct (numbers, dates, strings)
|
||||
- [ ] No missing values in required columns
|
||||
- [ ] Output file is well-formed and complete
|
||||
@@ -0,0 +1,136 @@
|
||||
---
|
||||
name: hook-management
|
||||
description: Implement lifecycle hooks (PreToolUse/PostToolUse) using OpenClaw's existing tools and config
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when you need to:
|
||||
- Add validation before dangerous tools (exec, write, edit)
|
||||
- Audit/log all tool usage
|
||||
- Enforce custom security policies
|
||||
- Track costs/metrics around tool calls
|
||||
- Transform tool outputs before they reach the model
|
||||
|
||||
**Note**: OpenClaw does not have native PreToolUse/PostToolUse hooks. This skill shows you how to achieve similar effects using available mechanisms.
|
||||
|
||||
## Approach 1: Permission Mode + Rules (Built-in)
|
||||
|
||||
OpenClaw already has a permission system. Use it:
|
||||
|
||||
### Set permission mode
|
||||
```bash
|
||||
# Ask before every write/exec (default safe)
|
||||
gateway config set tools.exec.security full
|
||||
|
||||
# Or use plan mode to block all writes
|
||||
# (requires implementing plan_mode toggle)
|
||||
```
|
||||
|
||||
### Path-level rules in config
|
||||
Edit `openclaw.json`:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"path_rules": [
|
||||
{ "pattern": "**/secrets/**", "allow": false },
|
||||
{ "pattern": "**/*.key", "allow": false }
|
||||
],
|
||||
"denied_commands": ["rm -rf /", "DROP TABLE *", "format c:"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Approach 2: Wrapper Scripts (Shell Proxy)
|
||||
|
||||
Create wrapper scripts that add validation/logging:
|
||||
|
||||
### Example: Safe exec wrapper
|
||||
```bash
|
||||
# ~/.openclaw/wrappers/exec-safe
|
||||
#!/bin/bash
|
||||
# PreToolUse validation
|
||||
CMD="$1"
|
||||
if echo "$CMD" | grep -qE "(rm -rf|dd if=|mkfs)"; then
|
||||
echo "ERROR: Dangerous command blocked: $CMD" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Audit log
|
||||
echo "$(date -Iseconds) USER EXEC: $CMD" >> ~/.openclaw/logs/exec-audit.log
|
||||
|
||||
# Execute
|
||||
exec /usr/lib/openclaw/tools/exec.real "$@"
|
||||
```
|
||||
|
||||
Then configure OpenClaw to use the wrapper instead of the built-in exec tool.
|
||||
|
||||
## Approach 3: Plugin Interception (If Plugin System Supports)
|
||||
|
||||
If OpenClaw plugins can intercept tool calls:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "audit-plugin",
|
||||
"version": "1.0.0",
|
||||
"preToolUse": {
|
||||
"command": "audit-log",
|
||||
"priority": 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Check plugin docs** to see if `preToolUse`/`postToolUse` are supported.
|
||||
|
||||
## Approach 4: Custom Agent with Restricted Tools
|
||||
|
||||
Spawn a subagent with limited tool set:
|
||||
|
||||
```bash
|
||||
clawteam spawn tmux openclaw \
|
||||
--agent-type restricted \
|
||||
--tools "read,write,web_search" # no exec, no dangerous tools
|
||||
```
|
||||
|
||||
## Common Use Cases & Solutions
|
||||
|
||||
### Audit logging all tool calls
|
||||
- **Solution**: Wrapper scripts that log to file
|
||||
- Or use OpenClaw's built-in logging if available
|
||||
|
||||
### Block dangerous commands
|
||||
- **Solution**: `denied_commands` in config
|
||||
- Or wrapper validation
|
||||
|
||||
### Rate limiting
|
||||
- **Solution**: Track in session memory, check before allowing
|
||||
- No built-in — implement in custom plugin/agent
|
||||
|
||||
### Cost tracking
|
||||
- **Solution**: Parse logs, aggregate token usage
|
||||
- OpenClaw may already log token counts
|
||||
|
||||
### Input sanitization
|
||||
- **Solution**: Pre-process arguments in wrapper
|
||||
- Or validate in agent logic before calling tool
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] Hooks/validation are actually triggered
|
||||
- [ ] Dangerous operations are blocked as intended
|
||||
- [ ] Audit logs capture necessary details (who, what, when)
|
||||
- [ ] No performance degradation (wrappers are fast)
|
||||
- [ ] Rules don't interfere with normal operations
|
||||
- [ ] Fail open/closed appropriately (security vs availability)
|
||||
|
||||
## Limitations
|
||||
|
||||
- No native hook priority system — order depends on wrapper chain
|
||||
- No automatic hook discovery — manual registration needed
|
||||
- Wrapper approach requires maintaining extra scripts
|
||||
- Not as elegant as built-in hook system
|
||||
|
||||
## Future: Request Native Hooks
|
||||
|
||||
If hooks are critical, consider:
|
||||
- Feature request to OpenClaw maintainers
|
||||
- Contributing a hook system implementation
|
||||
- Using OpenHarness as an alternative (has native hooks)
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: mcp-integration
|
||||
description: Connect to Model Context Protocol (MCP) servers using exec and manual integration
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when you need to:
|
||||
- Access external data sources via MCP (filesystem, GitHub, databases)
|
||||
- Use tools provided by MCP servers
|
||||
- Integrate with existing MCP infrastructure
|
||||
- Extend OpenClaw's capabilities beyond native tools
|
||||
|
||||
**Note**: OpenClaw does not have a built-in MCP client. This skill shows how to manually integrate MCP using available tools.
|
||||
|
||||
## What is MCP?
|
||||
Model Context Protocol (MCP) is a standard for LLM apps to connect to external data sources and tools. MCP servers expose:
|
||||
- **Resources**: Read-only data
|
||||
- **Tools**: Callable functions
|
||||
- **Prompts**: Prompt templates
|
||||
|
||||
## Manual Integration Approach
|
||||
|
||||
Since OpenClaw lacks native MCP, you need to:
|
||||
|
||||
### 1. Run MCP server as subprocess
|
||||
Start an MCP server in the background:
|
||||
|
||||
```bash
|
||||
# Example: filesystem MCP server
|
||||
npx @modelcontextprotocol/server-filesystem /allowed/path &
|
||||
MCP_PID=$!
|
||||
|
||||
# Or GitHub MCP
|
||||
GITHUB_TOKEN=ghp_... npx @modelcontextprotocol/server-github &
|
||||
```
|
||||
|
||||
### 2. Communicate via stdio
|
||||
The MCP protocol uses JSON-RPC over stdio. You need to:
|
||||
- Write JSON-RPC requests to server's stdin
|
||||
- Read responses from server's stdout
|
||||
- Handle initialization handshake
|
||||
|
||||
### 3. Wrap as custom tool
|
||||
Create a shell function or script that:
|
||||
- Accepts arguments (tool name, params)
|
||||
- Sends JSON-RPC request to MCP server
|
||||
- Returns result to OpenClaw
|
||||
|
||||
Example pseudo-code:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# mcp-call.sh
|
||||
TOOL="$1"
|
||||
shift
|
||||
PARAMS="$*"
|
||||
|
||||
# Send JSON-RPC request (simplified)
|
||||
echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"$TOOL\",\"arguments\":$PARAMS}}" > /tmp/mcp.stdin
|
||||
# Read response from /tmp/mcp.stdout
|
||||
```
|
||||
|
||||
### 4. Use in OpenClaw
|
||||
```bash
|
||||
# Call MCP tool via wrapper
|
||||
exec ~/.openclaw/mcp/mcp-call.sh github_create_issue --repo 'owner/repo' --title 'Bug' --body '...'
|
||||
```
|
||||
|
||||
## Alternative: Use OpenHarness for MCP
|
||||
|
||||
OpenHarness has built-in MCP support (`mcp` command). If MCP integration is important:
|
||||
|
||||
1. Run OpenHarness alongside OpenClaw
|
||||
2. Use OpenHarness as MCP gateway
|
||||
3. Call OpenHarness from OpenClaw via HTTP or CLI
|
||||
|
||||
## Supported MCP Servers (Common)
|
||||
|
||||
- `@modelcontextprotocol/server-filesystem` — local file access
|
||||
- `@modelcontextprotocol/server-github` — GitHub API
|
||||
- `@modelcontextprotocol/server-postgres` — PostgreSQL
|
||||
- `@modelcontextprotocol/server-sqlite` — SQLite
|
||||
- `@modelcontextprotocol/server-http` — generic HTTP APIs
|
||||
|
||||
## Security Considerations
|
||||
|
||||
⚠️ MCP servers run with your user privileges and can:
|
||||
- Read/write any files in mounted paths
|
||||
- Access network resources
|
||||
- Use credentials (GitHub tokens, DB passwords)
|
||||
|
||||
**Mitigations**:
|
||||
- Restrict filesystem paths strictly
|
||||
- Use read-only tools when possible
|
||||
- Limit token scopes
|
||||
- Run MCP servers in sandbox if untrusted
|
||||
|
||||
## Workflow Example: Read file via MCP
|
||||
|
||||
1. Start filesystem MCP:
|
||||
```bash
|
||||
npx @modelcontextprotocol/server-filesystem /home/user/project &
|
||||
```
|
||||
|
||||
2. List resources:
|
||||
```bash
|
||||
# Send request manually or via script
|
||||
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list"}' > /proc/$PID/fd/0
|
||||
```
|
||||
|
||||
3. Read a resource:
|
||||
```bash
|
||||
# Assuming you have a wrapper `mcp-read`
|
||||
mcp-read file:///project/README.md
|
||||
```
|
||||
|
||||
## Implementation Difficulty
|
||||
|
||||
**Manual MCP integration is non-trivial**:
|
||||
- Need to implement JSON-RPC 2.0
|
||||
- Handle server initialization handshake
|
||||
- Manage async notifications
|
||||
- Error handling and reconnection
|
||||
|
||||
**Recommendation**: Use OpenHarness if you need MCP now, or wait for OpenClaw to add native support.
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] MCP server starts successfully and stays running
|
||||
- [ ] Initialization handshake completes (capabilities exchanged)
|
||||
- [ ] Tool calls return expected results
|
||||
- [ ] Resources are accessible and correctly formatted
|
||||
- [ ] Errors are handled gracefully
|
||||
- [ ] No sensitive data leaks in logs
|
||||
- [ ] MCP process is properly terminated when done
|
||||
|
||||
## Future: Native MCP Client
|
||||
|
||||
A proper OpenClaw MCP integration would:
|
||||
- Manage server lifecycle automatically
|
||||
- Provide `mcp` command (list-tools, call-tool, read-resource)
|
||||
- Handle JSON-RPC transparently
|
||||
- Cache resources
|
||||
- Support multiple servers
|
||||
|
||||
Consider contributing this to OpenClaw if needed.
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
name: notebook-edit
|
||||
description: Edit Jupyter notebook cells: read, modify, insert, delete, and execute code cells
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when the user asks to:
|
||||
- Modify code in a Jupyter notebook (.ipynb)
|
||||
- Add new cells (code, markdown, raw)
|
||||
- Delete or reorder cells
|
||||
- Update cell outputs
|
||||
- Execute notebook cells (if kernel available)
|
||||
- Convert notebooks to other formats
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Locate the notebook
|
||||
Find the .ipynb file path.
|
||||
|
||||
### 2. Read notebook structure
|
||||
```bash
|
||||
read notebook.ipynb
|
||||
```
|
||||
This returns the raw JSON structure of the notebook with cells, sources, outputs, metadata. You'll need to parse this JSON manually.
|
||||
|
||||
### 3. Make edits
|
||||
Use `edit` tool to modify the notebook JSON directly:
|
||||
- Edit `cells[*].source` to change code/markdown content
|
||||
- Edit `cells[*].cell_type` to change type ("code", "markdown")
|
||||
- Insert/delete by modifying the `cells` array
|
||||
- Be careful with JSON structure — validate after edits
|
||||
|
||||
### 4. Execute cells (optional)
|
||||
OpenClaw does not have a built-in `notebook_execute` tool. If you need to execute notebooks, either:
|
||||
- Use `exec` to run `jupyter nbconvert --execute notebook.ipynb`
|
||||
- Or manually run the code cells section by section using `code_execution`
|
||||
|
||||
### 5. Save changes
|
||||
Edits are saved automatically upon tool completion, or explicitly write.
|
||||
|
||||
## Cell Types
|
||||
- **code**: Executable Python/R/Julia code
|
||||
- **markdown**: Documentation with Markdown formatting
|
||||
- **raw**: Unformatted text (rarely used)
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Add a code cell at the end
|
||||
```bash
|
||||
notebook_edit notebook.ipynb \
|
||||
--insert "end" \
|
||||
--cell-type code \
|
||||
--source "print('Hello')"
|
||||
```
|
||||
|
||||
### Update existing cell
|
||||
```bash
|
||||
notebook_edit notebook.ipynb \
|
||||
--cell-index 3 \
|
||||
--source "x = 5\nprint(x*2)"
|
||||
```
|
||||
|
||||
### Delete a cell
|
||||
```bash
|
||||
notebook_edit notebook.ipynb \
|
||||
--cell-index 2 \
|
||||
--delete true
|
||||
```
|
||||
|
||||
### Run all cells
|
||||
```bash
|
||||
notebook_execute notebook.ipynb --all
|
||||
```
|
||||
|
||||
### Clear outputs
|
||||
```bash
|
||||
notebook_edit notebook.ipynb --clear-outputs true
|
||||
```
|
||||
|
||||
## Safety Rules
|
||||
- **Backup first**: Copy notebook before major edits
|
||||
- **Don't overwrite outputs** unless explicitly asked
|
||||
- **Preserve cell metadata**: Some notebooks rely on custom metadata
|
||||
- **Kernel restarts**: Changes to imports/functions may require kernel restart
|
||||
|
||||
## Examples
|
||||
|
||||
<Good>
|
||||
User: "Thêm cell tính trung bình vào notebook analysis.ipynb"
|
||||
Assistant:
|
||||
1. Đọc notebook hiện tại
|
||||
2. Tìm vị trí phù hợp (sau phần data loading)
|
||||
3. Thêm code cell với formulas đúng
|
||||
4. Kiểm tra syntax trước khi lưu
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
Sửa cell mà không xem nội dung gốc, có thể mất code quan trọng.
|
||||
</Bad>
|
||||
|
||||
## Error Handling
|
||||
- **Invalid cell index**: Check notebook length first
|
||||
- **JSON parse error**: Notebook có thể bị corrupt, backup và repair
|
||||
- **Kernel not available**: Execution sẽ fail, chỉ edit được code
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] Notebook file is valid JSON
|
||||
- [ ] Cell indices are within bounds
|
||||
- [ ] Code syntax is correct (consider linting)
|
||||
- [ ] No orphaned outputs (clear if needed)
|
||||
- [ ] Notebook can still open in Jupyter after edit
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Read, extract, and manipulate PDF documents
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when the user asks to:
|
||||
- Extract text from PDF files
|
||||
- Read PDF content (full or specific pages)
|
||||
- Split or merge PDF documents
|
||||
- Extract metadata (title, author, page count)
|
||||
- Search within PDFs
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Identify the PDF file
|
||||
Locate the PDF file path. Use `glob` or `ls` if needed.
|
||||
|
||||
### 2. Extract text (full or partial)
|
||||
|
||||
OpenClaw's `read` tool does not directly support PDF. You need to convert PDF to text first:
|
||||
|
||||
```bash
|
||||
# Convert PDF to text using pdftotext (if available)
|
||||
exec pdftotext path/to/file.pdf -
|
||||
|
||||
# Or use Python
|
||||
python -c "
|
||||
import pypdf;
|
||||
reader = pypdf.PdfReader('file.pdf');
|
||||
print('\n'.join([page.extract_text() for page in reader.pages]))
|
||||
"
|
||||
```
|
||||
|
||||
Then capture the output for processing.
|
||||
|
||||
### 3. Parse and structure content
|
||||
- If extracting form data, organize into key-value pairs
|
||||
- If extracting tables, preserve structure (CSV/markdown table)
|
||||
- If searching, return matching snippets with page numbers
|
||||
|
||||
### 4. For advanced operations
|
||||
- **Split PDF**: Use appropriate tool to split into separate files
|
||||
- **Merge PDFs**: Combine multiple PDFs in order
|
||||
- **Metadata**: Extract or modify PDF metadata
|
||||
|
||||
## Tool Requirements
|
||||
This skill assumes the following tools are available:
|
||||
- `exec` (to run conversion commands: pdftotext, python, etc.)
|
||||
- `read` (for text files after conversion)
|
||||
- `write`/`edit` (for saving extracted content)
|
||||
- Optional: `poppler-utils` package (pdftotext) or `pypdf` Python library
|
||||
|
||||
## Examples
|
||||
|
||||
<Good>
|
||||
User: "Lấy nội dung invoice.pdf"
|
||||
Assistant:
|
||||
1. Xác định đường dẫn file
|
||||
2. Dùng read để extract text
|
||||
3. Trích xuất thông tin quan trọng (số hóa đơn, ngày, tổng tiền)
|
||||
4. Trả về dữ liệu có cấu trúc
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
Chỉ nói "Tôi đọc được nội dung PDF" mà không trích xuất thông tin cụ thể.
|
||||
</Bad>
|
||||
|
||||
## Limitations
|
||||
- Large PDFs (>100 pages) may be truncated — check tool limits
|
||||
- Scanned PDFs require OCR — ensure OCR tool is available
|
||||
- Password-protected PDFs need password first
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] PDF file exists and is accessible
|
||||
- [ ] Extracted text is complete (no truncation)
|
||||
- [ ] Structured data is accurate
|
||||
- [ ] Page numbers/references are correct if cited
|
||||
- [ ] For tables, formatting is preserved
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
name: security-best-practices
|
||||
description: Apply security hardening, input validation, and protection measures across all operations
|
||||
---
|
||||
|
||||
## When to use
|
||||
Use when the user asks to:
|
||||
- Secure an application or system
|
||||
- Audit code for vulnerabilities
|
||||
- Set up authentication/authorization
|
||||
- Harden configurations
|
||||
- Perform security reviews
|
||||
- Handle secrets and credentials
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Defense in Depth
|
||||
Apply multiple layers of security:
|
||||
- Input validation
|
||||
- Authentication
|
||||
- Authorization
|
||||
- Output encoding
|
||||
- Encryption
|
||||
- Auditing
|
||||
|
||||
### 2. Least Privilege
|
||||
Agents/tools should have only the permissions they need:
|
||||
- File access: restrict to specific directories
|
||||
- Network: allow only required endpoints
|
||||
- Tools: disable dangerous ones when not needed
|
||||
|
||||
### 3. Fail Securely
|
||||
Errors should not reveal sensitive information:
|
||||
- Generic error messages to users
|
||||
- Detailed errors only in logs (protected)
|
||||
- Secure defaults (deny by default)
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Input Validation
|
||||
- [ ] Validate all user inputs (type, length, format, range)
|
||||
- [ ] Sanitize to remove/escape dangerous characters
|
||||
- [ ] Use parameterized queries (no string concatenation)
|
||||
- [ ] Reject unexpected values early
|
||||
|
||||
### Authentication & Authorization
|
||||
- [ ] Use strong, salted password hashing (bcrypt, Argon2)
|
||||
- [ ] Implement multi-factor authentication for sensitive operations
|
||||
- [ ] Enforce least privilege (RBAC/ABAC)
|
||||
- [ ] Use short-lived tokens, rotate regularly
|
||||
- [ ] Validate permissions on every request
|
||||
|
||||
### Secrets Management
|
||||
- [ ] Never hardcode secrets in source code
|
||||
- [ ] Use environment variables or secret vaults
|
||||
- [ ] Rotate credentials regularly
|
||||
- [ ] Different secrets per environment (dev/staging/prod)
|
||||
- [ ] Don't log secrets (redact from logs)
|
||||
|
||||
### Data Protection
|
||||
- [ ] Encrypt sensitive data at rest (AES-256)
|
||||
- [ ] Use TLS 1.2+ for data in transit
|
||||
- [ ] Secure backups (encrypted, access-controlled)
|
||||
- [ ] Anonymize/pseudonymize PII when possible
|
||||
|
||||
### Output Encoding
|
||||
- [ ] Encode data before rendering (HTML escape, SQL escape, shell escape)
|
||||
- [ ] Use templating engines with auto-escaping
|
||||
- [ ] Content Security Policy (CSP) headers for web apps
|
||||
|
||||
### Dependency Security
|
||||
- [ ] Regularly audit dependencies for CVEs
|
||||
- [ ] Use minimal dependencies
|
||||
- [ ] Pin versions (avoid floating ranges)
|
||||
- [ ] Update promptly when vulnerabilities disclosed
|
||||
|
||||
## Code Review Security Points
|
||||
|
||||
Review code for:
|
||||
- **SQL injection**: raw queries with string concatenation
|
||||
- **XSS**: unescaped output in HTML/JS
|
||||
- **CSRF**: missing tokens on state-changing requests
|
||||
- **Path traversal**: user-controlled file paths without validation
|
||||
- **Insecure deserialization**: untrusted data → object creation
|
||||
- **Hardcoded secrets**: passwords, API keys in source
|
||||
- **Weak crypto**: MD5, SHA1, custom algorithms, hardcoded keys
|
||||
|
||||
## Configuration Hardening
|
||||
|
||||
### File permissions
|
||||
```bash
|
||||
chmod 600 ~/.openclaw/credentials/*.json # Owner read/write only
|
||||
chmod 700 ~/.openclaw/workspace # Restrict workspace
|
||||
```
|
||||
|
||||
### Network security
|
||||
- Firewall: allow only necessary ports
|
||||
- VPN for remote access
|
||||
- Disable unnecessary services
|
||||
|
||||
### Audit logging
|
||||
Log all security events:
|
||||
- Authentication attempts (success/failure)
|
||||
- Authorization failures
|
||||
- Configuration changes
|
||||
- Data access (especially PII)
|
||||
Include: timestamp, user, action, IP, outcome
|
||||
|
||||
## Incident Response
|
||||
|
||||
If a breach is suspected:
|
||||
1. **Isolate**: Cut off network access if possible
|
||||
2. **Preserve logs**: Don't delete; copy for analysis
|
||||
3. **Assess scope**: Which systems/data affected?
|
||||
4. **Notify**: Follow disclosure procedures
|
||||
5. **Remediate**: Patch vulnerabilities, rotate credentials
|
||||
6. **Post-mortem**: Document lessons learned
|
||||
|
||||
## Tools for Security Audit
|
||||
|
||||
Use OpenClaw skills:
|
||||
- `security-review`: Automated code security scan
|
||||
- `systematic-debugging`: Identify root cause of vulnerabilities
|
||||
- `code-quality-gate`: Enforce security standards
|
||||
|
||||
External tools:
|
||||
- OWASP ZAP / Burp Suite (web scanning)
|
||||
- Trivy / Grype (dependency scanning)
|
||||
- Bandit / Semgrep (SAST)
|
||||
- sqlmap (SQL injection testing)
|
||||
|
||||
## Examples
|
||||
|
||||
<Good>
|
||||
Database query with parameterized statement:
|
||||
```python
|
||||
cursor.execute("SELECT * FROM users WHERE email = %s", (email,))
|
||||
```
|
||||
</Good>
|
||||
|
||||
<Bad>
|
||||
```python
|
||||
query = f"SELECT * FROM users WHERE email = '{email}'"
|
||||
cursor.execute(query) # SQL injection vulnerability
|
||||
```
|
||||
</Bad>
|
||||
|
||||
## Compliance Considerations
|
||||
|
||||
Depending on industry:
|
||||
- **GDPR**: Data protection, privacy by design, breach notification
|
||||
- **PCI DSS**: Payment card data handling
|
||||
- **HIPAA**: Healthcare data encryption and access logs
|
||||
- **SOC 2**: Security controls and audit trails
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] All user inputs validated and sanitized
|
||||
- [ ] No hardcoded secrets in codebase
|
||||
- [ ] Secrets stored securely (env vars, vault)
|
||||
- [ ] Database queries use parameterized statements
|
||||
- [ ] Output properly encoded for context (HTML, SQL, shell)
|
||||
- [ ] Authentication strong (bcrypt, 2FA)
|
||||
- [ ] Authorization checks on all protected actions
|
||||
- [ ] Sensitive data encrypted at rest and in transit
|
||||
- [ ] Audit logs capture security events
|
||||
- [ ] Dependencies up-to-date with no known CVEs
|
||||
- [ ] Regular security scans performed
|
||||
- [ ] Incident response plan documented
|
||||
Reference in New Issue
Block a user