Connect an Agent to Slack

Connect a dedicated Codex Agent to a Slack workspace using Socket Mode. A Kubernetes installation and an existing Slack app are required. Slack credentials go to the Agent's gateway; model credentials are configured separately.

Before you start

Enable Slack Socket Mode and create an app-level token (xapp-) with connections:write. Subscribe to the bot event app_mention. Grant the bot token (xoxb-) app_mentions:read to receive channel mentions and chat:write to send replies. Reinstall the Slack app if you add bot scopes to an existing installation.
Use one Slack app, with its own app-level and bot tokens, for each Agent. Slack can deliver an event to any active Socket Mode connection for that app. If Agents share an app, the intended Agent can miss the event.
Invite the app's bot to the channel. Your Installation operator must allow the gateway's Slack network traffic and provide a runtime image that includes the native Slack plugin.
Require the operator to configure and verify both Slack proxies before enabling Slack: gateway messaging and Console directory lookup use separate settings and egress rules.
Choose a dedicated Codex Agent on Kubernetes and configure its model authentication. Embedded OpenClaw execution cannot isolate channel credentials from the Harness, and Kubernetes Compute rejects embedded versions with external channels enabled. The Standard OpenClaw preset must leave channels disabled.
First deployment generates required connection credentials. It requires Agent deploy, plus Agent read and operate when generation is needed. Selecting Secrets requires readable Secret metadata and caller operate on each selected Secret. Saving token bindings requires Configuration update and Namespace IAM administration to grant the Agent access to each exact Secret. Creating a token Secret also requires Secret creation permission in the Namespace.

Configure both Slack proxies

For Slack-enabled k3d and EKS installations, configure both paths before creating a Slack-enabled dedicated Codex Agent. A working Socket Mode connection does not establish that Console user or channel search works.

Path	Required setting	Consumer
Slack messaging and Socket Mode	Installation `drivers.compute.configuration.runtime.channels.proxyUrl`	Dedicated gateway
Console lookup and credential validation	Helm `slackProxy.enabled` or `api.channelDirectoryProxyUrl`	OCC API

Provision a reviewed HTTP CONNECT proxy that each consumer can reach. For production, use Helm slackProxy.enabled: true. The chart then creates a private proxy Service, points the API directory proxy at its Service DNS name, admits API and managed gateway callers, and lets the proxy reach public IPv4 destinations on TCP 443, excluding private and reserved ranges. For an external proxy instead, use a literal IPv4 address and explicit port with no URL credentials or path. Setting one proxy path does not configure the other. The managed proxy serves only API directory lookup and dedicated gateway traffic; it does not make embedded OpenClaw Slack-capable.

The proxy checks the Slack hostname on every CONNECT request, so its network policy can allow public HTTPS without tracking Slack's rotating IP addresses. Do not store signed WSS URLs or credentials in configuration or documentation.

The directory path needs CONNECT slack.com:443. The gateway path also needs the Slack Socket Mode endpoints returned for the app; review the required slack.com, slack-edge.com, and slack-msgs.com domains and their subdomains. Retain TLS certificate verification. See the directory proxy contract and gateway network boundary.

Merge these fragments into the protected Installation and Helm inputs. Replace documentation-only addresses with reviewed endpoints; preserve other settings.

yaml

# installation.yamldrivers:  compute:    configuration:      runtime:        channels:          proxyUrl: http://openclaw-enterprise-slack-proxy.openclaw-system.svc:3128          managedProxy:            hostname: openclaw-enterprise-slack-proxy.openclaw-system.svc            namespace: openclaw-system            podLabels:              app.kubernetes.io/name: openclaw-enterprise              app.kubernetes.io/instance: oce              app.kubernetes.io/component: slack-proxy            port: 3128

yaml

# Helm valuesslackProxy:  enabled: true

Apply both inputs through the installation procedure and roll out the affected control-plane processes so they load the new configuration. With the managed proxy, Helm grants API egress to the proxy Pods. Kubernetes Compute grants gateway egress to the channel proxy named in the Installation runtime setting. Keep Slack tokens in Namespace Secrets; do not place them in these inputs or the proxy configuration.

For an existing installation, once OCC reloads the gateway proxy setting, deploy a new version for every affected running Slack Agent. Its gateway environment and channel NetworkPolicy are rendered during version preparation; restarting OCC alone does not update existing gateways. Preserve stopped Agents' state. Changing only the API directory proxy does not require an Agent redeployment.

Before handing off the Slack setup, verify both paths:

In the Console, select the Slack bot Secret and search for a known user and channel visible to that bot. Require successful results. The bot needs users:read, channels:read, and groups:read for private channels.
After deploying, require the current gateway and Harness to be Ready and confirm Slack Socket Mode is connected. Use the authorized message proof below to establish delivery separately.
Confirm the proxy denies an unrelated public destination and a private upstream destination from the same permitted caller path.

A directory response of 503 can indicate that the API cannot reach Slack; enable the managed Slack proxy or check the external proxy route. When the API has no Slack proxy and gets no answer from Slack, Agent provisioning and deployment answer 409 and ask for an Installation administrator to give the API a route to Slack: Helm slackProxy.enabled or api.channelDirectoryProxyUrl. If the API has another approved route to Slack, such as a sign-in setting with empty egressCidrs, try again; a timeout on that route gets the same answer. A missing-scope response requires updating the bot's Slack scopes. Missing gateway proxy configuration prevents Slack-enabled workload preparation. Resolve each path independently; entering exact IDs does not verify directory lookup.

Connect and verify

