Slack Multi-Bot Setup Handoff — omniclaw

Shared by @futuretrees

Updated May 23, 2026

Slack Multi-Bot Setup Handoff — omniclaw

Audience: Codex computer-use agent driving the Slack admin UI. Read top-to-bottom; this is a runbook, not a description.

Goal: Provision 5 Slack apps (one per omniclaw agent) in peyton's new Slack workspace, capture the tokens & IDs Slack generates, and hand them back to peyton via the secure channel he specifies (not in this public doc).

Context (what you need to know to make judgment calls)

  • omniclaw is a multi-agent orchestrator already connected to Discord with 5 agent identities. The Discord bots are: Clayton (PRIMARY), OCPeyton, Dex, Cody, LocalPeyton.
  • The intent is to mirror that setup in Slack: each agent gets its own Slack app + bot identity so users see distinct avatars/handles, not one generic bot relaying for everyone.
  • omniclaw's slack channel adapter uses Slack Socket Mode (via the @slack/bolt package with socketMode: true). That means every app needs:
    • a bot-level token issued by the workspace OAuth install (the kind that starts with x-o-x-b dash), AND
    • an app-level token specifically for Socket Mode (the kind that starts with x-a-p-p dash) with the connections:write scope.
    • No HTTP endpoints, no public URLs, no event-request-URLs — Socket Mode does it all via outbound WebSocket.
  • omniclaw's host-side config supports a multi-bot environment variable shape (semicolon-delimited per-agent triplets of id + bot-token + app-token). Peyton will assemble the final value himself after you hand the captured strings back. You do NOT need to write that env value.
  • You are NOT installing apps to a public directory. These are private workspace apps. Leave "Distribution" / "Public Distribution" disabled for all of them.

The 5 apps to create

For each app below, the App Name is what shows in Slack's UI, the Bot Display Name is the handle users see, and the Agent ID is the internal omniclaw identifier (must match exactly when peyton wires the config).

App Name Bot Display Name Agent ID Short Description
Clayton Clayton clayton Senior code agent — ships PRs, runs reviews
OCPeyton OCPeyton ocpeyton Peyton's personal operator agent
Dex Dex dex Devops + container agent
Cody Cody cody Codebase researcher / Q&A agent
LocalPeyton LocalPeyton local-peyton Local-machine ops agent (file system, scheduled tasks)

If avatars are easily available from the Discord setup, reuse them. If not, leave blank — peyton can upload later.

Per-app provisioning steps (repeat 5×)

Open https://api.slack.com/apps and sign in to peyton's new workspace if not already.

Step 1 — Create app from scratch

  1. Click Create New App.
  2. Choose From scratch.
  3. Enter the App Name from the table above (e.g. Clayton).
  4. Pick peyton's new workspace from the dropdown.
  5. Click Create App.

Step 2 — Enable Socket Mode + generate the app-level token

  1. In the left sidebar click Socket Mode.
  2. Toggle Enable Socket Mode to ON.
  3. A modal appears asking to generate an app-level token. Token name: socket-mode. Add scope: connections:write. Click Generate.
  4. CAPTURE the generated string (the long one shown immediately after Generate). This is one of the two tokens you need to hand back. Label it as the agent's app-level token in your handoff notes.

Step 3 — Configure bot scopes

  1. Left sidebar → OAuth & Permissions.
  2. Scroll to Bot Token Scopes. Add ALL of these (click "Add an OAuth Scope" for each):
    • app_mentions:read
    • channels:history
    • channels:read
    • chat:write
    • chat:write.public (lets the bot post in channels it hasn't been explicitly invited to — convenient for omniclaw's auto-discovery flow)
    • files:read
    • files:write
    • groups:history
    • groups:read
    • im:history
    • im:read
    • im:write
    • mpim:history
    • mpim:read
    • mpim:write
    • reactions:read
    • reactions:write
    • users:read

Step 4 — Subscribe to bot events

  1. Left sidebar → Event Subscriptions.
  2. Toggle Enable Events to ON. (Event Request URL field can be ignored — Socket Mode bypasses it.)
  3. Expand Subscribe to bot events and add:
    • app_mention
    • message.channels
    • message.groups
    • message.im
    • message.mpim
    • reaction_added
  4. Save Changes at the bottom.

Step 5 — Set app display info (matters because users see this)

  1. Left sidebar → Basic Information.
  2. Scroll to Display Information.
  3. Set App name from the table.
  4. Set Short description from the table.
  5. (Optional) Upload an app icon if available.
  6. Save Changes.

