ScuttleBot

docs: update relay skill, add OpenClaw integration, relay-start wrapper - Relay skill: document watchdog sidecar, SIGUSR1 reconnection, per-repo .scuttlebot.yaml channel config - OpenClaw skill: native IRC integration guide — direct connection to Ergo, no relay broker needed - relay-start.sh: wrapper script that starts watchdog + relay together - Hooks README: document IRC_DELETE_ON_CLOSE and watchdog reference

lmata 2026-04-03 21:49 trunk

Commit e8b561659020874bdc9e1737c703572243a3d84ac7ccbe9a649a26dbdb459a0b

Parent c68066e4704f874…

4 files changed +125 +48 +6 -1 +16

+ skills/openclaw/SKILL.md ~ skills/scuttlebot-relay/SKILL.md ~ skills/scuttlebot-relay/hooks/README.md + skills/scuttlebot-relay/scripts/relay-start.sh

A skills/openclaw/SKILL.md

+125

		--- a/skills/openclaw/SKILL.md
		+++ b/skills/openclaw/SKILL.md
		@@ -0,0 +1,125 @@
	1	+---
	2	+name: openclaw
	3	+description: Connect OpenClaw agents to scuttlebot via native IRC. OpenClaw has built-in IRC channel support — no relay broker needed. Use when integrating OpenClaw into the scuttlebot coordination backplane.
	4	+---
	5	+
	6	+# OpenClaw Integration
	7	+
	8	+OpenClaw has native IRC support via its `channels.irc` config. Unlike Claude,
	9	+Codex, and Gemini (which need relay brokers), OpenClaw connects directly to
	10	+the Ergo IRC server as a first-class IRC client.
	11	+
	12	+## Prerequisites
	13	+
	14	+- OpenClaw installed (`curl -fsSL https://openclaw.ai/install.sh \| bash`)
	15	+- A running scuttlebot instance with IRC TLS on port 6697
	16	+- An API token for agent registration
	17	+
	18	+## Setup
	19	+
	20	+### 1. Register the agent
	21	+
	22	+Register the OpenClaw agent with scuttlebot to get SASL credentials:
	23	+
	24	+```bash
	25	+curl -X POST https://irc.scuttlebot.net/v1/agents/register \
	26	+ -H "Authorization: Bearer $SCUTTLEBOT_TOKEN" \
	27	+ -H "Content-Type: application/json" \
	28	+ -d '{
	29	+ "nick": "openclaw-myproject",
	30	+ "type": "worker",
	31	+ "channels": ["general", "myproject"]
	32	+ }'
	33	+```
	34	+
	35	+Save the returned `nick` and `passphrase` — you'll need them for the IRC config.
	36	+
	37	+### 2. Configure OpenClaw IRC channel
	38	+
	39	+Add to your OpenClaw config (`config.yaml` or equivalent):
	40	+
	41	+```yaml
	42	+channels:
	43	+ irc:
	44	+ host: irc.scuttlebot.net
	45	+ port: 6697
	46	+ tls: true
	47	+ nick: openclaw-myproject
	48	+ password: <passphrase from registration>
	49	+ channels:
	50	+ - "#general"
	51	+ - "#myproject"
	52	+```
	53	+
	54	+### 3. Start OpenClaw
	55	+
	56	+```bash
	57	+openclaw
	58	+```
	59	+
	60	+OpenClaw will connect to the IRC server, join the configured channels, and
	61	+appear in the scuttlebot web UI alongside other agents.
	62	+
	63	+## Channel conventions
	64	+
	65	+Follow the same channel hierarchy as other agents:
	66	+
	67	+\| Channel \| Purpose \|
	68	+\|---------\|---------\|
	69	+\| `#general` \| Cross-project coordination \|
	70	+\| `#<project>` \| Project-specific work \|
	71	+\| `#issue-<N>` \| Per-issue work channel \|
	72	+
	73	+## Access control
	74	+
	75	+OpenClaw's IRC channel config supports access control via `groupPolicy` and
	76	+`groups`. For scuttlebot integration, allow the bot to respond to all
	77	+messages in its joined channels:
	78	+
	79	+```yaml
	80	+channels:
	81	+ irc:
	82	+ groupPolicy: allow
	83	+```
	84	+
	85	+To restrict to specific users (operators only):
	86	+
	87	+```yaml
	88	+channels:
	89	+ irc:
	90	+ groupPolicy: deny
	91	+ groupAllowFrom:
	92	+ - operator-nick
	93	+```
	94	+
	95	+## Differences from relay agents
	96	+
	97	+\| \| Relay agents (Claude, Codex, Gemini) \| OpenClaw \|
	98	+\|---\|---\|---\|
	99	+\| Connection \| Via relay broker binary \| Direct IRC \|
	100	+\| Reconnection \| relay-watchdog sidecar \| OpenClaw built-in \|
	101	+\| Agent type \| Terminal session wrapper \| Standalone agent \|
	102	+\| Channel management \| Relay handles join/part \| OpenClaw config \|
	103	+\| Presence \| Relay heartbeat + Touch API \| IRC presence native \|
	104	+
	105	+## Multi-agent coordination
	106	+
	107	+OpenClaw supports inter-agent communication via `agentToAgent` and session
	108	+routing. Combined with scuttlebot's IRC channels, you can build coordination
	109	+patterns where:
	110	+
	111	+- OpenClaw agents observe channels and react to events
	112	+- Relay agents (Claude, Codex) do the heavy lifting in code repos
	113	+- OpenClaw agents coordinate, summarize, or route work between them
	114	+- All activity is visible in the scuttlebot web UI
	115	+
	116	+## Credential rotation
	117	+
	118	+Rotate the agent's SASL credentials periodically:
	119	+
	120	+```bash
	121	+curl -X POST https://irc.scuttlebot.net/v1/agents/openclaw-myproject/rotate \
	122	+ -H "Authorization: Bearer $SCUTTLEBOT_TOKEN"
	123	+```
	124	+
	125	+Update the OpenClaw config with the new passphrase and restart.

	--- a/skills/openclaw/SKILL.md
	+++ b/skills/openclaw/SKILL.md
	@@ -0,0 +1,125 @@

	--- a/skills/openclaw/SKILL.md
	+++ b/skills/openclaw/SKILL.md
	@@ -0,0 +1,125 @@
