diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index c742e40ea..c6efa6601 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "f858b5de22083a4459f29d70e3dd2265ff45d113", - "syncedAt": "2026-05-01T15:23:19.907Z" + "sha": "439d8edf68e2b650bc47ecb7edc82ccffbe74570", + "syncedAt": "2026-05-01T18:31:52.033Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index c03babba3..9c6953fd0 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -37787172adf7a55a32097599b4bf5729fc7138c8743c6f4c9d58fc8d01df72a1 plugin-sdk-api-baseline.json -0ec4957528477832085c638a5f7f691c878ba199f3e81f330f162c27cfd9ebf4 plugin-sdk-api-baseline.jsonl +42cb8c8be1e10a42891035fc402022ab1cc2eb941e7e69a9a2f8a6d01a30bd3e plugin-sdk-api-baseline.json +4bafb4519802e0daeb8458d9aed9b09d2fc51755f02d1568a368d814c6f7930a plugin-sdk-api-baseline.jsonl diff --git a/docs/channels/groups.md b/docs/channels/groups.md index 37a234aa2..2e65f573f 100644 --- a/docs/channels/groups.md +++ b/docs/channels/groups.md @@ -47,7 +47,7 @@ If the message tool is unavailable under the active tool policy, OpenClaw falls back to automatic visible replies instead of silently suppressing the response. `openclaw doctor` warns about this mismatch. -For direct chats and any other source turn, use `messages.visibleReplies: "message_tool"` to apply the same tool-only visible-reply behavior globally. `messages.groupChat.visibleReplies` remains the more specific override for group/channel rooms. +For direct chats and any other source turn, use `messages.visibleReplies: "message_tool"` to apply the same tool-only visible-reply behavior globally. Harnesses can also choose this as their unset default; the Codex harness does this for Codex-mode direct chats. `messages.groupChat.visibleReplies` remains the more specific override for group/channel rooms. This replaces the old pattern of forcing the model to answer `NO_REPLY` for most lurk-mode turns. In tool-only mode, doing nothing visible simply means not calling the message tool. diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md index b551d8107..11ef585e1 100644 --- a/docs/gateway/config-channels.md +++ b/docs/gateway/config-channels.md @@ -774,7 +774,7 @@ See the full channel index: [Channels](/channels). Group messages default to **require mention** (metadata mention or safe regex patterns). Applies to WhatsApp, Telegram, Discord, Google Chat, and iMessage group chats. -Visible replies are controlled separately. Group/channel rooms default to `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw still processes the turn, but normal final replies stay private and visible room output requires `message(action=send)`. Set `"automatic"` only when you want the legacy behavior where normal replies are posted back to the room. To apply the same tool-only visible-reply behavior to direct chats too, set `messages.visibleReplies: "message_tool"`. +Visible replies are controlled separately. Group/channel rooms default to `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw still processes the turn, but normal final replies stay private and visible room output requires `message(action=send)`. Set `"automatic"` only when you want the legacy behavior where normal replies are posted back to the room. To apply the same tool-only visible-reply behavior to direct chats too, set `messages.visibleReplies: "message_tool"`; the Codex harness also uses that tool-only behavior as its unset direct-chat default. If the message tool is unavailable under the active tool policy, OpenClaw falls back to automatic visible replies instead of silently suppressing the response. `openclaw doctor` warns about this mismatch. @@ -789,7 +789,7 @@ The gateway hot-reloads `messages` config after the file is saved. Restart only ```json5 { messages: { - visibleReplies: "automatic", // global default for direct/source chats + visibleReplies: "automatic", // global default for direct/source chats; Codex harness defaults unset direct chats to message_tool groupChat: { historyLimit: 50, visibleReplies: "message_tool", // default; use "automatic" for legacy final replies @@ -803,7 +803,7 @@ The gateway hot-reloads `messages` config after the file is saved. Restart only `messages.groupChat.historyLimit` sets the global default. Channels can override with `channels..historyLimit` (or per-account). Set `0` to disable. -`messages.visibleReplies` is the global source-turn default; `messages.groupChat.visibleReplies` overrides it for group/channel source turns. Channel allowlists and mention gating still decide whether a turn is processed. +`messages.visibleReplies` is the global source-turn default; `messages.groupChat.visibleReplies` overrides it for group/channel source turns. When `messages.visibleReplies` is unset, a harness can provide its own direct/source default; the Codex harness defaults to `message_tool`. Channel allowlists and mention gating still decide whether a turn is processed. #### DM history limits diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md index b7533e2de..bd357f1ad 100644 --- a/docs/gateway/heartbeat.md +++ b/docs/gateway/heartbeat.md @@ -82,6 +82,7 @@ If you want a heartbeat to do something very specific (e.g. "check Gmail PubSub ## Response contract - If nothing needs attention, reply with **`HEARTBEAT_OK`**. +- Tool-capable heartbeat runs may instead call `heartbeat_respond` with `notify: false` for no visible update, or `notify: true` plus `notificationText` for an alert. When present, the structured tool response takes precedence over the text fallback. - During heartbeat runs, OpenClaw treats `HEARTBEAT_OK` as an ack when it appears at the **start or end** of the reply. The token is stripped and the reply is dropped if the remaining content is **≤ `ackMaxChars`** (default: 300). - If `HEARTBEAT_OK` appears in the **middle** of a reply, it is not treated specially. - For alerts, **do not** include `HEARTBEAT_OK`; return only the alert text. diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 27daed56e..d7175aadb 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -15,6 +15,17 @@ discovery, native thread resume, native compaction, and app-server execution. OpenClaw still owns chat channels, session files, model selection, tools, approvals, media delivery, and the visible transcript mirror. +When a source chat turn runs through the Codex harness, visible replies default +to the OpenClaw `message` tool if the deployment has not explicitly configured +`messages.visibleReplies`. The agent can still finish its Codex turn privately; +it only posts to the channel when it calls `message(action="send")`. Set +`messages.visibleReplies: "automatic"` to keep direct-chat final replies on the +legacy automatic delivery path. + +Codex heartbeat turns also get the `heartbeat_respond` tool by default, so the +agent can record whether the wake should stay quiet or notify without encoding +that control flow in final text. + If you are trying to orient yourself, start with [Agent runtimes](/concepts/agent-runtimes). The short version is: `openai/gpt-5.5` is the model ref, `codex` is the runtime, and Telegram, @@ -583,7 +594,8 @@ Codex dynamic tools default to the `native-first` profile. In that mode, OpenClaw does not expose dynamic tools that duplicate Codex-native workspace operations: `read`, `write`, `edit`, `apply_patch`, `exec`, `process`, and `update_plan`. OpenClaw integration tools such as messaging, sessions, media, -cron, browser, nodes, gateway, and `web_search` remain available. +cron, browser, nodes, gateway, `heartbeat_respond`, and `web_search` remain +available. Supported top-level Codex plugin fields: