> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-alona-ohe-slack-install-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  This page is for self-hosted OpenHands Enterprise. If you use OpenHands Cloud,
  see [Slack Integration](/openhands/usage/cloud/slack-installation).
</Note>

## 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.

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

## 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](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.

```yaml theme={null}
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](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:

```bash theme={null}
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"
```

<Note>
  The helper currently uses `uv`. If you do not want to install `uv`, use the
  manifest option above.
</Note>

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.

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="Standalone Helm">
    Configure the `openhands` chart with the Slack client ID and Slack resolver
    flag:

    ```yaml theme={null}
    slack:
      enabled: true
      clientId: "<slack-client-id>"

    env:
      ENABLE_V1_SLACK_RESOLVER: "true"
    ```

    Configure the `openhands-secrets` chart with the Slack secrets:

    ```yaml theme={null}
    config:
      slack_client_id: "<slack-client-id>"
      slack_client_secret: "<slack-client-secret>"
      slack_signing_secret: "<slack-signing-secret>"
    ```

    Then redeploy both charts:

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

After redeploying, confirm the integrations service has Slack enabled:

```bash theme={null}
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:

```text theme={null}
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:

```text theme={null}
OpenHands Authentication Successful!
```

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

<Note>
  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.
</Note>

## 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:

```text theme={null}
@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.                                     |