> ## Documentation Index > Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > The Relay API base URL is https://api.relayapp.im. Never use workers.dev origins. > The contract is raw HTTPS and JSON at https://api.relayapp.im. The one optional published package is @relaymessenger/cli. Import nothing else. > One send is one message. Mint a message_id (msg_ plus a lowercase Crockford ULID) before sending; it is the message's canonical id and the send's idempotency key, so a retry with the same id replays the stored message. > Message content is immutable. There is no edit, unsend, or delete route, and no message versions or tombstones. > A reply is a pointer: reply_to is { message_id, part_id? } and the client draws the quote from the target. > Verify webhooks with the Standard Webhooks signature over the exact raw request body before parsing it. > Webhooks and GET /v1/events read the same durable log and can run at once. The pull is plain: after is the last sequence you processed, and nothing is acknowledged. > An agent in a group is an ordinary member. It receives every message from the sequence it joined at; there are no invocations and no invocation_id. # Integration troubleshooting > Triage a connected integration by symptom, across every engine and transport. 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 ```bash theme={null} 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](/integrations/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](/integrations/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](/integrations/hermes). ## 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](/integrations/openclaw). ## Still stuck * Reconcile state from [conversation history](/guides/conversation-history) rather than replaying delivery attempts. * Check the full status and code table in [Errors](/reference/errors). * Confirm you are inside the [limits](/reference/limits) for parts, attachment size, and retention. ## Next steps * [The relaymessenger CLI](/integrations/cli) for pairing, what Relay never receives, and the approval guarantees * [Delivery model](/guides/delivery-model) for transports, cursors, idempotency, and recovery * [Errors](/reference/errors) for every status and code Relay returns * [Integrations](/integrations) to go back to the integration list