Open the Agent's Create new version draft in the console, then open Channels and Configure Slack (or Edit Slack for an existing setup). Start with Slack credentials at the top: select a Namespace Secret or Create new Secret... for each token. The bot token enables channel and people name lookup; the app token is used for Socket Mode. An enabled Slack setup saves only with both. Exact-ID entry remains available without name lookup. Enable Slack and choose Channels, then select Specific people or Everyone in these channels under channel access. Leave Require a mention enabled for this setup. To receive messages without a mention, follow Enable channel messages without mentions. New Slack setups use threaded channel replies. Choose Disabled under Direct-message policy for channel-only access, or keep Allowlist and select Allowed people in direct messages. When creating a Secret, the modal prefills the token key and accepts its value in a password field. Create Secret stores it immediately; Save configuration saves the selected bindings. Cancelling the drawer discards selections but keeps any newly created Secrets. If multiple Agents use this Configuration, the edit also affects their future deployments.
Open Credentials. If tokens are still missing (a Configuration saved before this check), select their Secrets and Save channel Secrets. OCC stores them as Namespace Secrets, grants the Agent access, and saves Configuration bindings for gateway delivery. Stored Secret bindings confirm storage only; they do not prove Slack accepted the tokens. Bound tokens show a synthetic password mask. To replace one token, edit that field and leave the other unchanged; its stored value is preserved.
Select Deploy new version to apply the saved bindings. OCC generates missing connection credentials during the first deployment when the Compute Driver requires them. After a channel draft or Secret value change, explicitly redeploy each consumer. Follow Secret updates when replacing an existing token.
From a real Slack user account, send an explicit @mention to the Agent in an allowed channel. Ask it to repeat a short unique phrase. A reply containing that phrase confirms that the message reached the Agent and a response returned to Slack. An accepted deployment or Stored credentials alone do not prove that path.

If you manage Configuration through the API, use the native Slack Socket Mode example. The console supports the default Socket Mode account and gateway environment references; non-Socket settings, wildcard channel maps, mixed per-channel mention settings, mixed per-channel sender lists, and sender IDs that cannot be represented in a comma-separated field may need an API edit.

Enable channel messages without mentions (optional)

Consider model token costs before disabling Require a mention. Slack event subscriptions control delivery; the channel's mention setting controls admission to model turns. With this setting enabled, ordinary channel text without a mention is rejected before model dispatch. Replies in threads where the bot participates can count as implicit mentions. Disabling the setting lets other messages trigger model turns, increasing input tokens for messages and context and output tokens for generated responses. This can increase costs substantially in busy channels. Receiving a Slack event alone does not consume model tokens; calling the model does.

Disabling Require a mention changes the Agent's message filter. It does not change the Slack app's event subscriptions. The bot token's scopes and the app's bot event subscriptions must both permit channel messages:

Open Your Slack Apps, select the Agent's app, then open Features → Event Subscriptions → Subscribe to bot events. Select Add Bot User Event and add the event for each channel type you use:

Channel type Bot event Required bot token scope

Public message.channels channels:history

Private message.groups groups:history

Keep app_mention and select Save Changes.
Under OAuth & Permissions → Bot Token Scopes, confirm the required scopes. Add any missing scopes, then select Install App → Reinstall to Workspace if you added scopes.
In the Console, open Channels → Edit Slack, clear Require a mention, save, and deploy a new version. If the running Agent already has this setting disabled, changing the Slack event subscriptions does not require another Agent deployment.
From an allowed user account, send a new top-level message without an @mention in a configured channel where the bot is a member. Ask the Agent to repeat a short unique phrase and confirm that its reply contains that phrase. Do not use an existing thread where the bot has participated; its implicit mention handling can admit the message even when mentions are required.

Channel type	Bot event	Required bot token scope
Public	`message.channels`	`channels:history`
Private	`message.groups`	`groups:history`

Enable direct messages (optional)

Channel mentions do not deliver direct messages, even if the user mentions the bot. To enable one-to-one messages:

In Slack, subscribe to the bot event message.im and grant the bot token im:history. Reinstall the Slack app if the scope is new. In App Home settings, enable sending messages from the Messages tab.
In Channels → Edit Slack, select Allowlist under Direct-message policy and choose Allowed people in direct messages. Save and redeploy. Choose Disabled to block DMs (recommended for organization-wide installs), or use Pairing or Open. Channel user IDs do not grant DM access. If native dm.enabled is false, enable it in native Configuration JSON before testing DMs.
From an allowed user account, send the app a direct message with a new phrase and confirm a reply. A channel reply does not verify direct messages.

Troubleshoot

Credentials show Bound but the Agent does not reply: first confirm that the gateway connected to Slack, the bot has joined the configured channel, and the channel ID is correct. Then send an explicit mention. Ask the operator to check gateway network access if it cannot connect.
Some messages never reach the Agent: check whether another Agent connects to the same Slack app. Give each Agent its own app and use that app's tokens.
The Agent replies only to mentions after Require a mention is disabled: check the app's bot event subscriptions as well as its bot token scopes. Follow Enable channel messages without mentions.
Channel messages work but direct messages do not: check the message.im subscription, the installed bot token's im:history scope, and whether the sender's Slack user ID is allowed by the native allowFrom setting and direct-message policy.
Credential save failed or the response was lost: reload the Agent and inspect saved Secrets, IAM bindings, and Configuration before retrying after a partial save; those writes are separate and are not automatically rolled back.
Slack replies with a model error: check the Agent's model authentication and selected version independently. Slack connection alone does not establish model access.