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.
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 revisions 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 revision for every affected running Slack Agent. Its gateway environment and channel NetworkPolicy are rendered during revision 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. 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. Both are required before deployment. 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. 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, 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 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 enter Allowed DM user IDs. 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.
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 active revision independently. Slack connection alone does not establish model access.