0xmrpeter 25475fb74a docs(slack): add output mode section, /outputmode setup step, fix /openacp-new typo
- slack.md: add Step 6 sub-section for registering /outputmode slash command
- slack.md: add outputMode field to config table
- slack.md: add Output Mode section (Low/Medium/High, thread rendering, /outputmode usage)
- slack.md: add /outputmode to commands table and examples
- slack-issues.md: fix incorrect /openacp-new command (should be /new)
- slack-issues.md: update outputMode reference, remove deprecated displayVerbosity mention
- slack-issues.md: add /outputmode troubleshooting entry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-31 15:03:02 +07:00

121 lines
6.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Slack Issues
If you haven't finished initial setup, see the [Slack Setup guide](../platform-setup/slack.md) first.
---
### Socket Mode connection fails on startup
**Symptoms:** OpenACP exits immediately with an error like `Slack adapter requires botToken, appToken, and signingSecret` or the Bolt app fails to connect.
**Cause:** Socket Mode requires three credentials: a **Bot Token** (`xoxb-…`), an **App-Level Token** (`xapp-…`), and a **Signing Secret**. Missing any one of them prevents the adapter from starting.
**Solution:**
1. In the [Slack API dashboard](https://api.slack.com/apps), open your app.
2. **Bot Token**: Settings → **OAuth & Permissions** → copy the `xoxb-…` token.
3. **App-Level Token**: Settings → **Basic Information** → **App-Level Tokens** → generate one with the `connections:write` scope. It starts with `xapp-`.
4. **Signing Secret**: Settings → **Basic Information** → **App Credentials** → Signing Secret.
5. Add all three to `~/.openacp/config.json` under `channels.slack`.
---
### Bot doesn't respond to messages
**Symptoms:** You post in the session channel but the agent is silent, with no log output.
**Cause:** The Slack event router only processes messages in channels that have an active OpenACP session. Messages in other channels, DMs, or the notification channel are not routed to an agent.
**Solution:**
1. Use `/new` to create a new session — this creates a dedicated channel for the conversation.
2. Ensure Socket Mode is enabled for your app: Settings → **Socket Mode → Enable Socket Mode**.
3. Check that the `message.channels` event subscription is present under **Event Subscriptions → Subscribe to bot events**.
4. Verify `security.allowedUserIds` — if non-empty, your Slack user ID must be listed.
---
### "not_allowed_token_type" error
**Symptoms:** Logs show `not_allowed_token_type` from the Slack API, or `auth.test() did not return user_id`.
**Cause:** A User Token (`xoxp-…`) was provided where a Bot Token (`xoxb-…`) is required, or vice versa. The App-Level Token (`xapp-…`) was placed in the wrong field.
**Solution:**
- `botToken` must be an `xoxb-…` token from **OAuth & Permissions**.
- `appToken` must be an `xapp-…` token from **Basic Information → App-Level Tokens**.
- Do not swap these — they serve different purposes. The bot token authenticates API calls; the app token opens the Socket Mode WebSocket connection.
---
### Rate limiting causes delayed or dropped messages
**Symptoms:** Responses are slow to appear, or logs show rate limit warnings from the Slack API.
**Cause:** Slack enforces per-method rate limits (Tier 1–4). Heavy usage — many concurrent sessions posting messages quickly — can exhaust these limits.
**Solution:**
- OpenACP's `SlackSendQueue` serialises outbound API calls automatically to respect rate limits.
- If you hit limits consistently, reduce `security.maxConcurrentSessions` in config.
- Avoid bursting many messages at once; consider using `outputMode: "low"` in your config, or type `/outputmode low` in a session channel to reduce intermediate streaming updates.
---
### Interactivity (permission buttons) not working
**Symptoms:** The agent posts a permission request with buttons, but clicking them does nothing.
**Cause:** Interactivity requires Socket Mode to be enabled. If the app is in HTTP mode or the app-level token is missing/invalid, button interactions are never delivered.
**Solution:**
1. Enable Socket Mode: **Settings → Socket Mode → Enable**.
2. Ensure the `appToken` (`xapp-…`) is valid and has the `connections:write` scope.
3. Under **Interactivity & Shortcuts**, confirm that Interactivity is **On**.
4. Restart OpenACP after enabling interactivity.
---
### Voice messages are not transcribed
**Symptoms:** You send a voice memo in Slack but the agent receives no text, or receives the file path instead of a transcription.
**Cause:** Slack voice clips are audio files. OpenACP downloads the file and passes it to the agent as an audio attachment — but this requires the bot to have the `files:read` scope, and the agent must support audio input.
If the download returns an HTML login page instead of binary audio, the `files:read` scope is missing.
**Solution:**
1. Add `files:read` to your bot's OAuth scopes: **OAuth & Permissions → Bot Token Scopes → Add `files:read`**.
2. Reinstall the app to the workspace (Slack requires reinstallation after scope changes): **Settings → Install App → Reinstall**.
3. Confirm your agent supports audio input — agents that do not expose audio capability receive the file path as text instead.
---
### `/outputmode` command does nothing or returns "command not found"
**Symptoms:** Typing `/outputmode` shows no autocomplete, or Slack says the command is not found.
**Cause:** The `/outputmode` slash command must be registered in the Slack app's configuration before Slack delivers its payloads to OpenACP.
**Solution:**
1. In the [Slack API dashboard](https://api.slack.com/apps), open your app.
2. Go to **Slash Commands** in the left sidebar.
3. Click **Create New Command** and fill in:
- **Command**: `/outputmode`
- **Request URL**: leave blank (Socket Mode delivers the payload via WebSocket)
- **Short Description**: `Change output verbosity`
- **Usage Hint**: `[low|medium|high]`
4. Click **Save**.
5. Reinstall the app: **Settings → Install App → Reinstall to Workspace**.
6. Restart OpenACP.
---
### Channel creation fails or produces duplicate channels
**Symptoms:** Each restart creates a new `#openacp-…` channel, or channel creation fails with a permissions error.
**Cause:** The bot needs `channels:manage` (for public channels) or `groups:write` (for private channels) scope to create channels. Duplicate channels appear when the saved `startupChannelId` in config has been deleted.
**Solution:**
1. Add the required scope: **OAuth & Permissions → Bot Token Scopes → `channels:manage`** (or `groups:write` for private).
2. Reinstall the app after adding scopes.
3. If duplicate channels have accumulated, delete the extras in Slack and clear `startupChannelId` from `~/.openacp/config.json`. OpenACP will create one clean channel on next startup and save its ID for reuse.