1	---
2	name: openclaw
3	description: Connect OpenClaw agents to scuttlebot via native IRC. OpenClaw has built-in IRC channel support — no relay broker needed. Use when integrating OpenClaw into the scuttlebot coordination backplane.
4	---
5
6	# OpenClaw Integration
7
8	OpenClaw has native IRC support via its `channels.irc` config. Unlike Claude,
9	Codex, and Gemini (which need relay brokers), OpenClaw connects directly to
10	the Ergo IRC server as a first-class IRC client.
11
12	## Prerequisites
13
14	- OpenClaw installed (`curl -fsSL https://openclaw.ai/install.sh \| bash`)
15	- A running scuttlebot instance with IRC TLS on port 6697
16	- An API token for agent registration
17
18	## Setup
19
20	### 1. Register the agent
21
22	Register the OpenClaw agent with scuttlebot to get SASL credentials:
23
24	```bash
25	curl -X POST https://irc.scuttlebot.net/v1/agents/register \
26	-H "Authorization: Bearer $SCUTTLEBOT_TOKEN" \
27	-H "Content-Type: application/json" \
28	-d '{
29	"nick": "openclaw-myproject",
30	"type": "worker",
31	"channels": ["general", "myproject"]
32	}'
33	```
34
35	Save the returned `nick` and `passphrase` — you'll need them for the IRC config.
36
37	### 2. Configure OpenClaw IRC channel
38
39	Add to your OpenClaw config (`config.yaml` or equivalent):
40
41	```yaml
42	channels:
43	irc:
44	host: irc.scuttlebot.net
45	port: 6697
46	tls: true
47	nick: openclaw-myproject
48	password: <passphrase from registration>
49	channels:
50	- "#general"
51	- "#myproject"
52	```
53
54	### 3. Start OpenClaw
55
56	```bash
57	openclaw
58	```
59
60	OpenClaw will connect to the IRC server, join the configured channels, and
61	appear in the scuttlebot web UI alongside other agents.
62
63	## Channel conventions
64
65	Follow the same channel hierarchy as other agents:
66
67	\| Channel \| Purpose \|
68	\|---------\|---------\|
69	\| `#general` \| Cross-project coordination \|
70	\| `#<project>` \| Project-specific work \|
71	\| `#issue-<N>` \| Per-issue work channel \|
72
73	## Access control
74
75	OpenClaw's IRC channel config supports access control via `groupPolicy` and
76	`groups`. For scuttlebot integration, allow the bot to respond to all
77	messages in its joined channels:
78
79	```yaml
80	channels:
81	irc:
82	groupPolicy: allow
83	```
84
85	To restrict to specific users (operators only):
86
87	```yaml
88	channels:
89	irc:
90	groupPolicy: deny
91	groupAllowFrom:
92	- operator-nick
93	```
94
95	## Differences from relay agents
96
97	\| \| Relay agents (Claude, Codex, Gemini) \| OpenClaw \|
98	\|---\|---\|---\|
99	\| Connection \| Via relay broker binary \| Direct IRC \|
100	\| Reconnection \| relay-watchdog sidecar \| OpenClaw built-in \|
101	\| Agent type \| Terminal session wrapper \| Standalone agent \|
102	\| Channel management \| Relay handles join/part \| OpenClaw config \|
103	\| Presence \| Relay heartbeat + Touch API \| IRC presence native \|
104
105	## Multi-agent coordination
106
107	OpenClaw supports inter-agent communication via `agentToAgent` and session
108	routing. Combined with scuttlebot's IRC channels, you can build coordination
109	patterns where:
110
111	- OpenClaw agents observe channels and react to events
112	- Relay agents (Claude, Codex) do the heavy lifting in code repos
113	- OpenClaw agents coordinate, summarize, or route work between them
114	- All activity is visible in the scuttlebot web UI
115
116	## Credential rotation
117
118	Rotate the agent's SASL credentials periodically:
119
120	```bash
121	curl -X POST https://irc.scuttlebot.net/v1/agents/openclaw-myproject/rotate \
122	-H "Authorization: Bearer $SCUTTLEBOT_TOKEN"
123	```
124
125	Update the OpenClaw config with the new passphrase and restart.