Step 6 — Install to workspace

  1. Left sidebar → Install App.
  2. Click Install to .
  3. Slack shows a permission confirmation page. Click Allow.
  4. On the resulting page you'll see the Bot User OAuth Token (the long string starting with the bot-token prefix). CAPTURE this string as the agent's bot-level token in your handoff notes.

Step 7 — Capture identifying metadata

From Basic Information → App Credentials section, copy:

  • App ID (looks like A0xxxxxxxxx).
  • The bot's User ID (looks like U0xxxxxxxxx) — shown on the OAuth screen after install, or under Install App after install completes.

Stop conditions — DO NOT proceed past these without flagging peyton

  • Workspace ambiguity: if more than one workspace is available in the dropdown and you're not sure which one is "the new slack," stop and ask.
  • Token visible only once: Slack shows generated tokens with one-time copy buttons. If you click away without copying, the string is unrecoverable — you'll have to regenerate. Don't proceed if you missed a copy.
  • Rate limits / 2FA challenges: if Slack interrupts with a verification challenge that can't be auto-solved, stop and surface it.
  • App count limit: Slack tiers limit the number of apps per workspace. If the 4th or 5th app fails to create with a quota error, stop and report which agents are missing.

Handoff format (what to send peyton when done)

Hand back a structured report — NOT in this public doc, but via whichever secure channel peyton points you to. For each agent, return these four items, clearly labeled with the agent id:

  • App ID (A0… shape)
  • Bot User ID (U0… shape)
  • Bot-level token (the long string captured in Step 6)
  • App-level token (the long string captured in Step 2)

Per-agent checklist (use this shape in the handoff so peyton can paste-and-assemble quickly — leave placeholders unfilled if a step failed, and note which step failed):

Agent App ID Bot User ID Bot Token captured? App Token captured?
clayton yes / no yes / no
ocpeyton yes / no yes / no
dex yes / no yes / no
cody yes / no yes / no
local-peyton yes / no yes / no

Plus the four token strings per agent in a sealed-channel message. Do not put the actual token strings in this markdown doc or anywhere public.

Invite phase (after app creation — same session OK)

For each agent, decide which channels they should listen in. As a starting baseline, invite all 5 bots to one shared test channel (e.g. #omniclaw-test — create if it doesn't exist) so peyton can verify routing before fanning out.

To invite: open the channel in Slack web/desktop → type /invite @<bot_name> and confirm. Or use channel settings → Integrations → Apps → Add.

Record which bot is in which channel:

#omniclaw-test  -> clayton, ocpeyton, dex, cody, local-peyton
#<other-chan>   -> <bots>
...

What happens after this doc is finished

Peyton (or the omniclaw side of the work) will:

  1. Take the captured tokens and write them into omniclaw's local environment file in the multi-bot shape that the existing config parser expects.
  2. Verify omniclaw's src/channels/slack.ts send path respects the per-bot identity (read-only check — no changes expected since the multi-bot env structure already exists in src/config.ts).
  3. Insert channel_subscriptions rows in store/messages.db mapping each invited Slack channel × agent, with channel_folder and category_folder matching the 4-layer (server / category / channel / agent) layout already used for Discord.
  4. Restart omniclaw (just restart or launchctl kickstart -k gui/$(id -u)/com.omniclaw).
  5. Send a test @Clayton hello in #omniclaw-test, verify the right bot replies in Discord-style format.

Codex does not need to do any of that — just provision the 5 apps, capture the secrets, and hand them off.

Reference: the 4-layer context (for when peyton decides channel layout)

  • Server = a workspace-level scope (in Slack: the workspace itself; in Discord: the guild).
  • Category = a grouping of related channels (in Slack: no native primitive, so we use channel-name prefixes — e.g. aura-omniclaw-spec, aura-omniclaw-general → category aura/omniclaw).
  • Channel = the actual Slack channel (C0xxxxxxx ID, #human-name).
  • Agent = the omniclaw agent identity routed by channel_subscriptions.agent_id.

When deciding which bots go in which channels, group by category first — e.g. all aura-omniclaw-* channels probably want the same set of agents.

Doc generated 2026-05-23. PR history this work depends on: omniaura/omniclaw#747, #750, #751, #752, #753 (merged); #757 (open, reconnect resilience — recommend merge before going live with new bots).