Integration troubleshooting

Find a symptom below and apply its fix. Symptoms are grouped by source: Relay’s API first, then each engine. Each integration’s own page carries the depth.

Start here

relaymessenger doctor

A healthy baseline reports all of:

Node version supported.
Pairing valid, with the owner user id pinned.
Token file present with owner-only permissions.
API origin reachable.
Saved state readable.
Each adapter entrypoint resolving, and for Hermes, hermes acp --check passing.

Anything red here explains most symptoms below. Fix it before reading further.

Cross-integration failure signatures

These come from Relay’s API rather than the engine, so they apply to every integration.

Symptom	Fastest check	Fix
Every request fails with `401`	`relaymessenger doctor` pairing line	A `401` is terminal, not retryable. Run `relaymessenger pair` again
`relaymessenger pair` never completes	Did you approve the code in the Relay app?	The token poll answers `authorization_pending` until you approve, and `expired_token` once the code lapses. Pair again and approve the code
A send returns `409 idempotency_conflict`	Is the `message_id` reused across turns?	That `msg_` id is already committed by a different sender or a different body. Mint a fresh `msg_` ULID per new message, and reuse one only when retrying that exact send
The same reply posts twice	Is the retry reusing the first attempt’s `message_id`?	The client-minted `message_id` is the idempotency key. Persist it before the first attempt and send it again on retry
An event is handled twice	Are you deduplicating on `event_id`?	Both webhooks and polling redeliver at least once. Deduplicate on `event_id`; the cursor acknowledges nothing
A non-owner’s message is ignored	Owner pin in `relaymessenger doctor`	Working as intended. Only the pinned owner can drive the agent or answer approvals

Claude Code failure signatures

Symptom	Fastest check	Fix
Channel events stop arriving	Is that Claude session still open?	Channel events flow only while the session is open. Use the ACP bridge for a session-independent conversation
The plugin will not load	Did you pass `--dangerously-load-development-channels`?	Custom channels need the flag unless the org allowlists the plugin. Team and Enterprise orgs must also enable channels
An approval offers only Deny	Is the permission preview complete JSON?	The preview was truncated, so Relay withheld remote Allow. Approve at the keyboard
`install-claude` refuses to run	Configured identity in the channel `.env`	Deliberate. A different Relay identity is configured. Remove it before replacing

Full detail: Claude Code.

Codex failure signatures

Symptom	Fastest check	Fix
Codex asks you to trust a hook handler	Expected right after `install-codex`	Accept it once at the keyboard
Nothing arrives for one project	Is the root listed in `~/.relaymessenger/codex-notify.json`?	Run `relaymessenger install-codex` from that project. Opt-in is per project root
An approval offers only Deny	Could the operation be represented in full?	Relay denies rather than offering a blind Allow. Approve at the keyboard
A retried MCP send posted twice	Is `send_id` caller-stable?	`send_id` must be stable across retries so the bridge reuses the same `message_id`

Full detail: Codex.

Hermes Agent failure signatures

Symptom	Fastest check	Fix
The bridge will not start	`hermes acp --check`	Fix the Hermes installation. Relay will not start against an installation that reports itself unready
An approval was denied without you answering	Did 55 seconds pass?	Relay denies at 55 seconds to answer before Hermes’s 60-second timeout. Answer sooner, or approve at the keyboard
Behavior differs from the documented contract	Installed version in `relaymessenger doctor`	The audited reference is Hermes Agent 0.18.2. You own installation and upgrades

Full detail: Hermes Agent.

OpenClaw failure signatures

Symptom	Fastest check	Fix
Reactions or receipts do not wake the agent	Expected today	Reactions and receipts do not start agent turns in this channel
The agent cannot read an attachment	Is the part a capability URL?	Inbound media arrives as a fetchable URL, not inline. The agent must fetch it
A group conversation does nothing	Is the conversation direct?	The channel’s scope today is direct conversations only
The installer refuses to overwrite	Relay fields in `~/.openclaw/openclaw.json`	Deliberate. A different Relay identity is configured. Remove it first

Full detail: OpenClaw.

Still stuck

Reconcile state from conversation history rather than replaying delivery attempts.
Check the full status and code table in Errors.
Confirm you are inside the limits for parts, attachment size, and retention.

Next steps

The relaymessenger CLI for pairing, what Relay never receives, and the approval guarantees
Delivery model for transports, cursors, idempotency, and recovery
Errors for every status and code Relay returns
Integrations to go back to the integration list

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Integration troubleshooting

Start here

Cross-integration failure signatures

Claude Code failure signatures

Codex failure signatures

Hermes Agent failure signatures

OpenClaw failure signatures

Still stuck

Next steps

​Start here

​Cross-integration failure signatures

​Claude Code failure signatures

​Codex failure signatures

​Hermes Agent failure signatures

​OpenClaw failure signatures

​Still stuck

​Next steps

Start here

Cross-integration failure signatures

Claude Code failure signatures

Codex failure signatures

Hermes Agent failure signatures

OpenClaw failure signatures

Still stuck

Next steps