Slack

Configure Slack for OpenHands Enterprise.

This guide explains how to connect Slack to an OpenHands Enterprise installation. The integration lets users mention @OpenHands in Slack to start or continue OpenHands conversations.

This page is for self-hosted OpenHands Enterprise. If you use OpenHands Cloud, see Slack Integration.

Prerequisites

• An OpenHands Enterprise installation reachable at https://app.<your-base-domain>.
• Public inbound HTTPS access to https://app.<your-base-domain>/slack/*. Slack must be able to reach these routes to deliver events and interactive form submissions.
• A trusted TLS certificate for app.<your-base-domain>.
• Slack workspace administrator access to create and install a Slack app.
• Access to the OpenHands Enterprise Admin Console, or Helm values for a standalone Kubernetes installation.

Slack Socket Mode is not supported. Fully air-gapped installs cannot use the Slack integration today.

Create a Slack App

OpenHands Enterprise needs its own Slack app so Slack events are sent to your OpenHands domain.

Option A: Create the App from a Manifest

In Slack, open https://api.slack.com/apps.

1. Click Create New App.
2. Select From an app manifest.
3. Choose the Slack workspace where users will invoke OpenHands.
4. Paste the manifest below.
5. Replace every instance of <your-base-domain> with your OpenHands Enterprise base domain. For example, if users sign in at https://app.openhands.example.com, use openhands.example.com.
6. Create the app.

display_information:
  name: OpenHands
features:
  bot_user:
    display_name: OpenHands
    always_online: false
oauth_config:
  redirect_urls:
    - https://app.<your-base-domain>/slack/install-callback
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - users:read
      - channels:history
      - groups:history
      - mpim:history
      - im:history
settings:
  event_subscriptions:
    request_url: https://app.<your-base-domain>/slack/on-event
    bot_events:
      - app_mention
  interactivity:
    is_enabled: true
    request_url: https://app.<your-base-domain>/slack/on-form-interaction
    message_menu_options_url: https://app.<your-base-domain>/slack/on-options-load
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

After the app is created, open Basic Information and copy these values:

• Client ID
• Client Secret
• Signing Secret

You will paste these values into OpenHands Enterprise.

Option B: Create the App with the Helper Script

The OpenHands-Cloud repository includes a helper script that creates the same Slack app through Slack’s manifest API. Use this option if you prefer to create the app from the command line.

First, generate a Slack app configuration token:

1. Open https://api.slack.com/apps.
2. In Your App Configuration Tokens, click Generate Token.
3. Select your workspace.
4. Copy the access token. It starts with xoxe.xoxp-.

Then run the helper:

git clone https://github.com/OpenHands/OpenHands-Cloud.git
cd OpenHands-Cloud

export SLACK_CONFIG_TOKEN=xoxe.xoxp-...
./scripts/create_slack_app/create_slack_app.py \
  --base-domain openhands.example.com \
  --app-name "OpenHands"

The helper currently uses uv. If you do not want to install uv, use the manifest option above.

The helper prints the Client ID, Client Secret, and Signing Secret. Store them securely.

Configure OpenHands Enterprise

Pick the deployment type that matches your installation.

Replicated

Open the Replicated Admin Console for your OpenHands Enterprise installation.

1. Go to the application configuration page.
2. Open Enable Slack.
3. Enable Slack Integration.
4. Enter the Slack Client ID.
5. Enter the Slack Client Secret.
6. Enter the Slack Signing Secret.
7. Save and deploy the updated configuration.

Replicated creates a Kubernetes Secret named slack-auth, enables the Slack integration routes, and restarts the OpenHands integrations service with the Slack credentials.

Standalone Helm

Configure the openhands chart with the Slack client ID and Slack resolver flag:

slack:
  enabled: true
  clientId: "<slack-client-id>"

env:
  ENABLE_V1_SLACK_RESOLVER: "true"

Configure the openhands-secrets chart with the Slack secrets:

