SKILL.md
$27
Via Docker
docker run -it -v ~/.weclaw:/root/.weclaw ghcr.io/fastclaw-ai/weclaw start
---
## First-Run Flow
weclaw start # Shows QR code → scan with WeChat → auto-detects agents → saves config
weclaw login # Add/re-authenticate a WeChat account
weclaw status # Show running state and active agent
weclaw stop # Stop the background daemon
weclaw start -f # Foreground mode (debug/verbose)
Logs: `~/.weclaw/weclaw.log`
Config: `~/.weclaw/config.json`
## Configuration
{
"default_agent": "claude",
"agents": {
"claude": {
"type": "acp",
"command": "/usr/local/bin/claude-agent-acp",
"model": "sonnet"
},
"codex": {
"type": "acp",
"command": "/usr/local/bin/codex-acp"
},
"claude-cli": {
"type": "cli",
"command": "/usr/local/bin/claude",
"args": ["--dangerously-skip-permissions"]
},
"codex-cli": {
"type": "cli",
"command": "/usr/local/bin/codex",
"args": ["--skip-git-repo-check"]
},
"openclaw": {
"type": "http",
"endpoint": "https://api.example.com/v1/chat/completions",
"api_key": "$OPENCLAW_GATEWAY_TOKEN",
"model": "openclaw:main"
}
}
}
### Environment Variables
Variable
Purpose
`WECLAW_DEFAULT_AGENT`
Override default agent at runtime
`WECLAW_API_ADDR`
Change local HTTP API address (default `127.0.0.1:18011`)
`OPENCLAW_GATEWAY_URL`
HTTP agent endpoint
`OPENCLAW_GATEWAY_TOKEN`
HTTP agent API token
## Agent Modes
Mode
Process model
Best for
`acp`
Long-running subprocess, JSON-RPC over stdio
Claude, Codex, Kimi, Gemini — fastest, session reuse
`cli`
New process per message, `--resume` for sessions
`claude -p`, `codex exec`
`http`
OpenAI-compatible `/v1/chat/completions`
Any REST-accessible model
Auto-detection prefers `acp` over `cli` when both binaries exist.
## Chat Commands (send as WeChat messages)
Command
Action
`hello`
Send to default agent
`/codex write a sort function`
Route to named agent
`/cc explain this code`
Use alias (`/cc` → claude)
`/claude`
Switch default agent to Claude (persisted)
`/status`
Show active agent info
`/help`
List available commands
### Built-in Aliases
Alias
Agent
`/cc`
claude
`/cx`
codex
`/cs`
cursor
`/km`
kimi
`/gm`
gemini
`/ocd`
opencode
`/oc`
openclaw
## Proactive Messaging — CLI
Send plain text
weclaw send --to "user_id@im.wechat" --text "Hello from WeClaw"
Send an image
weclaw send --to "user_id@im.wechat" --media "https://example.com/photo.png"
Send text + media together
weclaw send --to "user_id@im.wechat" \
--text "Check this out" \
--media "https://example.com/photo.png"
Send a file
weclaw send --to "user_id@im.wechat" --media "https://example.com/report.pdf"
## Proactive Messaging — HTTP API
The local API listens on `127.0.0.1:18011` while `weclaw start` is running.
Send text
curl -X POST http://127.0.0.1:18011/api/send \
-H "Content-Type: application/json" \
-d '{"to": "user_id@im.wechat", "text": "Hello from WeClaw"}'
Send image
curl -X POST http://127.0.0.1:18011/api/send \
-H "Content-Type: application/json" \
-d '{"to": "user_id@im.wechat", "media_url": "https://example.com/photo.png"}'
Send text + media
curl -X POST http://127.0.0.1:18011/api/send \
-H "Content-Type: application/json" \
-d '{"to": "user_id@im.wechat", "text": "See this", "media_url": "https://example.com/photo.png"}'
**Supported media types:** `png`, `jpg`, `gif`, `webp`, `mp4`, `mov`, `pdf`, `doc`, `zip`.
Change listen address:
WECLAW_API_ADDR=0.0.0.0:18011 weclaw start
## Go Integration Example
Call the WeClaw HTTP API from a Go service to send notifications:
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
type SendRequest struct {
To string json:"to"
Text string json:"text,omitempty"
MediaURL string json:"media_url,omitempty"
}
type SendResponse struct {
OK bool json:"ok"
Message string json:"message,omitempty"
}
func sendToWeChat(to, text, mediaURL string) error {
apiAddr := os.Getenv("WECLAW_API_ADDR")
if apiAddr == "" {
apiAddr = "127.0.0.1:18011"
}
req := SendRequest{To: to, Text: text, MediaURL: mediaURL}
body, err := json.Marshal(req)
if err != nil {
return fmt.Errorf("marshal: %w", err)
}
resp, err := http.Post(
fmt.Sprintf("http://%s/api/send", apiAddr),
"application/json",
bytes.NewReader(body),
)
if err != nil {
return fmt.Errorf("post: %w", err)
}
defer resp.Body.Close()
var result SendResponse
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return fmt.Errorf("decode: %w", err)
}
if !result.OK {
return fmt.Errorf("weclaw error: %s", result.Message)
}
return nil
}
func main() {
recipient := os.Getenv("WECHAT_RECIPIENT_ID") // e.g. "user_id@im.wechat"
if err := sendToWeChat(recipient, "Build succeeded ✅", ""); err != nil {
fmt.Fprintf(os.Stderr, "failed: %v\n", err)
os.Exit(1)
}
fmt.Println("Message sent.")
}
## Docker Setup
Build image
docker build -t weclaw .
Step 1: Interactive login (scan QR code)
docker run -it -v ~/.weclaw:/root/.weclaw weclaw login
Step 2: Run daemon with HTTP agent
docker run -d --name weclaw \
-v ~/.weclaw:/root/.weclaw \
-e OPENCLAW_GATEWAY_URL=https://api.example.com \
-e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN" \
weclaw
Expose the local API externally (bind carefully — no auth by default)
docker run -d --name weclaw \
-v ~/.weclaw:/root/.weclaw \
-e WECLAW_API_ADDR=0.0.0.0:18011 \
-p 18011:18011 \
-e OPENCLAW_GATEWAY_TOKEN="$OPENCLAW_GATEWAY_TOKEN" \
weclaw
docker logs -f weclaw
ACP/CLI agents require the agent binary inside the container. Mount the binary or build a custom image. HTTP agents work out of the box.
## System Service (Auto-start)
**macOS (launchd):**
cp service/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist
**Linux (systemd):**
sudo cp service/weclaw.service /etc/systemd/system/
sudo systemctl enable --now weclaw
journalctl -u weclaw -f
## Development
make dev # Hot reload
go build -o weclaw . # Build binary
./weclaw start -f # Run in foreground
**Releasing:**
git tag v0.1.0
git push origin v0.1.0
GitHub Actions builds darwin/linux × amd64/arm64 and uploads release artifacts
## Common Patterns
### Pattern: Per-user agent routing
Send `/claude` or `/codex` as a WeChat message to switch the default agent. The choice persists in `~/.weclaw/config.json` across restarts.
### Pattern: CI/CD build notifications
After a build, call `weclaw send` or POST to the HTTP API to push results to a WeChat contact or group.
### Pattern: Media from agent
If an agent reply contains ``, WeClaw auto-downloads, AES-128-ECB encrypts, uploads to WeChat CDN, and delivers as a native image message — no extra config needed.
### Pattern: Disable permission prompts for headless use
{
"claude": { "type": "cli", "command": "/usr/local/bin/claude",
"args": ["--dangerously-skip-permissions"] },
"codex": { "type": "cli", "command": "/usr/local/bin/codex",
"args": ["--skip-git-repo-check"] }
}