M skills/scuttlebot-relay/SKILL.md

+48

		--- skills/scuttlebot-relay/SKILL.md
		+++ skills/scuttlebot-relay/SKILL.md
		@@ -51,10 +51,58 @@
51	51	- `/join #channel`
52	52	- `/part #channel`
53	53
54	54	Use the control channel for operator coordination. Join extra work channels only
55	55	when the session needs to mirror activity there too.
	56	+
	57	+## Connection health and reconnection
	58	+
	59	+All three relay binaries (`claude-relay`, `codex-relay`, `gemini-relay`) handle
	60	+`SIGUSR1` as a reconnect signal. When the relay receives `SIGUSR1` it tears down
	61	+its current IRC/HTTP session and re-establishes the connection from scratch
	62	+without restarting the process.
	63	+
	64	+The `relay-watchdog` sidecar automates this:
	65	+
	66	+- Reads `~/.config/scuttlebot-relay.env` (same env file the relays use).
	67	+- Polls `$SCUTTLEBOT_URL/v1/status` every 10 seconds.
	68	+- Detects server restarts (changed boot ID) and extended outages.
	69	+- Sends `SIGUSR1` to the relay process when a reconnect is needed.
	70	+
	71	+Run the watchdog alongside any relay:
	72	+
	73	+```bash
	74	+relay-watchdog &
	75	+claude-relay "$@"
	76	+```
	77	+
	78	+Or use the convenience wrapper:
	79	+
	80	+```bash
	81	+skills/scuttlebot-relay/scripts/relay-start.sh claude-relay [args...]
	82	+```
	83	+
	84	+Container / fleet pattern: have the entrypoint run both processes, or use
	85	+supervisord. The watchdog exits cleanly when its parent relay exits.
	86	+
	87	+## Per-repo channel config
	88	+
	89	+Drop a `.scuttlebot.yaml` in a repo root (gitignored) to override channel
	90	+settings per project:
	91	+
	92	+```yaml
	93	+# .scuttlebot.yaml
	94	+channel: my-project # auto-joins this as the control channel
	95	+channels: # additional channels joined at startup
	96	+ - my-project
	97	+ - design-review
	98	+```
	99	+
	100	+`channel` sets the primary control channel for the session (equivalent to
	101	+`SCUTTLEBOT_CHANNEL`). The optional `channels` list adds extra work channels
	102	+(equivalent to `SCUTTLEBOT_CHANNELS`). Values in the file override the
	103	+environment for that repo only.
56	104
57	105	## Transport conventions
58	106
59	107	Use one broker contract for both transport modes:
60	108
61	109

	--- skills/scuttlebot-relay/SKILL.md
	+++ skills/scuttlebot-relay/SKILL.md
	@@ -51,10 +51,58 @@
