What OpenCluster uses it for
Slack provides responder observations, decisions, and actions around an incident. OpenCluster can list public channels, read permitted channel history and threads, resolve author names, answer direct app mentions in their originating thread, and—only when an advanced pasted user token permits it—search messages. For direct app mentions, Slack reads are restricted to the originating thread and integration. If OpenCluster cannot verify that origin, the investigation stops. Unavailable previous conversation history limits continuity explicitly; it does not expand access to other Slack conversations.Reply delivery
Completed reads and answers are sent in batches. Normal passes become eligible again after about one second, including passes with nothing ready to send. Temporary failures use bounded retry backoff; a failed Slack delivery does not change the investigation’s result, which remains available in OpenCluster. Delivery is at least once. Once a reply’s identity is saved, subsequent updates reuse that message. If Slack accepts a message before OpenCluster saves its identity, a crash or lost connection can leave an extra message on retry. A native stream append accepted before progress is saved can likewise appear twice. Retries of an acknowledged terminal answer only finish closing its stream; they do not append that answer again.Prerequisites
- The Admin role in OpenCluster.
- Permission to install a Slack app in your workspace.
- Permission to create a Slack app, only if your deployment has none registered and you are using the pasted-token path below.
Scopes
The installed app requests these seven bot scopes. It does not request
search:read;
workspace-wide search is unavailable to the installed bot. The advanced pasted-token
fallback can use a user token already granted search:read, which can expose private
conversations and direct messages visible to that person. Use that fallback only after
explicitly accepting its broader boundary.
Connect
Select Connect Slack, authorize in Slack, and you are returned to an integration that is alreadyverified. Nothing is pasted, and no token passes through your
clipboard or your browser. This is the only path hosted OpenCluster offers, and a
self-hosted deployment gets the identical experience once it registers its own Slack app
and configures the app’s client credentials.
The steps below are the advanced fallback, offered only by a deployment that has no
Slack app registered at all — an air-gapped install, typically. Integrations already
connected this way keep working unchanged; there is nothing to migrate.
1
Create the Slack app
Create an app at api.slack.com/apps. Under OAuth &
Permissions, add
assistant:write, chat:write, app_mentions:read,
channels:read, channels:history, users:read, and groups:history as bot
token scopes when enabling app mentions. A read-only pasted bot needs only the
channel and user scopes required by the reads it offers.2
Install the app
Install it to the workspace and copy the Bot User OAuth Token (
xoxb-…).3
Create the integration
In OpenCluster, choose Slack, enter a name, and paste the token. OpenCluster
verifies the token with Slack before encrypting and storing it.The product API accepts the configuration key
botToken. The
field accepts either token type described on this page.4
Grant channel access
Invite the app to each public or private incident channel it should read.
OpenCluster does not join channels on its own.
Verify
Select Verify on the integration. Verification checks the credential and records its granted scopes. The connected workspace identity comes from the completed connection and is not editable configuration. A bot token holding the scopes OpenCluster asks for reportsverified. Workspace-wide
search is listed as an unavailable Tool rather than a missing scope, because
OpenCluster does not request search:read — its absence is a deliberate boundary, not a
gap to close.
The integration read reports each Tool individually, with the reason when a required grant
is unavailable. A failed credential check sets the Integration to failed; a token with
none of the usable scopes cannot be offered to investigations.
During investigations
Available reads depend on verified scopes, token type, and channel membership. OpenCluster may list public channels, read permitted history within the incident window, or follow the originating thread. Search is unavailable to the installed bot; an advanced pasted user token withsearch:read can search conversations visible to
that person, not only channels joined by the app. Messages are treated as leads; a
responder’s statement alone does not establish a cause.
Talking to OpenCluster in Slack
Where this deployment serves the Slack agent surface, OpenCluster can be spoken to as well as read from.
The reply is one message that fills in as the work happens: what is being read, what each read
found, and then the answer. OpenCluster never posts its internal reasoning, and it never answers
its own messages.
What it can see is unchanged by any of this. It reads the channels it has been invited to, at
investigation time, and keeps only the summaries and references its provenance model already
keeps — connecting Slack does not create a second archive of your workspace. Everything anyone
types is treated as evidence about what was said, never as an instruction to OpenCluster.
If OpenCluster cannot finish answering, it says so in the thread. The investigation behind it is
unaffected and stays readable in the console.
Limitations
- Bot-token channel and thread reads are limited to public channels and private channels the app has been explicitly invited to. An advanced pasted user token can additionally return private-channel, group-message, and direct-message search results visible to that person.
- Search uses Slack’s day-level date filters. A result can fall outside the exact investigation window on either boundary day.
- Text only. Files, attachments, reactions, and edit history are not read.
- OpenCluster’s only writes are its own replies in the thread it was addressed in. It does not react, join channels, post into channels it was not spoken to in, or edit anyone’s message.
- By default, Slack reads stay in the thread that opened the Conversation. A broader channel history or search is a separate bounded Tool, is offered only from verified Slack scopes, appears in investigation activity, and remains subject to Slack’s own channel permissions.
- Workspace-wide search is not requested by the recommended bot installation. OpenCluster reasons over conversations it has been invited into, not everything an employee can see.
- A message sent while OpenCluster is still working is picked up at the end of the current turn rather than starting a second one. A running turn cannot be interrupted from Slack.
- Reads are bounded. Truncated channel, history, and thread results are marked.
- Slack rate limits are honored and surfaced in the investigation record.
- Resolving an incoming message’s permalink happens after acknowledgement. A failed lookup cannot delay acknowledgement, discard the durable question, or prevent the Investigation.
Troubleshooting
invalid_auth: paste a current token and verify again.- No channel messages: invite the app to the channel and confirm
channels:historyis granted. - No message search: this is expected for an installed bot. Rely on channel and thread reads, or explicitly evaluate the broader advanced user-token fallback.
- Stored credential cannot be opened: restore the deployment encryption key that sealed the credential, restart, and verify again.
Recover a failed reply
If a reply remains failed after its bounded retries, an Admin can make that Slack Message eligible for processing again. Find its Conversation ID and message sequence in the Conversation, then send an authenticatedPOST request to
/api/v1/slack/conversations/<conversation-id>/messages/<sequence>/recover. Recovery is
accepted only for terminal failed work in the same Organization and is recorded in the
audit log.