Manage SandboxesMessaging Channels

Set Up Slack

View as Markdown

Slack uses Socket Mode and requires both a bot token and an app-level token.

Prepare and Validate Tokens

Use SLACK_BOT_TOKEN for the bot user OAuth token that begins with xoxb-. Use SLACK_APP_TOKEN for the app-level Socket Mode token that begins with xapp-.

NemoClaw validates both tokens before it saves Slack credentials or enables the channel. This validation calls the live Slack APIs auth.test and apps.connections.open, so the tokens must belong to a real Slack app. These probes confirm token validity but do not report whether another Socket Mode connection uses the Slack app.

If Slack rejects the tokens, NemoClaw skips the Slack channel and does not apply the slack network policy preset. When Slack is skipped, the preset does not appear as applied in nemoclaw <name> policy list.

To exercise channel setup with placeholder tokens in a restricted network or hermetic test environment, set NEMOCLAW_SKIP_SLACK_AUTH_VALIDATION=1. Slack token format checks still apply.

Configure Allowlists

Set SLACK_ALLOWED_USERS to comma-separated Slack member IDs to authorize those users for DMs and channel @mention events. Set SLACK_ALLOWED_CHANNELS to comma-separated Slack channel IDs to restrict channel @mention handling.

When both allowlists are set, NemoClaw requires the mention to come from an allowed channel and an allowed member. Channel messages still require an explicit bot mention.

When an allowlist denies a Slack channel mention, NemoClaw sends a denial notice to the sender instead of dropping the message silently.

During sandbox startup, NemoClaw normalizes OpenShell credential placeholders into the environment shape expected by the Slack runtime, so post-rebuild Slack starts use the gateway-managed tokens instead of literal placeholder strings.

Avoid Duplicate Socket Mode Sessions

Conflict Detection Scope

NemoClaw checks for another active Slack sandbox only in the selected OpenShell gateway’s sandbox registry. It cannot detect or prevent Slack credential reuse across independent OpenShell gateways.

Run only one active Slack sandbox on each OpenShell gateway. Use distinct bot and app tokens for Slack sandboxes on different OpenShell gateways. Onboarding, rebuild, and channels add slack abort when they detect a conflict in the selected OpenShell gateway’s sandbox registry. Onboarding and rebuild have no override. For channels add slack only, pass --force to accept the conflict risk.

Wait for Slack Readiness

After a rebuild, OpenClaw can need more time to initialize the Slack plugin and connect through Socket Mode. Use the readiness check when automation must wait until Slack can receive messages:

$nemoclaw my-assistant channels status --channel slack --wait --timeout 180 --json

The command polls the manifest-defined Slack readiness check until all these conditions pass:

  • Slack is registered for the sandbox.
  • The slack network policy preset covers the sandbox.
  • The OpenClaw Slack account runtime is running.
  • Socket Mode is connected.
  • The OpenClaw account probe succeeds.

NemoClaw runs the live OpenClaw account probe only after Slack is registered and the slack preset is recorded and applied. Each live probe can send traffic through the configured Slack policy. The command does not change channel configuration or display Slack credentials. The default timeout is 180 seconds. The --timeout value is the total wait budget; NemoClaw limits live probes to the remaining budget and starts none at or after the deadline.

Deferred initialization is reported as retryable. A successful result exits with status 0 and reports the readiness evidence in JSON. The readiness object reports its state, category, reason, retryability, attempts, elapsed milliseconds, last transition timestamp, and last observed channel state. If the timeout expires, readiness.state, readiness.category, and readiness.reason are timeout; readiness.retryable mirrors readiness.lastObserved.retryable, and readiness.lastObserved.category and readiness.lastObserved.reason retain the underlying cause.

A terminal credential, policy, plugin, or runtime error exits nonzero with a structured category and reason. If Slack is paused with channels stop, the command skips the live probe and returns one terminal result with readiness.reason set to channel_paused. The command also exits nonzero with the timeout category when Slack does not become operational before the timeout. Use the category and reason to correct a terminal error. If the result reports a timeout during deferred initialization, inspect the OpenClaw logs, then rerun the readiness check.

Other messaging channels return their existing status snapshot in the result. They return readiness_not_supported for --wait until their channel manifests define equivalent readiness checks.

Enable Slack

$export SLACK_BOT_TOKEN="<your-slack-bot-token>"
$export SLACK_APP_TOKEN="<your-slack-app-token>"
$export SLACK_ALLOWED_USERS="<your-slack-member-id>"
$export SLACK_ALLOWED_CHANNELS="<your-slack-channel-id>"

Continue with Enable Channels During Onboarding or Add Channels After Onboarding.