- BlueBubbles: add opt-in `channels.bluebubbles.replyContextApiFallback` that fetches the original message from the BlueBubbles HTTP API when the in-memory reply-context cache misses (multi-instance deployments sharing one BB account, post-restart, after long-lived TTL/LRU eviction). Off by default; channel-level setting propagates to accounts that omit the flag through `mergeAccountConfig`; routed through the typed `BlueBubblesClient` so every fetch is SSRF-guarded by the same three-mode policy as every other BB client request; reply-id shape is validated and part-index prefixes (`p:0/<guid>`) are stripped before the request; concurrent webhooks for the same `replyToId` coalesce into one fetch and successful responses populate the reply cache for subsequent hits. Also promotes BlueBubbles attachment download failures from verbose to runtime error so silently-dropped inbound images are visible at default log level, and extends `sanitizeForLog` to redact `?password=…`/`?token=…` query params and `Authorization:` headers before they reach the log sink (CWE-532). (#71820) Thanks @coletebou and @zqchris.

- CLI/proxy: add `openclaw proxy validate` so operators can verify effective proxy configuration, proxy reachability, and expected allow/deny destination behavior before deploying proxy-routed OpenClaw commands. (#73438) Thanks @jesse-merhi.

- Agents/Codex: default Codex app-server dynamic tools to native-first, keeping OpenClaw integration tools while leaving file, patch, exec, and process ownership to the Codex harness. (#75308) Thanks @pashpashpash.

- Agents/Codex: default Codex-harness direct source replies to the OpenClaw `message` tool when visible reply delivery is not explicitly configured, keeping channel-visible output as a deliberate tool call. Thanks @pashpashpash.

- Heartbeats/agents: add a structured `heartbeat_respond` tool for tool-capable heartbeat runs so agents can record quiet outcomes or explicit notification text without relying only on `HEARTBEAT_OK` parsing. Thanks @pashpashpash.

### Fixes

37787172adf7a55a32097599b4bf5729fc7138c8743c6f4c9d58fc8d01df72a1 plugin-sdk-api-baseline.json

0ec4957528477832085c638a5f7f691c878ba199f3e81f330f162c27cfd9ebf4 plugin-sdk-api-baseline.jsonl

42cb8c8be1e10a42891035fc402022ab1cc2eb941e7e69a9a2f8a6d01a30bd3e plugin-sdk-api-baseline.json

4bafb4519802e0daeb8458d9aed9b09d2fc51755f02d1568a368d814c6f7930a plugin-sdk-api-baseline.jsonl

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.

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.

```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

`messages.groupChat.historyLimit` sets the global default. Channels can override with `channels.<channel>.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

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

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,

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:

return {

id: options?.id ?? "codex",

label: options?.label ?? "Codex agent harness",

deliveryDefaults: {

sourceVisibleReplies: "message_tool",

},

supports: (ctx) => {

const provider = ctx.provider.trim().toLowerCase();

if (providerIds.has(provider)) {

expect(registerAgentHarness.mock.calls[0]?.[0]).toMatchObject({

id: "codex",

label: "Codex agent harness",

deliveryDefaults: { sourceVisibleReplies: "message_tool" },

dispose: expect.any(Function),

});

expect(registerMediaUnderstandingProvider.mock.calls[0]?.[0]).toMatchObject({

it("only claims the codex provider by default", () => {

const harness = createCodexAppServerAgentHarness();

expect(harness.deliveryDefaults?.sourceVisibleReplies).toBe("message_tool");

expect(

harness.supports({ provider: "codex", modelId: "gpt-5.4", requestedRuntime: "auto" })

.supported,

import type { AgentToolResult } from "@mariozechner/pi-agent-core";

import type { AnyAgentTool } from "openclaw/plugin-sdk/agent-harness";

import { wrapToolWithBeforeToolCallHook } from "openclaw/plugin-sdk/agent-harness-runtime";

import {

HEARTBEAT_RESPONSE_TOOL_NAME,

wrapToolWithBeforeToolCallHook,

} from "openclaw/plugin-sdk/agent-harness-runtime";

import {

initializeGlobalHookRunner,

resetGlobalHookRunner,

});

});

it("records heartbeat response tool outcomes", async () => {

const bridge = createBridgeWithToolResult(

HEARTBEAT_RESPONSE_TOOL_NAME,

textToolResult("Recorded.", {

status: "recorded",

outcome: "needs_attention",

notify: true,

summary: "Build is blocked.",

notificationText: "Build is blocked on missing credentials.",

priority: "high",

}),

);

const result = await bridge.handleToolCall({

threadId: "thread-1",

turnId: "turn-1",

callId: "call-1",

namespace: null,

tool: HEARTBEAT_RESPONSE_TOOL_NAME,

arguments: {},

});

expect(result).toEqual(expectInputText("Recorded."));

expect(bridge.telemetry.heartbeatToolResponse).toEqual({

outcome: "needs_attention",

notify: true,

summary: "Build is blocked.",

notificationText: "Build is blocked on missing credentials.",

priority: "high",

});

});

it("applies agent tool result middleware from the active plugin registry", async () => {

const registry = createEmptyPluginRegistry();

const handler = vi.fn(

createCodexAppServerToolResultExtensionRunner,

extractToolResultMediaArtifact,

filterToolResultMediaUrls,

HEARTBEAT_RESPONSE_TOOL_NAME,

isToolWrappedWithBeforeToolCallHook,

isMessagingTool,

isMessagingToolSendAction,

normalizeHeartbeatToolResponse,

runAgentHarnessAfterToolCallHook,

type AnyAgentTool,

type HeartbeatToolResponse,

type MessagingToolSend,

wrapToolWithBeforeToolCallHook,

} from "openclaw/plugin-sdk/agent-harness-runtime";

messagingToolSentTexts: string[];

messagingToolSentMediaUrls: string[];

messagingToolSentTargets: MessagingToolSend[];

heartbeatToolResponse?: HeartbeatToolResponse;

toolMediaUrls: string[];

toolAudioAsVoice: boolean;

successfulCronAdds?: number;

if (!params.isError && params.toolName === "cron" && isCronAddAction(params.args)) {

params.telemetry.successfulCronAdds = (params.telemetry.successfulCronAdds ?? 0) + 1;

}

if (!params.isError && params.toolName === HEARTBEAT_RESPONSE_TOOL_NAME) {

const response = normalizeHeartbeatToolResponse(params.result?.details);

if (response) {

params.telemetry.heartbeatToolResponse = response;

}

}

if (!params.isError && params.result) {

const media = extractToolResultMediaArtifact(params.result);

if (media) {

status !== "ok" &&

status !== "success" &&

status !== "completed" &&

status !== "recorded" &&

status !== "running"

);

}