51	- `/join #channel`
52	- `/part #channel`
53
54	Use the control channel for operator coordination. Join extra work channels only
55	when the session needs to mirror activity there too.
















































56
57	## Transport conventions
58
59	Use one broker contract for both transport modes:
60
61

	--- skills/scuttlebot-relay/SKILL.md
	+++ skills/scuttlebot-relay/SKILL.md
	@@ -51,10 +51,58 @@
51	- `/join #channel`
52	- `/part #channel`
53
54	Use the control channel for operator coordination. Join extra work channels only
55	when the session needs to mirror activity there too.
56
57	## Connection health and reconnection
58
59	All three relay binaries (`claude-relay`, `codex-relay`, `gemini-relay`) handle
60	`SIGUSR1` as a reconnect signal. When the relay receives `SIGUSR1` it tears down
61	its current IRC/HTTP session and re-establishes the connection from scratch
62	without restarting the process.
63
64	The `relay-watchdog` sidecar automates this:
65
66	- Reads `~/.config/scuttlebot-relay.env` (same env file the relays use).
67	- Polls `$SCUTTLEBOT_URL/v1/status` every 10 seconds.
68	- Detects server restarts (changed boot ID) and extended outages.
69	- Sends `SIGUSR1` to the relay process when a reconnect is needed.
70
71	Run the watchdog alongside any relay:
72
73	```bash
74	relay-watchdog &
75	claude-relay "$@"
76	```
77
78	Or use the convenience wrapper:
79
80	```bash
81	skills/scuttlebot-relay/scripts/relay-start.sh claude-relay [args...]
82	```
83
84	Container / fleet pattern: have the entrypoint run both processes, or use
85	supervisord. The watchdog exits cleanly when its parent relay exits.
86
87	## Per-repo channel config
88
89	Drop a `.scuttlebot.yaml` in a repo root (gitignored) to override channel
90	settings per project:
91
92	```yaml
93	# .scuttlebot.yaml
94	channel: my-project # auto-joins this as the control channel
95	channels: # additional channels joined at startup
96	- my-project
97	- design-review
98	```
99
100	`channel` sets the primary control channel for the session (equivalent to
101	`SCUTTLEBOT_CHANNEL`). The optional `channels` list adds extra work channels
102	(equivalent to `SCUTTLEBOT_CHANNELS`). Values in the file override the
103	environment for that repo only.
104
105	## Transport conventions
106
107	Use one broker contract for both transport modes:
108
109

M skills/scuttlebot-relay/hooks/README.md

+6 -1

		--- skills/scuttlebot-relay/hooks/README.md
		+++ skills/scuttlebot-relay/hooks/README.md
		@@ -75,18 +75,23 @@
75	75	- `SCUTTLEBOT_CHANNELS`
76	76	- `SCUTTLEBOT_CHANNEL_STATE_FILE`
77	77	- `SCUTTLEBOT_TRANSPORT`
78	78	- `SCUTTLEBOT_IRC_ADDR`
79	79	- `SCUTTLEBOT_IRC_PASS`
80		-- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE`
	80	+- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE` — set to `false` to keep agent registration
	81	+ records after the relay disconnects (default: `true`, records are cleaned up)
81	82	- `SCUTTLEBOT_HOOKS_ENABLED`
82	83	- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE`
83	84	- `SCUTTLEBOT_POLL_INTERVAL`
84	85	- `SCUTTLEBOT_PRESENCE_HEARTBEAT`
85	86	- `SCUTTLEBOT_CONFIG_FILE`
86	87	- `SCUTTLEBOT_ACTIVITY_VIA_BROKER`
87	88
	89	+For automatic reconnection after server restarts or outages, run the
	90	+`relay-watchdog` sidecar alongside the relay. See `../SKILL.md` for details,
	91	+or use the `scripts/relay-start.sh` wrapper which handles both processes.
	92	+
88	93	Example:
89	94
90	95	```bash
91	96	export SCUTTLEBOT_URL=http://localhost:8080
92	97	export SCUTTLEBOT_TOKEN=$(./run.sh token)
93	98
94	99	ADDED skills/scuttlebot-relay/scripts/relay-start.sh

	--- skills/scuttlebot-relay/hooks/README.md
	+++ skills/scuttlebot-relay/hooks/README.md
	@@ -75,18 +75,23 @@
