LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/automation.md
View on GitHub# OpenClaw Automation Reference (Cron Jobs, Webhooks, Gmail Pub/Sub)
## Table of Contents
- [Cron Jobs](#cron-jobs)
- [Webhooks](#webhooks)
- [Gmail Pub/Sub](#gmail-pubsub)
---
## Cron Jobs
Cron runs inside the **Gateway** (not inside the model). Jobs persist under `~/.openclaw/cron/jobs.json`.
### Quick Start
```bash
# One-shot reminder
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: check the docs" \
--wake now \
--delete-after-run
# Recurring isolated job with announce
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize overnight updates." \
--announce \
--channel slack \
--to "channel:C1234567890"
# Management
openclaw cron list
openclaw cron run <job-id>
openclaw cron runs --id <job-id>
```
### Concepts
#### Jobs
Each job has:
- **Schedule** (when it runs)
- **Payload** (what it does)
- **Delivery mode** (optional): `announce`, `webhook`, or `none`
- **Agent binding** (optional): `agentId` — run under a specific agent
#### Schedules
| Type | Description | Example |
|---|---|---|
| `at` | One-shot timestamp (ISO 8601) | `schedule.at: "2026-02-01T16:00:00Z"` |
| `every` | Fixed interval (ms) | `schedule.every: 3600000` |
| `cron` | 5-field cron expression + optional timezone | `schedule.cron: "0 7 * * *"` |
Options: `--stagger 30s` to set stagger window, `--exact` to force `staggerMs = 0`.
#### Execution Modes
| Mode | Session Key | Description |
|---|---|---|
| **Main session** | `main` | System event → heartbeat prompt |
| **Isolated** | `cron:<jobId>` | Dedicated agent turn, fresh session per run |
**Main session jobs**: `payload.kind = "systemEvent"`. Wake options: `"now"` (immediate) or `"next-heartbeat"`.
**Isolated jobs**: Each run starts a fresh sessionId. Prompt prefixed with `[cron:<jobId> <job name>]`.
#### Payload Shapes
- `systemEvent`: main-session only, routed through heartbeat
- `agentTurn`: isolated only, runs a dedicated agent turn with `message`, optional `model`/`thinking`/`timeoutSeconds`
#### Delivery
| Mode | Behavior |
|---|---|
| `announce` (default for isolated) | Deliver summary to target channel + main session summary |
| `webhook` | POST to `delivery.to` URL |
| `none` | Internal only, no delivery |
Delivery fields:
- `delivery.channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` / `signal` / `imessage` / `last`
- `delivery.to`: channel-specific target or webhook URL
- `delivery.bestEffort`: avoid failing if announce delivery fails
**Telegram topics**: Use `delivery.to: "-1001234567890:topic:123"` format.
#### Model & Thinking Overrides
Override priority: Job payload → Hook-specific defaults → Agent config default.
- `model`: `provider/model` string or alias
- `thinking`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`
### Retry Policy
- **Transient errors** (retried): network timeouts, rate limits, upstream 5xx
- **Permanent errors** (no retry): auth failures, invalid config, model not found
- Default: no config needed; built-in retries for transient errors
### Configuration
```json5
{
cron: {
webhookToken: "your-token", // Auth for webhook mode
stagger: { defaultMs: 0 }, // Default stagger
},
}
```
### Troubleshooting
| Problem | Fix |
|---|---|
| "Nothing runs" | Check `openclaw gateway status`, ensure Gateway is running |
| Recurring job delays after failures | Check retry backoff; reset with `openclaw cron run <id>` |
| Telegram delivers to wrong place | Use explicit `:topic:` format for forum threads |
| Subagent announce retries | Set `delivery.bestEffort: true` |
---
## Webhooks
HTTP endpoints exposed by the Gateway for external triggers.
### Enable
```json5
{
gateway: {
webhooks: { enabled: true },
},
}
```
### Auth
Webhooks require `gateway.auth.token` or `gateway.auth.password`. Pass via `Authorization: Bearer <token>` header.
### Endpoints
#### `POST /hooks/wake`
Trigger a wake/heartbeat cycle.
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
-H "Authorization: Bearer $TOKEN"
```
#### `POST /hooks/agent`
Send a prompt to the agent, run a dedicated turn.
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "Check server status"}'
```
Options: `model`, `thinking`, `agentId`, `sessionKey`, `delivery`.
#### `POST /hooks/<name>` (mapped)
Custom-named webhook endpoints configured in `gateway.webhooks.map`.
### Session Key Policy
By default, each webhook call gets a fresh `hook:<uuid>` session key. Override with `sessionKey` in the request body.
### Responses
Returns `{ status: "ok", sessionId: "..." }` on success, or error details.
### Security
- Always use auth tokens
- Restrict network exposure (bind to loopback or use Tailscale)
- Webhooks inherit the agent's tool permissions
---
## Gmail Pub/Sub
Connect Gmail inbox notifications to OpenClaw via Google Cloud Pub/Sub.
### Prerequisites
- Google Cloud project with Gmail API + Pub/Sub enabled
- Service account or OAuth credentials
- A Pub/Sub topic and push subscription
### Setup
```bash
# Wizard (recommended)
openclaw webhooks gmail setup
# Manual one-time setup
# 1. Create GCP Pub/Sub topic
# 2. Grant Gmail publish rights
# 3. Configure OpenClaw
```
### Start the Watch
```bash
openclaw webhooks gmail watch
```
### Run the Push Handler
Configure the push subscription to POST to your Gateway's webhook endpoint.
### Troubleshooting
| Problem | Fix |
|---|---|
| No notifications | Verify Pub/Sub subscription is active |
| Auth errors | Check service account permissions |
| Webhook not receiving | Ensure Gateway is accessible from GCP |
### Cleanup
```bash
openclaw webhooks gmail stop
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |