mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-09 05:19:32 +08:00
Merge branch 'main' into qianfan
This commit is contained in:
ide-rea
@@ -23,7 +23,7 @@ cron is the mechanism.
|
||||
- Jobs persist under `~/.openclaw/cron/` so restarts don’t lose schedules.
|
||||
- Two execution styles:
|
||||
- **Main session**: enqueue a system event, then run on the next heartbeat.
|
||||
- **Isolated**: run a dedicated agent turn in `cron:<jobId>`, optionally deliver output.
|
||||
- **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default or none).
|
||||
- Wakeups are first-class: a job can request “wake now” vs “next heartbeat”.
|
||||
|
||||
## Quick start (actionable)
|
||||
@@ -53,7 +53,7 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize overnight updates." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel slack \
|
||||
--to "channel:C1234567890"
|
||||
```
|
||||
@@ -86,7 +86,8 @@ Think of a cron job as: **when** to run + **what** to do.
|
||||
- Main session → `payload.kind = "systemEvent"`
|
||||
- Isolated session → `payload.kind = "agentTurn"`
|
||||
|
||||
Optional: `deleteAfterRun: true` removes successful one-shot jobs from the store.
|
||||
Optional: one-shot jobs (`schedule.kind = "at"`) delete after success by default. Set
|
||||
`deleteAfterRun: false` to keep them (they will disable after success).
|
||||
|
||||
## Concepts
|
||||
|
||||
@@ -96,19 +97,19 @@ A cron job is a stored record with:
|
||||
|
||||
- a **schedule** (when it should run),
|
||||
- a **payload** (what it should do),
|
||||
- optional **delivery** (where output should be sent).
|
||||
- optional **delivery mode** (announce or none).
|
||||
- optional **agent binding** (`agentId`): run the job under a specific agent; if
|
||||
missing or unknown, the gateway falls back to the default agent.
|
||||
|
||||
Jobs are identified by a stable `jobId` (used by CLI/Gateway APIs).
|
||||
In agent tool calls, `jobId` is canonical; legacy `id` is accepted for compatibility.
|
||||
Jobs can optionally auto-delete after a successful one-shot run via `deleteAfterRun: true`.
|
||||
One-shot jobs auto-delete after success by default; set `deleteAfterRun: false` to keep them.
|
||||
|
||||
### Schedules
|
||||
|
||||
Cron supports three schedule kinds:
|
||||
|
||||
- `at`: one-shot timestamp (ms since epoch). Gateway accepts ISO 8601 and coerces to UTC.
|
||||
- `at`: one-shot timestamp via `schedule.at` (ISO 8601).
|
||||
- `every`: fixed interval (ms).
|
||||
- `cron`: 5-field cron expression with optional IANA timezone.
|
||||
|
||||
@@ -136,9 +137,13 @@ Key behaviors:
|
||||
|
||||
- Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
|
||||
- Each run starts a **fresh session id** (no prior conversation carry-over).
|
||||
- A summary is posted to the main session (prefix `Cron`, configurable).
|
||||
- `wakeMode: "now"` triggers an immediate heartbeat after posting the summary.
|
||||
- If `payload.deliver: true`, output is delivered to a channel; otherwise it stays internal.
|
||||
- Default behavior: if `delivery` is omitted, isolated jobs announce a summary (`delivery.mode = "announce"`).
|
||||
- `delivery.mode` (isolated-only) chooses what happens:
|
||||
- `announce`: deliver a summary to the target channel and post a brief summary to the main session.
|
||||
- `none`: internal only (no delivery, no main-session summary).
|
||||
- `wakeMode` controls when the main-session summary posts:
|
||||
- `now`: immediate heartbeat.
|
||||
- `next-heartbeat`: waits for the next scheduled heartbeat.
|
||||
|
||||
Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
|
||||
your main chat history.
|
||||
@@ -155,16 +160,35 @@ Common `agentTurn` fields:
|
||||
- `message`: required text prompt.
|
||||
- `model` / `thinking`: optional overrides (see below).
|
||||
- `timeoutSeconds`: optional timeout override.
|
||||
- `deliver`: `true` to send output to a channel target.
|
||||
- `channel`: `last` or a specific channel.
|
||||
- `to`: channel-specific target (phone/chat/channel id).
|
||||
- `bestEffortDeliver`: avoid failing the job if delivery fails.
|
||||
|
||||
Isolation options (only for `session=isolated`):
|
||||
Delivery config (isolated jobs only):
|
||||
|
||||
- `postToMainPrefix` (CLI: `--post-prefix`): prefix for the system event in main.
|
||||
- `postToMainMode`: `summary` (default) or `full`.
|
||||
- `postToMainMaxChars`: max chars when `postToMainMode=full` (default 8000).
|
||||
- `delivery.mode`: `none` | `announce`.
|
||||
- `delivery.channel`: `last` or a specific channel.
|
||||
- `delivery.to`: channel-specific target (phone/chat/channel id).
|
||||
- `delivery.bestEffort`: avoid failing the job if announce delivery fails.
|
||||
|
||||
Announce delivery suppresses messaging tool sends for the run; use `delivery.channel`/`delivery.to`
|
||||
to target the chat instead. When `delivery.mode = "none"`, no summary is posted to the main session.
|
||||
|
||||
If `delivery` is omitted for isolated jobs, OpenClaw defaults to `announce`.
|
||||
|
||||
#### Announce delivery flow
|
||||
|
||||
When `delivery.mode = "announce"`, cron delivers directly via the outbound channel adapters.
|
||||
The main agent is not spun up to craft or forward the message.
|
||||
|
||||
Behavior details:
|
||||
|
||||
- Content: delivery uses the isolated run's outbound payloads (text/media) with normal chunking and
|
||||
channel formatting.
|
||||
- Heartbeat-only responses (`HEARTBEAT_OK` with no real content) are not delivered.
|
||||
- If the isolated run already sent a message to the same target via the message tool, delivery is
|
||||
skipped to avoid duplicates.
|
||||
- Missing or invalid delivery targets fail the job unless `delivery.bestEffort = true`.
|
||||
- A short summary is posted to the main session only when `delivery.mode = "announce"`.
|
||||
- The main-session summary respects `wakeMode`: `now` triggers an immediate heartbeat and
|
||||
`next-heartbeat` waits for the next scheduled heartbeat.
|
||||
|
||||
### Model and thinking overrides
|
||||
|
||||
@@ -185,19 +209,16 @@ Resolution priority:
|
||||
|
||||
### Delivery (channel + target)
|
||||
|
||||
Isolated jobs can deliver output to a channel. The job payload can specify:
|
||||
Isolated jobs can deliver output to a channel via the top-level `delivery` config:
|
||||
|
||||
- `channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`
|
||||
- `to`: channel-specific recipient target
|
||||
- `delivery.mode`: `announce` (deliver a summary) or `none`.
|
||||
- `delivery.channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`.
|
||||
- `delivery.to`: channel-specific recipient target.
|
||||
|
||||
If `channel` or `to` is omitted, cron can fall back to the main session’s “last route”
|
||||
(the last place the agent replied).
|
||||
Delivery config is only valid for isolated jobs (`sessionTarget: "isolated"`).
|
||||
|
||||
Delivery notes:
|
||||
|
||||
- If `to` is set, cron auto-delivers the agent’s final output even if `deliver` is omitted.
|
||||
- Use `deliver: true` when you want last-route delivery without an explicit `to`.
|
||||
- Use `deliver: false` to keep output internal even if a `to` is present.
|
||||
If `delivery.channel` or `delivery.to` is omitted, cron can fall back to the main session’s
|
||||
“last route” (the last place the agent replied).
|
||||
|
||||
Target format reminders:
|
||||
|
||||
@@ -220,8 +241,8 @@ Prefixed targets like `telegram:...` / `telegram:group:...` are also accepted:
|
||||
## JSON schema for tool calls
|
||||
|
||||
Use these shapes when calling Gateway `cron.*` tools directly (agent tool calls or RPC).
|
||||
CLI flags accept human durations like `20m`, but tool calls use epoch milliseconds for
|
||||
`atMs` and `everyMs` (ISO timestamps are accepted for `at` times).
|
||||
CLI flags accept human durations like `20m`, but tool calls should use an ISO 8601 string
|
||||
for `schedule.at` and milliseconds for `schedule.everyMs`.
|
||||
|
||||
### cron.add params
|
||||
|
||||
@@ -230,7 +251,7 @@ One-shot, main session job (system event):
|
||||
```json
|
||||
{
|
||||
"name": "Reminder",
|
||||
"schedule": { "kind": "at", "atMs": 1738262400000 },
|
||||
"schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
|
||||
"sessionTarget": "main",
|
||||
"wakeMode": "now",
|
||||
"payload": { "kind": "systemEvent", "text": "Reminder text" },
|
||||
@@ -248,22 +269,25 @@ Recurring, isolated job with delivery:
|
||||
"wakeMode": "next-heartbeat",
|
||||
"payload": {
|
||||
"kind": "agentTurn",
|
||||
"message": "Summarize overnight updates.",
|
||||
"deliver": true,
|
||||
"message": "Summarize overnight updates."
|
||||
},
|
||||
"delivery": {
|
||||
"mode": "announce",
|
||||
"channel": "slack",
|
||||
"to": "channel:C1234567890",
|
||||
"bestEffortDeliver": true
|
||||
},
|
||||
"isolation": { "postToMainPrefix": "Cron", "postToMainMode": "summary" }
|
||||
"bestEffort": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `schedule.kind`: `at` (`atMs`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
|
||||
- `atMs` and `everyMs` are epoch milliseconds.
|
||||
- `schedule.kind`: `at` (`at`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
|
||||
- `schedule.at` accepts ISO 8601 (timezone optional; treated as UTC when omitted).
|
||||
- `everyMs` is milliseconds.
|
||||
- `sessionTarget` must be `"main"` or `"isolated"` and must match `payload.kind`.
|
||||
- Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun`, `isolation`.
|
||||
- Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun` (defaults to true for `at`),
|
||||
`delivery`.
|
||||
- `wakeMode` defaults to `"next-heartbeat"` when omitted.
|
||||
|
||||
### cron.update params
|
||||
@@ -341,7 +365,7 @@ openclaw cron add \
|
||||
--wake now
|
||||
```
|
||||
|
||||
Recurring isolated job (deliver to WhatsApp):
|
||||
Recurring isolated job (announce to WhatsApp):
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -350,7 +374,7 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize inbox + calendar for today." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
@@ -364,7 +388,7 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize today; send to the nightly topic." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel telegram \
|
||||
--to "-1001234567890:topic:123"
|
||||
```
|
||||
@@ -380,7 +404,7 @@ openclaw cron add \
|
||||
--message "Weekly deep analysis of project progress." \
|
||||
--model "opus" \
|
||||
--thinking high \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
@@ -90,7 +90,8 @@ Cron jobs run at **exact times** and can run in isolated sessions without affect
|
||||
- **Exact timing**: 5-field cron expressions with timezone support.
|
||||
- **Session isolation**: Runs in `cron:<jobId>` without polluting main history.
|
||||
- **Model overrides**: Use a cheaper or more powerful model per job.
|
||||
- **Delivery control**: Can deliver directly to a channel; still posts a summary to main by default (configurable).
|
||||
- **Delivery control**: Isolated jobs default to `announce` (summary); choose `none` as needed.
|
||||
- **Immediate delivery**: Announce mode posts directly without waiting for heartbeat.
|
||||
- **No agent context needed**: Runs even if main session is idle or compacted.
|
||||
- **One-shot support**: `--at` for precise future timestamps.
|
||||
|
||||
@@ -104,12 +105,12 @@ openclaw cron add \
|
||||
--session isolated \
|
||||
--message "Generate today's briefing: weather, calendar, top emails, news summary." \
|
||||
--model opus \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
This runs at exactly 7:00 AM New York time, uses Opus for quality, and delivers directly to WhatsApp.
|
||||
This runs at exactly 7:00 AM New York time, uses Opus for quality, and announces a summary directly to WhatsApp.
|
||||
|
||||
### Cron example: One-shot reminder
|
||||
|
||||
@@ -173,7 +174,7 @@ The most efficient setup uses **both**:
|
||||
|
||||
```bash
|
||||
# Daily morning briefing at 7am
|
||||
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver
|
||||
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
|
||||
|
||||
# Weekly project review on Mondays at 9am
|
||||
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
|
||||
@@ -214,13 +215,13 @@ See [Lobster](/tools/lobster) for full usage and examples.
|
||||
|
||||
Both heartbeat and cron can interact with the main session, but differently:
|
||||
|
||||
| | Heartbeat | Cron (main) | Cron (isolated) |
|
||||
| ------- | ------------------------------- | ------------------------ | ---------------------- |
|
||||
| Session | Main | Main (via system event) | `cron:<jobId>` |
|
||||
| History | Shared | Shared | Fresh each run |
|
||||
| Context | Full | Full | None (starts clean) |
|
||||
| Model | Main session model | Main session model | Can override |
|
||||
| Output | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Summary posted to main |
|
||||
| | Heartbeat | Cron (main) | Cron (isolated) |
|
||||
| ------- | ------------------------------- | ------------------------ | -------------------------- |
|
||||
| Session | Main | Main (via system event) | `cron:<jobId>` |
|
||||
| History | Shared | Shared | Fresh each run |
|
||||
| Context | Full | Full | None (starts clean) |
|
||||
| Model | Main session model | Main session model | Can override |
|
||||
| Output | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Announce summary (default) |
|
||||
|
||||
### When to use main session cron
|
||||
|
||||
@@ -245,7 +246,7 @@ Use `--session isolated` when you want:
|
||||
|
||||
- A clean slate without prior context
|
||||
- Different model or thinking settings
|
||||
- Output delivered directly to a channel (summary still posts to main by default)
|
||||
- Announce summaries directly to a channel
|
||||
- History that doesn't clutter main session
|
||||
|
||||
```bash
|
||||
@@ -256,7 +257,7 @@ openclaw cron add \
|
||||
--message "Weekly codebase analysis..." \
|
||||
--model opus \
|
||||
--thinking high \
|
||||
--deliver
|
||||
--announce
|
||||
```
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "Feishu bot support status, features, and configuration"
|
||||
summary: "Feishu bot overview, features, and configuration"
|
||||
read_when:
|
||||
- You want to connect a Feishu/Lark bot
|
||||
- You are configuring the Feishu channel
|
||||
@@ -8,7 +8,7 @@ title: Feishu
|
||||
|
||||
# Feishu bot
|
||||
|
||||
Status: production-ready, supports bot DMs and group chats. Uses WebSocket long connection mode to receive events.
|
||||
Feishu (Lark) is a team chat platform used by companies for messaging and collaboration. This plugin connects OpenClaw to a Feishu/Lark bot using the platform’s WebSocket event subscription so messages can be received without exposing a public webhook URL.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -16,12 +16,17 @@ Related:
|
||||
|
||||
Tip: run `openclaw cron --help` for the full command surface.
|
||||
|
||||
Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
|
||||
output internal. `--deliver` remains as a deprecated alias for `--announce`.
|
||||
|
||||
Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
|
||||
|
||||
## Common edits
|
||||
|
||||
Update delivery settings without changing the message:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --deliver --channel telegram --to "123456789"
|
||||
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
|
||||
```
|
||||
|
||||
Disable delivery for an isolated job:
|
||||
@@ -29,3 +34,9 @@ Disable delivery for an isolated job:
|
||||
```bash
|
||||
openclaw cron edit <job-id> --no-deliver
|
||||
```
|
||||
|
||||
Announce to a specific channel:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
```
|
||||
|
||||
@@ -303,7 +303,7 @@ Options:
|
||||
- `--non-interactive`
|
||||
- `--mode <local|remote>`
|
||||
- `--flow <quickstart|advanced|manual>` (manual is an alias for advanced)
|
||||
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
|
||||
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
|
||||
- `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
|
||||
- `--token <token>` (non-interactive; used with `--auth-choice token`)
|
||||
- `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
|
||||
|
||||
@@ -22,5 +22,5 @@ openclaw security audit --deep
|
||||
openclaw security audit --fix
|
||||
```
|
||||
|
||||
The audit warns when multiple DM senders share the main session and recommends `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
|
||||
The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
|
||||
It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
|
||||
|
||||
@@ -17,6 +17,26 @@ Use `session.dmScope` to control how **direct messages** are grouped:
|
||||
- `per-account-channel-peer`: isolate by account + channel + sender (recommended for multi-account inboxes).
|
||||
Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer`, `per-channel-peer`, or `per-account-channel-peer`.
|
||||
|
||||
### Secure DM mode (recommended)
|
||||
|
||||
If your agent can receive DMs from **multiple people** (pairing approvals for more than one sender, a DM allowlist with multiple entries, or `dmPolicy: "open"`), enable **secure DM mode** to avoid cross-user context leakage:
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
{
|
||||
session: {
|
||||
// Secure DM mode: isolate DM context per channel + sender.
|
||||
dmScope: "per-channel-peer",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Default is `dmScope: "main"` for continuity (all DMs share the main session).
|
||||
- For multi-account inboxes on the same channel, prefer `per-account-channel-peer`.
|
||||
- If the same person contacts you on multiple channels, use `session.identityLinks` to collapse their DM sessions into one canonical identity.
|
||||
|
||||
## Gateway is the source of truth
|
||||
|
||||
All session state is **owned by the gateway** (the “master” OpenClaw). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
|
||||
|
||||
@@ -446,6 +446,32 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
|
||||
}
|
||||
```
|
||||
|
||||
### Secure DM mode (shared inbox / multi-user DMs)
|
||||
|
||||
If more than one person can DM your bot (multiple entries in `allowFrom`, pairing approvals for multiple people, or `dmPolicy: "open"`), enable **secure DM mode** so DMs from different senders don’t share one context by default:
|
||||
|
||||
```json5
|
||||
{
|
||||
// Secure DM mode (recommended for multi-user or sensitive DM agents)
|
||||
session: { dmScope: "per-channel-peer" },
|
||||
|
||||
channels: {
|
||||
// Example: WhatsApp multi-user inbox
|
||||
whatsapp: {
|
||||
dmPolicy: "allowlist",
|
||||
allowFrom: ["+15555550123", "+15555550124"],
|
||||
},
|
||||
|
||||
// Example: Discord multi-user inbox
|
||||
discord: {
|
||||
enabled: true,
|
||||
token: "YOUR_DISCORD_BOT_TOKEN",
|
||||
dm: { enabled: true, allowFrom: ["alice", "bob"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth with API key failover
|
||||
|
||||
```json5
|
||||
|
||||
@@ -2552,7 +2552,9 @@ Notes:
|
||||
|
||||
- Set `MOONSHOT_API_KEY` in the environment or use `openclaw onboard --auth-choice moonshot-api-key`.
|
||||
- Model ref: `moonshot/kimi-k2.5`.
|
||||
- Use `https://api.moonshot.cn/v1` if you need the China endpoint.
|
||||
- For the China endpoint, either:
|
||||
- Run `openclaw onboard --auth-choice moonshot-api-key-cn` (wizard will set `https://api.moonshot.cn/v1`), or
|
||||
- Manually set `baseUrl: "https://api.moonshot.cn/v1"` in `models.providers.moonshot`.
|
||||
|
||||
### Kimi Coding
|
||||
|
||||
@@ -2764,6 +2766,7 @@ Fields:
|
||||
- `per-peer`: isolate DMs by sender id across channels.
|
||||
- `per-channel-peer`: isolate DMs per channel + sender (recommended for multi-user inboxes).
|
||||
- `per-account-channel-peer`: isolate DMs per account + channel + sender (recommended for multi-account inboxes).
|
||||
- Secure DM mode (recommended): set `session.dmScope: "per-channel-peer"` when multiple people can DM the bot (shared inboxes, multi-person allowlists, or `dmPolicy: "open"`).
|
||||
- `identityLinks`: map canonical ids to provider-prefixed peers so the same person shares a DM session across channels when using `per-peer`, `per-channel-peer`, or `per-account-channel-peer`.
|
||||
- Example: `alice: ["telegram:123456789", "discord:987654321012345678"]`.
|
||||
- `reset`: primary reset policy. Defaults to daily resets at 4:00 AM local time on the gateway host.
|
||||
|
||||
@@ -205,7 +205,16 @@ By default, OpenClaw routes **all DMs into the main session** so your assistant
|
||||
}
|
||||
```
|
||||
|
||||
This prevents cross-user context leakage while keeping group chats isolated. If you run multiple accounts on the same channel, use `per-account-channel-peer` instead. If the same person contacts you on multiple channels, use `session.identityLinks` to collapse those DM sessions into one canonical identity. See [Session Management](/concepts/session) and [Configuration](/gateway/configuration).
|
||||
This prevents cross-user context leakage while keeping group chats isolated.
|
||||
|
||||
### Secure DM mode (recommended)
|
||||
|
||||
Treat the snippet above as **secure DM mode**:
|
||||
|
||||
- Default: `session.dmScope: "main"` (all DMs share one session for continuity).
|
||||
- Secure DM mode: `session.dmScope: "per-channel-peer"` (each channel+sender pair gets an isolated DM context).
|
||||
|
||||
If you run multiple accounts on the same channel, use `per-account-channel-peer` instead. If the same person contacts you on multiple channels, use `session.identityLinks` to collapse those DM sessions into one canonical identity. See [Session Management](/concepts/session) and [Configuration](/gateway/configuration).
|
||||
|
||||
## Allowlists (DM + groups) — terminology
|
||||
|
||||
|
||||
@@ -446,7 +446,10 @@ Example voice-call config with ngrok:
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"provider": "twilio",
|
||||
"tunnel": { "provider": "ngrok" }
|
||||
"tunnel": { "provider": "ngrok" },
|
||||
"webhookSecurity": {
|
||||
"allowedHosts": ["example.ngrok.app"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -454,7 +457,7 @@ Example voice-call config with ngrok:
|
||||
}
|
||||
```
|
||||
|
||||
The ngrok tunnel runs inside the container and provides a public webhook URL without exposing the Fly app itself.
|
||||
The ngrok tunnel runs inside the container and provides a public webhook URL without exposing the Fly app itself. Set `webhookSecurity.allowedHosts` to the public tunnel hostname so forwarded host headers are accepted.
|
||||
|
||||
### Security benefits
|
||||
|
||||
|
||||
@@ -81,6 +81,12 @@ Set config under `plugins.entries.voice-call.config`:
|
||||
path: "/voice/webhook",
|
||||
},
|
||||
|
||||
// Webhook security (recommended for tunnels/proxies)
|
||||
webhookSecurity: {
|
||||
allowedHosts: ["voice.example.com"],
|
||||
trustedProxyIPs: ["100.64.0.1"],
|
||||
},
|
||||
|
||||
// Public exposure (pick one)
|
||||
// publicUrl: "https://example.ngrok.app/voice/webhook",
|
||||
// tunnel: { provider: "ngrok" },
|
||||
@@ -111,6 +117,38 @@ Notes:
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Use for local dev only.
|
||||
- Ngrok free tier URLs can change or add interstitial behavior; if `publicUrl` drifts, Twilio signatures will fail. For production, prefer a stable domain or Tailscale funnel.
|
||||
|
||||
## Webhook Security
|
||||
|
||||
When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the
|
||||
public URL for signature verification. These options control which forwarded
|
||||
headers are trusted.
|
||||
|
||||
`webhookSecurity.allowedHosts` allowlists hosts from forwarding headers.
|
||||
|
||||
`webhookSecurity.trustForwardingHeaders` trusts forwarded headers without an allowlist.
|
||||
|
||||
`webhookSecurity.trustedProxyIPs` only trusts forwarded headers when the request
|
||||
remote IP matches the list.
|
||||
|
||||
Example with a stable public host:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"voice-call": {
|
||||
config: {
|
||||
publicUrl: "https://voice.example.com/voice/webhook",
|
||||
webhookSecurity: {
|
||||
allowedHosts: ["voice.example.com"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## TTS for calls
|
||||
|
||||
Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for
|
||||
|
||||
71
docs/providers/cloudflare-ai-gateway.md
Normal file
71
docs/providers/cloudflare-ai-gateway.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: "Cloudflare AI Gateway"
|
||||
summary: "Cloudflare AI Gateway setup (auth + model selection)"
|
||||
read_when:
|
||||
- You want to use Cloudflare AI Gateway with OpenClaw
|
||||
- You need the account ID, gateway ID, or API key env var
|
||||
---
|
||||
|
||||
# Cloudflare AI Gateway
|
||||
|
||||
Cloudflare AI Gateway sits in front of provider APIs and lets you add analytics, caching, and controls. For Anthropic, OpenClaw uses the Anthropic Messages API through your Gateway endpoint.
|
||||
|
||||
- Provider: `cloudflare-ai-gateway`
|
||||
- Base URL: `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`
|
||||
- Default model: `cloudflare-ai-gateway/claude-sonnet-4-5`
|
||||
- API key: `CLOUDFLARE_AI_GATEWAY_API_KEY` (your provider API key for requests through the Gateway)
|
||||
|
||||
For Anthropic models, use your Anthropic API key.
|
||||
|
||||
## Quick start
|
||||
|
||||
1. Set the provider API key and Gateway details:
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice cloudflare-ai-gateway-api-key
|
||||
```
|
||||
|
||||
2. Set a default model:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Non-interactive example
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice cloudflare-ai-gateway-api-key \
|
||||
--cloudflare-ai-gateway-account-id "your-account-id" \
|
||||
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
|
||||
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
|
||||
```
|
||||
|
||||
## Authenticated gateways
|
||||
|
||||
If you enabled Gateway authentication in Cloudflare, add the `cf-aig-authorization` header (this is in addition to your provider API key).
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
"cloudflare-ai-gateway": {
|
||||
headers: {
|
||||
"cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Environment note
|
||||
|
||||
If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process (for example, in `~/.openclaw/.env` or via `env.shellEnv`).
|
||||
@@ -40,6 +40,7 @@ See [Venice AI](/providers/venice).
|
||||
- [Qwen (OAuth)](/providers/qwen)
|
||||
- [OpenRouter](/providers/openrouter)
|
||||
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
|
||||
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
|
||||
- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
|
||||
- [OpenCode Zen](/providers/opencode)
|
||||
- [Amazon Bedrock](/bedrock)
|
||||
|
||||
@@ -37,6 +37,7 @@ See [Venice AI](/providers/venice).
|
||||
- [Anthropic (API + Claude Code CLI)](/providers/anthropic)
|
||||
- [OpenRouter](/providers/openrouter)
|
||||
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
|
||||
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
|
||||
- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
|
||||
- [Synthetic](/providers/synthetic)
|
||||
- [OpenCode Zen](/providers/opencode)
|
||||
|
||||
@@ -106,6 +106,7 @@ Current npm plugin list (update as needed):
|
||||
- @openclaw/bluebubbles
|
||||
- @openclaw/diagnostics-otel
|
||||
- @openclaw/discord
|
||||
- @openclaw/feishu
|
||||
- @openclaw/lobster
|
||||
- @openclaw/matrix
|
||||
- @openclaw/msteams
|
||||
|
||||
@@ -95,6 +95,8 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
|
||||
- **API key**: stores the key for you.
|
||||
- **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
|
||||
- More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
|
||||
- **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
|
||||
- More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
|
||||
- **MiniMax M2.1**: config is auto-written.
|
||||
- More detail: [MiniMax](/providers/minimax)
|
||||
- **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
|
||||
@@ -239,6 +241,19 @@ openclaw onboard --non-interactive \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Cloudflare AI Gateway example:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice cloudflare-ai-gateway-api-key \
|
||||
--cloudflare-ai-gateway-account-id "your-account-id" \
|
||||
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
|
||||
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Moonshot example:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -79,6 +79,11 @@ you revoke it with `openclaw devices revoke --device <id> --role <role>`. See
|
||||
- Logs: live tail of gateway file logs with filter/export (`logs.tail`)
|
||||
- Update: run a package/git update + restart (`update.run`) with a restart report
|
||||
|
||||
Cron jobs panel notes:
|
||||
|
||||
- For isolated jobs, delivery defaults to announce summary. You can switch to none if you want internal-only runs.
|
||||
- Channel/target fields appear when announce is selected.
|
||||
|
||||
## Chat behavior
|
||||
|
||||
- `chat.send` is **non-blocking**: it acks immediately with `{ runId, status: "started" }` and the response streams via `chat` events.
|
||||
|
||||
@@ -1,39 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- 调度后台任务或唤醒
|
||||
- 配置需要与心跳一起运行或配合运行的自动化任务
|
||||
- 决定计划任务使用心跳还是定时任务
|
||||
summary: Gateway 网关调度器的定时任务与唤醒机制
|
||||
- 配置需要与心跳一起或并行运行的自动化
|
||||
- 在心跳和定时任务之间做选择
|
||||
summary: Gateway网关调度器的定时任务与唤醒
|
||||
title: 定时任务
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:44:30Z"
|
||||
generated_at: "2026-02-01T19:37:32Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d43268b0029f1b13d0825ddcc9c06a354987ea17ce02f3b5428a9c68bf936676
|
||||
source_path: automation/cron-jobs.md
|
||||
workflow: 15
|
||||
workflow: 14
|
||||
---
|
||||
|
||||
# 定时任务（Gateway 网关调度器）
|
||||
# 定时任务（Gateway网关调度器）
|
||||
|
||||
> **定时任务还是心跳？** 请参阅[定时任务与心跳对比](/automation/cron-vs-heartbeat)了解何时使用哪种方式。
|
||||
|
||||
定时任务是 Gateway 网关内置的调度器。它持久化任务，在正确的时间唤醒智能体，并可选择将输出发送回聊天。
|
||||
定时任务是 Gateway网关内置的调度器。它持久化任务、在合适的时间唤醒智能体，并可选择将输出发送回聊天。
|
||||
|
||||
如果你需要"每天早上运行这个"或"20 分钟后触发智能体"，定时任务就是实现机制。
|
||||
如果你想要 _"每天早上运行"_ 或 _"20 分钟后提醒智能体"_，定时任务就是对应的机制。
|
||||
|
||||
## 简要概述
|
||||
|
||||
- 定时任务运行在 **Gateway 网关内部**（不是在模型内部）。
|
||||
- 定时任务运行在 **Gateway网关内部**（而非模型内部）。
|
||||
- 任务持久化存储在 `~/.openclaw/cron/` 下，因此重启不会丢失计划。
|
||||
- 两种执行方式：
|
||||
- **主会话**：将系统事件加入队列，然后在下一次心跳时运行。
|
||||
- **隔离**：在 `cron:<jobId>` 中运行专用的智能体回合，可选择发送输出。
|
||||
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳"。
|
||||
- **主会话**：入队一个系统事件，然后在下一次心跳时运行。
|
||||
- **隔离式**：在 `cron:<jobId>` 中运行专用智能体轮次，可投递摘要（默认 announce）或不投递。
|
||||
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳时"。
|
||||
|
||||
## 快速开始（可操作）
|
||||
|
||||
创建一个一次性提醒，验证它是否存在，然后立即运行：
|
||||
创建一个一次性提醒，验证其存在，然后立即运行：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -49,7 +49,7 @@ openclaw cron run <job-id> --force
|
||||
openclaw cron runs --id <job-id>
|
||||
```
|
||||
|
||||
调度一个带消息发送的循环隔离任务：
|
||||
调度一个带投递功能的周期性隔离任务：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -58,168 +58,158 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize overnight updates." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel slack \
|
||||
--to "channel:C1234567890"
|
||||
```
|
||||
|
||||
## 工具调用等效项（Gateway 网关定时任务工具）
|
||||
## 工具调用等价形式（Gateway网关定时任务工具）
|
||||
|
||||
有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON schema](/automation/cron-jobs#json-schema-for-tool-calls)。
|
||||
有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON 模式](/automation/cron-jobs#json-schema-for-tool-calls)。
|
||||
|
||||
## 定时任务的存储位置
|
||||
|
||||
定时任务默认持久化存储在 Gateway 网关主机的 `~/.openclaw/cron/jobs.json`。Gateway 网关将文件加载到内存中，并在更改时写回，因此只有在 Gateway 网关停止时手动编辑才是安全的。建议使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。
|
||||
定时任务默认持久化存储在 Gateway网关主机的 `~/.openclaw/cron/jobs.json` 中。Gateway网关将文件加载到内存中，并在更改时写回，因此仅在 Gateway网关停止时手动编辑才是安全的。请优先使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。
|
||||
|
||||
## 新手友好概述
|
||||
|
||||
将定时任务理解为：**何时**运行 + **做什么**。
|
||||
|
||||
1. **选择计划**
|
||||
1. **选择调度计划**
|
||||
- 一次性提醒 → `schedule.kind = "at"`（CLI：`--at`）
|
||||
- 重复任务 → `schedule.kind = "every"` 或 `schedule.kind = "cron"`
|
||||
- 如果你的 ISO 时间戳省略了时区，它将被视为 **UTC**。
|
||||
- 如果你的 ISO 时间戳省略了时区，将被视为 **UTC**。
|
||||
|
||||
2. **选择运行位置**
|
||||
- `sessionTarget: "main"` → 在下一次心跳时使用主上下文运行。
|
||||
- `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用的智能体回合。
|
||||
- `sessionTarget: "main"` → 在下一次心跳时使用主会话上下文运行。
|
||||
- `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用智能体轮次。
|
||||
|
||||
3. **选择负载**
|
||||
- 主会话 → `payload.kind = "systemEvent"`
|
||||
- 隔离会话 → `payload.kind = "agentTurn"`
|
||||
|
||||
可选：`deleteAfterRun: true` 会在成功执行后从存储中删除一次性任务。
|
||||
可选：一次性任务（`schedule.kind = "at"`）默认会在成功运行后删除。设置
|
||||
`deleteAfterRun: false` 可保留它（成功后会禁用）。
|
||||
|
||||
## 概念
|
||||
|
||||
### 任务
|
||||
|
||||
定时任务是一个存储的记录，包含：
|
||||
定时任务是一条存储记录，包含：
|
||||
|
||||
- 一个**计划**（何时运行），
|
||||
- 一个**调度计划**（何时运行），
|
||||
- 一个**负载**（做什么），
|
||||
- 可选的**发送**（输出发送到哪里）。
|
||||
- 可选的**智能体绑定**（`agentId`）：在特定智能体下运行任务；如果缺失或未知，Gateway 网关会回退到默认智能体。
|
||||
- 可选的**投递**（输出发送到哪里）。
|
||||
- 可选的**智能体绑定**（`agentId`）：在指定智能体下运行任务；如果缺失或未知，Gateway网关会回退到默认智能体。
|
||||
|
||||
任务通过稳定的 `jobId` 标识（供 CLI/Gateway 网关 API 使用）。在智能体工具调用中，`jobId` 是规范名称；为了兼容性也接受旧版的 `id`。任务可以通过 `deleteAfterRun: true` 选择在一次性成功运行后自动删除。
|
||||
任务通过稳定的 `jobId` 标识（用于 CLI/Gateway网关 API）。
|
||||
在智能体工具调用中，`jobId` 是规范字段；旧版 `id` 仍可兼容使用。
|
||||
一次性任务默认会在成功运行后自动删除；设置 `deleteAfterRun: false` 可保留它。
|
||||
|
||||
### 计划
|
||||
### 调度计划
|
||||
|
||||
定时任务支持三种计划类型：
|
||||
定时任务支持三种调度类型：
|
||||
|
||||
- `at`：一次性时间戳（自纪元以来的毫秒数）。Gateway 网关接受 ISO 8601 并转换为 UTC。
|
||||
- `at`：一次性时间戳（ISO 8601 字符串）。
|
||||
- `every`：固定间隔（毫秒）。
|
||||
- `cron`：5 字段 cron 表达式，带可选的 IANA 时区。
|
||||
- `cron`：5 字段 cron 表达式，可选 IANA 时区。
|
||||
|
||||
Cron 表达式使用 `croner`。如果省略时区，则使用 Gateway 网关主机的本地时区。
|
||||
Cron 表达式使用 `croner`。如果省略时区，将使用 Gateway网关主机的本地时区。
|
||||
|
||||
### 主会话与隔离执行
|
||||
### 主会话与隔离式执行
|
||||
|
||||
#### 主会话任务（系统事件）
|
||||
|
||||
主任务将系统事件加入队列并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。
|
||||
主会话任务入队一个系统事件，并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。
|
||||
|
||||
- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划的心跳。
|
||||
- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划心跳。
|
||||
- `wakeMode: "now"`：事件触发立即心跳运行。
|
||||
|
||||
当你需要正常的心跳提示 + 主会话上下文时，这是最佳选择。参见[心跳](/gateway/heartbeat)。
|
||||
|
||||
#### 隔离任务（专用定时会话）
|
||||
|
||||
隔离任务在会话 `cron:<jobId>` 中运行专用的智能体回合。
|
||||
隔离任务在会话 `cron:<jobId>` 中运行专用智能体轮次。
|
||||
|
||||
关键行为：
|
||||
|
||||
- 提示以 `[cron:<jobId> <job name>]` 为前缀以便追踪。
|
||||
- 每次运行启动一个**新的会话 id**（没有先前的对话延续）。
|
||||
- 摘要会发布到主会话（前缀 `Cron`，可配置）。
|
||||
- `wakeMode: "now"` 在发布摘要后触发立即心跳。
|
||||
- 如果 `payload.deliver: true`，输出会发送到渠道；否则保持内部。
|
||||
- 提示以 `[cron:<jobId> <任务名称>]` 为前缀，便于追踪。
|
||||
- 每次运行都会启动一个**全新的会话 ID**（不继承之前的对话）。
|
||||
- 如果未指定 `delivery`，隔离任务会默认以“announce”方式投递摘要。
|
||||
- `delivery.mode` 可选 `announce`（投递摘要）或 `none`（内部运行）。
|
||||
|
||||
对于嘈杂、频繁或不应该刷屏主聊天历史的"后台杂务"，使用隔离任务。
|
||||
对于嘈杂、频繁或"后台杂务"类任务，使用隔离任务可以避免污染你的主聊天记录。
|
||||
|
||||
### 负载结构（运行什么）
|
||||
### 负载结构（运行内容）
|
||||
|
||||
支持两种负载类型：
|
||||
|
||||
- `systemEvent`：仅限主会话，通过心跳提示路由。
|
||||
- `agentTurn`：仅限隔离会话，运行专用的智能体回合。
|
||||
- `agentTurn`：仅限隔离会话，运行专用智能体轮次。
|
||||
|
||||
常见的 `agentTurn` 字段：
|
||||
常用 `agentTurn` 字段：
|
||||
|
||||
- `message`：必需的文本提示。
|
||||
- `message`：必填文本提示。
|
||||
- `model` / `thinking`：可选覆盖（见下文）。
|
||||
- `timeoutSeconds`：可选的超时覆盖。
|
||||
- `deliver`：`true` 则将输出发送到渠道目标。
|
||||
- `channel`：`last` 或特定渠道。
|
||||
- `to`：特定于渠道的目标（电话/聊天/频道 id）。
|
||||
- `bestEffortDeliver`：发送失败时避免任务失败。
|
||||
- `timeoutSeconds`：可选超时覆盖。
|
||||
|
||||
隔离选项（仅适用于 `session=isolated`）：
|
||||
### 模型和思维覆盖
|
||||
|
||||
- `postToMainPrefix`（CLI：`--post-prefix`）：主会话中系统事件的前缀。
|
||||
- `postToMainMode`：`summary`（默认）或 `full`。
|
||||
- `postToMainMaxChars`：当 `postToMainMode=full` 时的最大字符数（默认 8000）。
|
||||
|
||||
### 模型和思考覆盖
|
||||
|
||||
隔离任务（`agentTurn`）可以覆盖模型和思考级别：
|
||||
隔离任务（`agentTurn`）可以覆盖模型和思维级别：
|
||||
|
||||
- `model`：提供商/模型字符串（例如 `anthropic/claude-sonnet-4-20250514`）或别名（例如 `opus`）
|
||||
- `thinking`：思考级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型）
|
||||
- `thinking`：思维级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型）
|
||||
|
||||
注意：你也可以在主会话任务上设置 `model`，但它会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。
|
||||
注意：你也可以在主会话任务上设置 `model`，但这会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。
|
||||
|
||||
解析优先级：
|
||||
优先级解析顺序：
|
||||
|
||||
1. 任务负载覆盖（最高）
|
||||
1. 任务负载覆盖（最高优先级）
|
||||
2. 钩子特定默认值（例如 `hooks.gmail.model`）
|
||||
3. 智能体配置默认值
|
||||
|
||||
### 发送（渠道 + 目标）
|
||||
### 投递（渠道 + 目标）
|
||||
|
||||
隔离任务可以将输出发送到渠道。任务负载可以指定：
|
||||
隔离任务可以通过顶层 `delivery` 配置投递输出：
|
||||
|
||||
- `channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last`
|
||||
- `to`：特定于渠道的接收者目标
|
||||
- `delivery.mode`：`announce`（投递摘要）或 `none`
|
||||
- `delivery.channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last`
|
||||
- `delivery.to`：渠道特定的接收目标
|
||||
- `delivery.bestEffort`：投递失败时避免任务失败
|
||||
|
||||
如果省略 `channel` 或 `to`，定时任务可以回退到主会话的"最后路由"（智能体最后回复的位置）。
|
||||
当启用 announce 投递时，该轮次会抑制消息工具发送；请使用 `delivery.channel`/`delivery.to` 来指定目标。
|
||||
|
||||
发送说明：
|
||||
|
||||
- 如果设置了 `to`，即使省略了 `deliver`，定时任务也会自动发送智能体的最终输出。
|
||||
- 当你想要不带显式 `to` 的最后路由发送时，使用 `deliver: true`。
|
||||
- 使用 `deliver: false` 即使存在 `to` 也保持输出在内部。
|
||||
如果省略 `delivery.channel` 或 `delivery.to`，定时任务会回退到主会话的“最后路由”（智能体最后回复的位置）。
|
||||
|
||||
目标格式提醒：
|
||||
|
||||
- Slack/Discord/Mattermost（插件）目标应使用显式前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
|
||||
- Telegram 话题应使用 `:topic:` 形式（见下文）。
|
||||
- Slack/Discord/Mattermost（插件）目标应使用明确前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
|
||||
- Telegram 主题应使用 `:topic:` 格式（见下文）。
|
||||
|
||||
#### Telegram 发送目标（话题/论坛帖子）
|
||||
#### Telegram 投递目标（主题/论坛帖子）
|
||||
|
||||
Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发送，你可以将话题/帖子编码到 `to` 字段中：
|
||||
Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投递，你可以将主题/帖子编码到 `to` 字段中：
|
||||
|
||||
- `-1001234567890`（仅聊天 id）
|
||||
- `-1001234567890:topic:123`（推荐：显式话题标记）
|
||||
- `-1001234567890`（仅聊天 ID）
|
||||
- `-1001234567890:topic:123`（推荐：明确的主题标记）
|
||||
- `-1001234567890:123`（简写：数字后缀）
|
||||
|
||||
带前缀的目标如 `telegram:...` / `telegram:group:...` 也被接受：
|
||||
带前缀的目标如 `telegram:...` / `telegram:group:...` 也可接受：
|
||||
|
||||
- `telegram:group:-1001234567890:topic:123`
|
||||
|
||||
## 工具调用的 JSON schema
|
||||
## 工具调用的 JSON 模式
|
||||
|
||||
直接调用 Gateway 网关 `cron.*` 工具时（智能体工具调用或 RPC）使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用对 `atMs` 和 `everyMs` 使用纪元毫秒（`at` 时间接受 ISO 时间戳）。
|
||||
直接调用 Gateway网关 `cron.*` 工具（智能体工具调用或 RPC）时使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用应使用 ISO 8601 字符串作为 `schedule.at`，并使用毫秒作为 `schedule.everyMs`。
|
||||
|
||||
### cron.add 参数
|
||||
|
||||
一次性，主会话任务（系统事件）：
|
||||
一次性主会话任务（系统事件）：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Reminder",
|
||||
"schedule": { "kind": "at", "atMs": 1738262400000 },
|
||||
"schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
|
||||
"sessionTarget": "main",
|
||||
"wakeMode": "now",
|
||||
"payload": { "kind": "systemEvent", "text": "Reminder text" },
|
||||
@@ -227,7 +217,7 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
}
|
||||
```
|
||||
|
||||
循环，带发送的隔离任务：
|
||||
带投递的周期性隔离任务：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -237,22 +227,24 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
"wakeMode": "next-heartbeat",
|
||||
"payload": {
|
||||
"kind": "agentTurn",
|
||||
"message": "Summarize overnight updates.",
|
||||
"deliver": true,
|
||||
"message": "Summarize overnight updates."
|
||||
},
|
||||
"delivery": {
|
||||
"mode": "announce",
|
||||
"channel": "slack",
|
||||
"to": "channel:C1234567890",
|
||||
"bestEffortDeliver": true
|
||||
},
|
||||
"isolation": { "postToMainPrefix": "Cron", "postToMainMode": "summary" }
|
||||
"bestEffort": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `schedule.kind`：`at`（`atMs`）、`every`（`everyMs`）或 `cron`（`expr`，可选 `tz`）。
|
||||
- `atMs` 和 `everyMs` 是纪元毫秒。
|
||||
- `sessionTarget` 必须是 `"main"` 或 `"isolated"` 并且必须与 `payload.kind` 匹配。
|
||||
- 可选字段：`agentId`、`description`、`enabled`、`deleteAfterRun`、`isolation`。
|
||||
- `schedule.kind`：`at`（`at`）、`every`（`everyMs`）或 `cron`（`expr`，可选 `tz`）。
|
||||
- `schedule.at` 接受 ISO 8601（可省略时区；省略时按 UTC 处理）。
|
||||
- `everyMs` 为毫秒数。
|
||||
- `sessionTarget` 必须为 `"main"` 或 `"isolated"`，且必须与 `payload.kind` 匹配。
|
||||
- 可选字段：`agentId`、`description`、`enabled`、`deleteAfterRun`、`delivery`。
|
||||
- `wakeMode` 省略时默认为 `"next-heartbeat"`。
|
||||
|
||||
### cron.update 参数
|
||||
@@ -269,8 +261,8 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
|
||||
说明：
|
||||
|
||||
- `jobId` 是规范名称；为了兼容性也接受 `id`。
|
||||
- 在补丁中使用 `agentId: null` 来清除智能体绑定。
|
||||
- `jobId` 是规范字段；`id` 可兼容使用。
|
||||
- 在补丁中使用 `agentId: null` 可清除智能体绑定。
|
||||
|
||||
### cron.run 和 cron.remove 参数
|
||||
|
||||
@@ -282,9 +274,9 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
{ "jobId": "job-123" }
|
||||
```
|
||||
|
||||
## 存储和历史
|
||||
## 存储与历史
|
||||
|
||||
- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway 网关管理的 JSON）。
|
||||
- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway网关管理的 JSON）。
|
||||
- 运行历史：`~/.openclaw/cron/runs/<jobId>.jsonl`（JSONL，自动清理）。
|
||||
- 覆盖存储路径：配置中的 `cron.store`。
|
||||
|
||||
@@ -330,7 +322,7 @@ openclaw cron add \
|
||||
--wake now
|
||||
```
|
||||
|
||||
循环隔离任务（发送到 WhatsApp）：
|
||||
周期性隔离任务（投递到 WhatsApp）：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -339,12 +331,12 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize inbox + calendar for today." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
循环隔离任务（发送到 Telegram 话题）：
|
||||
周期性隔离任务（投递到 Telegram 主题）：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -353,12 +345,12 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize today; send to the nightly topic." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel telegram \
|
||||
--to "-1001234567890:topic:123"
|
||||
```
|
||||
|
||||
带模型和思考覆盖的隔离任务：
|
||||
带模型和思维覆盖的隔离任务：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -369,15 +361,15 @@ openclaw cron add \
|
||||
--message "Weekly deep analysis of project progress." \
|
||||
--model "opus" \
|
||||
--thinking high \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
智能体选择（多智能体设置）：
|
||||
智能体选择（多智能体配置）：
|
||||
|
||||
```bash
|
||||
# 将任务绑定到智能体"ops"（如果该智能体不存在则回退到默认）
|
||||
# 将任务绑定到智能体 "ops"（如果该智能体不存在则回退到默认智能体）
|
||||
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
|
||||
|
||||
# 切换或清除现有任务的智能体
|
||||
@@ -406,27 +398,27 @@ openclaw cron edit <jobId> \
|
||||
openclaw cron runs --id <jobId> --limit 50
|
||||
```
|
||||
|
||||
不创建任务的立即系统事件：
|
||||
不创建任务直接发送系统事件：
|
||||
|
||||
```bash
|
||||
openclaw system event --mode now --text "Next heartbeat: check battery."
|
||||
```
|
||||
|
||||
## Gateway 网关 API 接口
|
||||
## Gateway网关 API 接口
|
||||
|
||||
- `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`
|
||||
- `cron.run`（强制或到期）、`cron.runs`
|
||||
对于不创建任务的立即系统事件，使用 [`openclaw system event`](/cli/system)。
|
||||
如需不创建任务直接发送系统事件，请使用 [`openclaw system event`](/cli/system)。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### "什么都不运行"
|
||||
### "没有任何任务运行"
|
||||
|
||||
- 检查定时任务是否启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。
|
||||
- 检查 Gateway 网关是否持续运行（定时任务在 Gateway 网关进程内运行）。
|
||||
- 对于 `cron` 计划：确认时区（`--tz`）与主机时区的关系。
|
||||
- 检查定时任务是否已启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。
|
||||
- 检查 Gateway网关是否持续运行（定时任务运行在 Gateway网关进程内部）。
|
||||
- 对于 `cron` 调度：确认时区（`--tz`）与主机时区的关系。
|
||||
|
||||
### Telegram 发送到错误的位置
|
||||
### Telegram 投递到了错误的位置
|
||||
|
||||
- 对于论坛话题，使用 `-100…:topic:<id>` 以确保明确无歧义。
|
||||
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务发送接受它们并仍然正确解析话题 ID。
|
||||
- 对于论坛主题，使用 `-100…:topic:<id>` 以确保明确无歧义。
|
||||
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务投递接受这些前缀并仍能正确解析主题 ID。
|
||||
|
||||
@@ -97,7 +97,7 @@ x-i18n:
|
||||
- **精确定时**：支持带时区的 5 字段 cron 表达式。
|
||||
- **会话隔离**：在 `cron:<jobId>` 中运行，不会污染主会话历史。
|
||||
- **模型覆盖**：可按任务使用更便宜或更强大的模型。
|
||||
- **投递控制**：可直接投递到渠道；默认仍会向主会话发布摘要（可配置）。
|
||||
- **投递控制**：隔离任务默认以 `announce` 投递摘要，可选 `none` 仅内部运行。
|
||||
- **无需智能体上下文**：即使主会话空闲或已压缩，也能运行。
|
||||
- **一次性支持**：`--at` 用于精确的未来时间戳。
|
||||
|
||||
@@ -111,7 +111,7 @@ openclaw cron add \
|
||||
--session isolated \
|
||||
--message "Generate today's briefing: weather, calendar, top emails, news summary." \
|
||||
--model opus \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
@@ -180,7 +180,7 @@ openclaw cron add \
|
||||
|
||||
```bash
|
||||
# 每天早上 7 点的早间简报
|
||||
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver
|
||||
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
|
||||
|
||||
# 每周一上午 9 点的项目回顾
|
||||
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
|
||||
@@ -219,13 +219,13 @@ Lobster 是用于**多步骤工具管道**的工作流运行时，适用于需
|
||||
|
||||
心跳和定时任务都可以与主会话交互，但方式不同：
|
||||
|
||||
| | 心跳 | 定时任务（主会话） | 定时任务（隔离式） |
|
||||
| ------ | ------------------------ | ---------------------- | ------------------ |
|
||||
| 会话 | 主会话 | 主会话（通过系统事件） | `cron:<jobId>` |
|
||||
| 历史 | 共享 | 共享 | 每次运行全新 |
|
||||
| 上下文 | 完整 | 完整 | 无（从零开始） |
|
||||
| 模型 | 主会话模型 | 主会话模型 | 可覆盖 |
|
||||
| 输出 | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件 | 摘要发布到主会话 |
|
||||
| | 心跳 | 定时任务（主会话） | 定时任务（隔离式） |
|
||||
| ------ | ------------------------ | ---------------------- | --------------------- |
|
||||
| 会话 | 主会话 | 主会话（通过系统事件） | `cron:<jobId>` |
|
||||
| 历史 | 共享 | 共享 | 每次运行全新 |
|
||||
| 上下文 | 完整 | 完整 | 无（从零开始） |
|
||||
| 模型 | 主会话模型 | 主会话模型 | 可覆盖 |
|
||||
| 输出 | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件 | announce 摘要（默认） |
|
||||
|
||||
### 何时使用主会话定时任务
|
||||
|
||||
@@ -250,7 +250,7 @@ openclaw cron add \
|
||||
|
||||
- 无先前上下文的全新环境
|
||||
- 不同的模型或思维设置
|
||||
- 输出直接投递到渠道（摘要默认仍会发布到主会话）
|
||||
- 输出可通过 `announce` 直接投递摘要（或用 `none` 仅内部运行）
|
||||
- 不会把主会话搞得杂乱的历史记录
|
||||
|
||||
```bash
|
||||
@@ -261,7 +261,7 @@ openclaw cron add \
|
||||
--message "Weekly codebase analysis..." \
|
||||
--model opus \
|
||||
--thinking high \
|
||||
--deliver
|
||||
--announce
|
||||
```
|
||||
|
||||
## 成本考量
|
||||
|
||||
@@ -23,12 +23,17 @@ x-i18n:
|
||||
|
||||
提示：运行 `openclaw cron --help` 查看完整的命令集。
|
||||
|
||||
## 常用编辑
|
||||
说明：隔离式 `cron add` 任务默认使用 `--announce` 投递摘要。使用 `--no-deliver` 仅内部运行。
|
||||
`--deliver` 仍作为 `--announce` 的弃用别名保留。
|
||||
|
||||
说明：一次性（`--at`）任务成功后默认删除。使用 `--keep-after-run` 保留。
|
||||
|
||||
## 常见编辑
|
||||
|
||||
更新投递设置而不更改消息：
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --deliver --channel telegram --to "123456789"
|
||||
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
|
||||
```
|
||||
|
||||
为隔离的作业禁用投递：
|
||||
|
||||
Reference in New Issue
Block a user