config:
  slack_client_id: "<slack-client-id>"
  slack_client_secret: "<slack-client-secret>"
  slack_signing_secret: "<slack-signing-secret>"

Then redeploy both charts:

helm upgrade --install openhands-secrets ./charts/openhands-secrets \
  -f values-secrets.yaml \
  -n openhands

helm upgrade --install openhands ./charts/openhands \
  -f values.yaml \
  -n openhands

If you manage Kubernetes secrets outside the openhands-secrets chart, create a Secret named slack-auth with client-id, client-secret, and signing-secret keys.

After redeploying, confirm the integrations service has Slack enabled:

kubectl -n openhands set env deployment/openhands-integrations --list \
  | grep '^SLACK_'

You should see SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_SIGNING_SECRET, and SLACK_WEBHOOKS_ENABLED=true.

Install the Slack App

After OpenHands Enterprise is configured and redeployed, install the Slack app into your workspace.

Open this URL in a browser:

https://app.<your-base-domain>/slack/install

Approve the Slack permissions. The flow redirects through Slack and then through OpenHands sign-in. When it succeeds, the page shows:

OpenHands Authentication Successful!

This first installation also links the installing Slack user to their OpenHands user.

If Slack could not verify the Event Subscriptions URL while you created the app, return to the Slack app’s Event Subscriptions page and click Retry after OpenHands is deployed.

Link Users

Each Slack user who wants to invoke OpenHands must link their Slack account to their OpenHands account once.

Users can link from either place:

• In OpenHands, go to Settings > Integrations and click Install OpenHands Slack App.
• In Slack, mention @OpenHands. If the user is not linked yet, the bot replies with a sign-in link.

The link maps the Slack user to the OpenHands user. Conversations started from Slack use that OpenHands user’s repositories, LLM settings, organization, and connected integrations.

Add the Bot to Channels

Slack only delivers channel mentions to apps that are present in the channel.

For each channel where users should invoke OpenHands, add the app using one of these Slack flows:

• Type /invite @OpenHands in the channel.
• Open the channel details, go to Integrations, and add the OpenHands app.

For private channels, a member of the private channel must add the app.

Test the Integration

Mention the bot in a channel where it has been added:

@OpenHands Please summarize this thread and tell me what the next action should be.

If the prompt does not name a repository, OpenHands may show a repository picker in Slack. Choose a repository, or choose No Repository if the request does not need repository context.

When the conversation starts, OpenHands replies in Slack with a link to the OpenHands conversation.

How Slack Context Works

When a user mentions @OpenHands, OpenHands starts from the text in that Slack message. It also includes nearby Slack message text as context:

• A top-level channel mention includes recent top-level channel messages.
• A thread mention includes recent replies from that thread.
• Attachments, images, files, reactions, and Slack canvases are not included.

Follow-up messages in an existing OpenHands Slack thread continue the same OpenHands conversation.

Troubleshooting

Symptom	Check
The Slack app cannot verify the Event Subscriptions URL	Confirm https://app.<your-base-domain>/slack/on-event is reachable from the public internet with trusted TLS, then retry verification in Slack.
The Slack card is not visible in OpenHands	Confirm Slack is enabled in the Admin Console or Helm values and the updated deployment has been applied.
/slack/install fails during Slack OAuth	Confirm the Slack app’s redirect URL exactly matches https://app.<your-base-domain>/slack/install-callback.
Users get a login link every time they mention @OpenHands	Have the user complete the link flow from Settings > Integrations or the bot’s sign-in link.
Mentions are ignored	Confirm the bot has been added to the channel and SLACK_WEBHOOKS_ENABLED=true is set on the integrations deployment.
Repository selection does not load	Confirm the Slack app has the Options Load URL set to https://app.<your-base-domain>/slack/on-options-load.
Slack logs show missing_scope	Confirm the Slack app has all bot scopes from the manifest, then reinstall the app from /slack/install.
Slack events reach OpenHands but no conversation starts	Confirm the Slack user is linked to OpenHands and has access to the selected repository, if one was selected.