Debug retries, duplicates, and delivery claims

Verifiedon 2026-07-302026.7.1

“Sent” is not a delivery status

A process can accept an event, enqueue work, attempt a provider request, receive an acknowledgement, and still fail to prove that the intended recipient received the message. Treating all five states as “sent” makes retries dangerous. A transport timeout is ambiguous: the provider may have accepted the request while your process lost the response.

Use the current OpenClaw documentation index and official release history to verify the exact channel and Gateway behavior you are operating. This course was reviewed against OpenClaw 2026.7.1, revision 2d2ddc43d0dcf71f31283d780f9fe9ff4cc04fe4, checked 2026-07-30. The examples below use a synthetic event and a test recipient; they do not prescribe provider-specific retry settings.

The durable decision record

Before any external side effect, create or look up a record keyed by a stable event identity. Prefer the provider’s event ID when it is unique within the relevant scope. If the provider does not provide one, derive an owned idempotency key from stable inputs such as provider scope, sender identity, event timestamp bucket, and a payload fingerprint. Never use a random request ID as the only deduplication key; a retry would produce a new random value and look like new work.

Record at least:

• event ID and provider scope;
• verified sender identity and endpoint evidence reference;
• route version and policy outcome;
• approval ID, destination, and approval expiry when delivery is possible;
• outbound intent fingerprint, not raw sensitive content;
• provider receipt reference and state transitions;
• timestamps, owner, and unresolved reason.

The record is a state machine, not a log line. A second event with the same key should find the first terminal decision before creating a second side effect. If the first run is unresolved, hold and ask an operator to reconcile; do not “retry until it works.”

Worked example: timeout after outbound attempt

A synthetic event evt-test-0042 passes the route matrix and has approval appr-test-009. The adapter attempts delivery to reviewer-test-room, then times out. Local state is attempted, provider receipt is unknown. The safe next step is not another send. Inspect provider evidence using the documented event or message reference, check whether the process is still running, and leave the record unresolved-provider-status until an operator classifies it. If evidence proves no request was accepted, a bounded retry may be possible with the same idempotency key. If evidence proves delivery, mark confirmed and suppress the retry.

key = "synthetic-webhook:evt-test-0042"
record = decisions.find(key)
if record?.state in ["attempted", "acknowledged", "confirmed"]:
return { action: "suppress-duplicate", state: record.state }
if record?.state == "unresolved-provider-status":
return { action: "hold-for-reconciliation" }
return { action: "evaluate-route-before-attempt" }

This is pseudocode for a lab discussion, not a drop-in OpenClaw command. The provider’s event ID, acknowledgement, and receipt semantics must be verified from its primary documentation.

Debug in a fixed order

When a learner reports “the message did not send,” do not start by increasing retries. Trace: provider event ID → endpoint/signature verification → stable sender → route decision → idempotency record → approval decision → exact recipient → outbound attempt → provider receipt. Stop at the first unproved boundary. If the event ID is absent, you cannot safely distinguish duplicate from new. If the recipient is not exact, you cannot claim a delivery attempt was safe. If approval is expired, the correct action is hold even if the provider is healthy.

Separate four operational questions in the incident record:

1. Did OpenClaw accept the inbound event?
2. Did policy permit this action and destination?
3. Did the adapter make an outbound attempt?
4. What evidence supports the provider delivery state?

A “yes” to the first question never implies “yes” to the fourth.

Lab: replay and ambiguity drill

In a disposable test channel, inject one synthetic event with a stable event ID. Run the workflow twice, including a simulated timeout between outbound attempt and response. Collect the decision record, route version, approval ID, destination class, and provider receipt reference. Expected output: one durable decision for the event, one outbound intent, and either a confirmed receipt or an unresolved state requiring reconciliation. There must be no second external side effect.

The learner artifact is that redacted decision record and its replay evidence: the stable event key, state transitions, route and approval references, destination class, provider receipt reference, and a note explaining why the retry was suppressed or held.

Then replay the same payload with a different event ID. Treat it as a new event only if the provider semantics say it is a distinct event; otherwise hold for operator review. Finally, send an event with an unknown destination and verify the route matrix stops it before any outbound attempt.

Failure cases and rollback

Common failures include deduplicating only in process memory, overwriting the first decision with the retry, using a payload hash that includes volatile timestamps, and logging raw messages into an audit store. Fix them by persisting a scoped key, keeping state transitions append-only or versioned, defining the fingerprint inputs, and retaining metadata rather than content. If two legitimate events share a provider ID across scopes, include provider/channel scope in the key and stop until the collision rule is reviewed.

Rollback is to stop retries and disable the affected outbound route, preserve the unresolved record, and reconcile against provider evidence. Do not delete a duplicate record to make the test look clean. A learner passes when the evidence pack proves one event, one decision, one approved outbound intent, and a clear unresolved path for ambiguous status. Lesson 5 places a human decision at the point where this record would otherwise authorize delivery.

Source receipt

Primary source: OpenClaw docs index. Version/revision: OpenClaw 2026.7.1, 2d2ddc43d0dcf71f31283d780f9fe9ff4cc04fe4, reviewed 2026-07-30. Official releases are the authority for changes after that review. Provider retry and receipt claims require a separate current provider receipt.