AMQP

The amqp channel consumes messages from an AMQP 0-9-1 broker (RabbitMQ and compatible). Each delivery can drive the agent loop, start a SOP run, or both, selected per alias by the dispatch field.

This is a SOP event source. For trigger syntax, routing-key matching, and the SOP side of the wiring, see SOP Fan-In: AMQP. This page covers the broker connection and the dispatch mode.

Configuration

The full field list, derived from the live schema. For a basic consumer you set amqp_url, exchange, and routing_keys.

amqp_url* 🔑 secret · default —

AMQP broker URL. Use amqp:// for plain or amqps:// for TLS (e.g. amqps://fedora:@rabbitmq.fedoraproject.org/%2Fpublic_pubsub).

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.amqp_url field.

zerocode

In the Config pane, set the channels.amqp.<alias>.amqp_url field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.amqp_url    # masked input, stored encrypted

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__amqp_url=

ca_cert string? · default —

Path to the CA certificate bundle for amqps:// connections.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.ca_cert field.

zerocode

In the Config pane, set the channels.amqp.<alias>.ca_cert field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.ca_cert <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__ca_cert=

client_cert 🔑 secret · default —

Path to the client certificate for broker mutual-TLS auth (Fedora Messaging requires a client cert).

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.client_cert field.

zerocode

In the Config pane, set the channels.amqp.<alias>.client_cert field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.client_cert    # masked input, stored encrypted

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__client_cert=

client_key 🔑 secret · default —

Path to the client private key matching client_cert.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.client_key field.

zerocode

In the Config pane, set the channels.amqp.<alias>.client_key field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.client_key    # masked input, stored encrypted

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__client_key=

content_template string · default ""

Template for the inbound message content. {field} placeholders are interpolated from the JSON delivery body’s top-level keys. When empty, the raw delivery body is used verbatim.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.content_template field.

zerocode

In the Config pane, set the channels.amqp.<alias>.content_template field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.content_template <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__content_template=

dispatch SopDispatch · default "agent_loop"

Where consumed deliveries are routed: drive an agent turn (agent_loop, default), dispatch to the SOP engine (sop), or both (sop_and_agent_loop). The sop and sop_and_agent_loop modes match the delivery against SOP amqp triggers by routing key.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.dispatch field.

zerocode

In the Config pane, set the channels.amqp.<alias>.dispatch field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.dispatch <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__dispatch=

durable_ack bool · default true

Acknowledgement mode. When true (default), deliveries are acked only after the message is durably handed to the agent loop, giving at-least-once semantics: a crash before hand-off redelivers the event. Set false for at-most-once (broker acks on dispatch), which silently drops in-flight events on crash and is only appropriate for non-side-effecting, drop-on-overload consumers.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.durable_ack field.

zerocode

In the Config pane, set the channels.amqp.<alias>.durable_ack field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.durable_ack <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__durable_ack=

exchange* string · default —

Exchange to bind the consumer queue to (e.g. amq.topic).

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.exchange field.

zerocode

In the Config pane, set the channels.amqp.<alias>.exchange field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.exchange <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__exchange=

excluded_tools string[] · default []

Tools excluded from this channel’s tool spec. When set, these tools are not exposed to the model when responding via this channel.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.excluded_tools field.

zerocode

In the Config pane, set the channels.amqp.<alias>.excluded_tools field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.excluded_tools <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__excluded_tools=

queue string? · default —

Queue name. Leave unset for a server-generated, transient, auto-deleted, exclusive queue. Set a stable name (UUID recommended) only when durable delivery across reconnects is required.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.queue field.

zerocode

In the Config pane, set the channels.amqp.<alias>.queue field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.queue <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__queue=

routing_keys string[] · default []

Routing keys to bind. Scope these to the topics of interest; binding # consumes the entire exchange and is almost never what you want.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.routing_keys field.

zerocode

In the Config pane, set the channels.amqp.<alias>.routing_keys field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.routing_keys <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__routing_keys=

sender_label string · default "amqp"

Value placed in ChannelMessage.sender for every delivery from this source (e.g. anitya). Lets the orchestrator’s self-loop guard and per-channel routing identify the origin.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.sender_label field.

zerocode

In the Config pane, set the channels.amqp.<alias>.sender_label field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.sender_label <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__sender_label=

thread_id_field string · default ""

Dotted path into the JSON delivery body whose value becomes the message thread_ts, correlating replies to the originating event (e.g. message.project.name). Empty disables threading.

Set it on any surface:

Gateway dashboard

Open /config/channels/amqp and set the channels.amqp.<alias>.thread_id_field field.

zerocode

In the Config pane, set the channels.amqp.<alias>.thread_id_field field.

zeroclaw config

zeroclaw config set channels.amqp.<alias>.thread_id_field <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_channels__amqp__<alias>__thread_id_field=

Full field reference: config reference.

Dispatch modes

The dispatch field decides what a delivery does:

agent_loop (default): the delivery is handed to the agent loop as a message. This preserves the original behavior; existing consumers are unaffected.
sop: the delivery is lifted into a SOP event (routing key into the event topic, body into the payload) and dispatched to the SOP engine. See SOP Fan-In: AMQP.
sop_and_agent_loop: both of the above run for each delivery.

TLS

For TLS transport, point amqp_url at an amqps:// endpoint and supply ca_cert. For mutual TLS, also set client_cert and client_key. Without these, the connection is plaintext; do not expose a plaintext consumer across an untrusted network.

Troubleshooting

Symptom	Likely cause	Fix
No messages consumed	exchange or routing keys do not match the publisher	Verify `exchange` and `routing_keys` against what the publisher emits
TLS handshake fails	`amqps://` without `ca_cert`, or a cert and key mismatch	Supply `ca_cert`; for mTLS verify `client_cert` and `client_key` pair
Deliveries arrive but no SOP starts	`dispatch` is `agent_loop`, or the SOP trigger does not match	Set `dispatch` to `sop` or `sop_and_agent_loop`; check the trigger routing key

Keyboard shortcuts

ZeroClaw Docs