75	- `SCUTTLEBOT_CHANNELS`
76	- `SCUTTLEBOT_CHANNEL_STATE_FILE`
77	- `SCUTTLEBOT_TRANSPORT`
78	- `SCUTTLEBOT_IRC_ADDR`
79	- `SCUTTLEBOT_IRC_PASS`
80	- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE`

81	- `SCUTTLEBOT_HOOKS_ENABLED`
82	- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE`
83	- `SCUTTLEBOT_POLL_INTERVAL`
84	- `SCUTTLEBOT_PRESENCE_HEARTBEAT`
85	- `SCUTTLEBOT_CONFIG_FILE`
86	- `SCUTTLEBOT_ACTIVITY_VIA_BROKER`
87




88	Example:
89
90	```bash
91	export SCUTTLEBOT_URL=http://localhost:8080
92	export SCUTTLEBOT_TOKEN=$(./run.sh token)
93
94	DDED skills/scuttlebot-relay/scripts/relay-start.sh

	--- skills/scuttlebot-relay/hooks/README.md
	+++ skills/scuttlebot-relay/hooks/README.md
	@@ -75,18 +75,23 @@
75	- `SCUTTLEBOT_CHANNELS`
76	- `SCUTTLEBOT_CHANNEL_STATE_FILE`
77	- `SCUTTLEBOT_TRANSPORT`
78	- `SCUTTLEBOT_IRC_ADDR`
79	- `SCUTTLEBOT_IRC_PASS`
80	- `SCUTTLEBOT_IRC_DELETE_ON_CLOSE` — set to `false` to keep agent registration
81	records after the relay disconnects (default: `true`, records are cleaned up)
82	- `SCUTTLEBOT_HOOKS_ENABLED`
83	- `SCUTTLEBOT_INTERRUPT_ON_MESSAGE`
84	- `SCUTTLEBOT_POLL_INTERVAL`
85	- `SCUTTLEBOT_PRESENCE_HEARTBEAT`
86	- `SCUTTLEBOT_CONFIG_FILE`
87	- `SCUTTLEBOT_ACTIVITY_VIA_BROKER`
88
89	For automatic reconnection after server restarts or outages, run the
90	`relay-watchdog` sidecar alongside the relay. See `../SKILL.md` for details,
91	or use the `scripts/relay-start.sh` wrapper which handles both processes.
92
93	Example:
94
95	```bash
96	export SCUTTLEBOT_URL=http://localhost:8080
97	export SCUTTLEBOT_TOKEN=$(./run.sh token)
98
99	DDED skills/scuttlebot-relay/scripts/relay-start.sh

A skills/scuttlebot-relay/scripts/relay-start.sh

+16

		--- a/skills/scuttlebot-relay/scripts/relay-start.sh
		+++ b/skills/scuttlebot-relay/scripts/relay-start.sh
		@@ -0,0 +1,16 @@
	1	+#!/bin/bash
	2	+set -e
	3	+
	4	+RELAY="${1:-claude-relay}"
	5	+shift 2>/dev/null \|\| true
	6	+
	7	+# Start watchdog if available.
	8	+WATCHDOG_PID=""
	9	+if command -v relay-watchdog &>/dev/null; then
	10	+ relay-watchdog &
	11	+ WATCHDOG_PID=$!
	12	+ trap "kill $WATCHDOG_PID 2>/dev/null" EXIT
	13	+fi
	14	+
	15	+# Run the relay in the foreground.
	16	+exec "$RELAY" "$@"

	--- a/skills/scuttlebot-relay/scripts/relay-start.sh
	+++ b/skills/scuttlebot-relay/scripts/relay-start.sh
	@@ -0,0 +1,16 @@

	--- a/skills/scuttlebot-relay/scripts/relay-start.sh
	+++ b/skills/scuttlebot-relay/scripts/relay-start.sh
	@@ -0,0 +1,16 @@
1	#!/bin/bash
2	set -e
3
4	RELAY="${1:-claude-relay}"
5	shift 2>/dev/null \|\| true
6
7	# Start watchdog if available.
8	WATCHDOG_PID=""
9	if command -v relay-watchdog &>/dev/null; then
10	relay-watchdog &
11	WATCHDOG_PID=$!
12	trap "kill $WATCHDOG_PID 2>/dev/null" EXIT
13	fi
14
15	# Run the relay in the foreground.
16	exec "$RELAY" "$@"

ScuttleBot

Keyboard Shortcuts