Slack

Connect IronClaw to a Slack workspace so your agent can read and reply to messages in channels and DMs.

Prerequisites

A Slack workspace where you can install apps
An IronClaw instance reachable from Slack over HTTPS

Setup

Create a Slack app

Create an app at api.slack.com/apps. The fastest route is From an app manifest — paste the manifest below, which sets the scopes, events, the /ironclaw slash command, and redirect URL in one step. Replace example.com with your own host first.If you build the app from scratch instead, configure OAuth & Permissions, Event Subscriptions, Slash Commands, and the redirect URL to match that manifest.Once created, install the app to your workspace and copy the bot token from OAuth & Permissions, and the signing secret from Basic Information. IronClaw uses the signing secret to verify that incoming requests really came from Slack.

Start IronClaw

ironclaw serve

Enter the deployment configuration (operator, once per instance)

In the web interface, open Admin → Configuration and fill in the Slack deployment configuration card — the bot token, signing secret, workspace (team) ID, app ID, and the other fields the card lists. They are written to the encrypted secret store.

The agent can’t do this operator step for you — registering the app credentials stays in the web interface. Once it’s done, though, asking the agent to “connect Slack” does work for the personal half: it installs and activates the extension, opens the in-chat connection panel if your personal OAuth is missing, and confirms when your account is already connected.

Point Slack at your instance

Back in your Slack app, confirm Event Subscriptions points at your instance:

https://your-host/webhooks/extensions/slack/events

Slack sends a verification challenge to that URL, so IronClaw must already be running and reachable when you save it. Reinstall the app if Slack asks you to.Also register the /ironclaw slash command under Slash Commands, pointed at the identical Request URL — Slack allows a slash command’s endpoint to be any URL, so one signed address answers both surfaces. Registering a slash command adds the commands bot scope, which also needs a reinstall.

Talk to it

Invite the bot to a channel and mention it, or send it a direct message.

URLs Slack Needs

Both are served by ironclaw serve, so they use whatever host and port your instance is reachable on. Replace your-host and use HTTPS — Slack will not deliver to a plain-HTTP or self-signed endpoint.

Slack setting	URL
Event Subscriptions → Request URL	`https://your-host/webhooks/extensions/slack/events`
Slash Commands → Request URL	`https://your-host/webhooks/extensions/slack/events`
OAuth & Permissions → Redirect URL	`https://your-host/api/reborn/product-auth/oauth/slack/callback`

Event Subscriptions and the /ironclaw slash command point at the identical Request URL — one signed endpoint answers both surfaces, so there is no second address to stand up.

The redirect URL is used for per-user (“personal”) Slack authorization. IronClaw derives it from the instance’s own public base URL, so there is nothing to set on this side — just register the value above in the Slack app.

The redirect URL must match exactly on both sides, including scheme, host, port, and path. Slack rejects the authorization with a redirect-URI mismatch if it differs by even a trailing slash. The path is /api/reborn/product-auth/oauth/slack/callback — a shortened form like /oauth/slack/callback is not served and will 404.

For a local instance the values are http://127.0.0.1:3000/..., but Slack cannot reach loopback, so events only work once the instance is reachable from the internet.

App Manifest

Create the app with From an app manifest and paste this, replacing example.com with your host. It sets the scopes, bot events, the /ironclaw slash command, and redirect URL that the steps above describe.

{
  "display_information": {
    "name": "IronClaw"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "IronClaw",
      "always_online": true
    },
    "slash_commands": [
      {
        "command": "/ironclaw",
        "url": "https://example.com/webhooks/extensions/slack/events",
        "description": "Run IronClaw commands",
        "usage_hint": "status | model <name> | help",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "redirect_urls": [
      "https://example.com/api/reborn/product-auth/oauth/slack/callback"
    ],
    "scopes": {
      "user": [
        "search:read",
        "channels:history",
        "groups:history",
        "im:history",
        "mpim:history",
        "channels:read",
        "groups:read",
        "im:read",
        "mpim:read",
        "users:read",
        "chat:write"
      ],
      "bot": [
        "channels:history",
        "app_mentions:read",
        "chat:write",
        "im:history",
        "im:write",
        "files:read",
        "files:write",
        "groups:history",
        "mpim:history",
        "commands"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://example.com/webhooks/extensions/slack/events",
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim"
      ]
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}

This is a starting point, not a minimum. The user scopes exist for per-user authorization — searching and posting as the person rather than as the bot. If you only want the bot to participate in channels, you can drop the user block and the redirect URL with it.

files:read lets the bot resolve and download inbound file shares. files:write lets it return explicitly attached workspace files through Slack’s external upload flow. IronClaw never uses the retired files.upload method. Slack validates the request URL when you save the manifest, so start IronClaw before creating the app.

Configuration

Slack has no settings in the configuration file. The app id, the bot token, the signing secret, and channel routing are all configured in the web interface, on the Slack card under Extensions — the tokens go straight into the encrypted secret store. There is no key that turns Slack on. The webhook route is always mounted, and it starts accepting events once the Slack extension is installed and its signing secret is registered. Until then it answers 503. There is no IRONCLAW_REBORN_SLACK_ENABLED environment variable either — the gate it fed was removed in #6116.

An older configuration file may still carry a [slack] section. Nothing reads it. A leftover setup field — api_app_id, team_id, bot_token_env, signing_secret_env, channel_routes, and the rest — now stops startup with a pointer to the web interface instead of being quietly ignored, so delete the section. [slack].enabled is accepted but inert, so an older install keeps booting.

Troubleshooting

Slack can't verify the request URL

IronClaw has to be running and publicly reachable over HTTPS before you save the URL. Confirm the instance answers from outside your network, and that you used the exact /webhooks/extensions/slack/events path.

Slack rejects authorization with a redirect-URI mismatch

The redirect URL registered in the Slack app must match the one IronClaw sends character for character. Check the scheme, the host, the port, and that the path is the full /api/reborn/product-auth/oauth/slack/callback.

The bot doesn't respond in a channel

Invite the bot to that channel, and make sure you subscribed to the matching message event. A bot only sees conversations it belongs to.

Requests are rejected

A wrong or missing signing secret makes IronClaw reject every incoming request. Re-enter it through the setup flow, then restart the server.

I can't find where to configure Slack

The instance-wide credentials live under Admin → Configuration, on the Slack deployment configuration card. The Extensions page handles the personal half — installing the extension and connecting your own Slack account.

Using IronClaw

Capabilities

Channels

IronHub

API

Extensions (Tools)

Tutorials

Prerequisites

Setup

URLs Slack Needs

App Manifest

Configuration

Troubleshooting

​Prerequisites

​Setup

​URLs Slack Needs

​App Manifest

​Configuration

​Troubleshooting

Prerequisites

Setup

URLs Slack Needs

App Manifest

Configuration

Troubleshooting