Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive 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.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

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
```
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall