AI Agents · 课时

Slack Bolt SDK 基础

Q: 「Slack Bolt SDK 基础」这节课中我会学到什么？

应用初始化、机器人令牌、套接字模式与 HTTP 模式，以及事件订阅。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

应用初始化、机器人令牌、套接字模式与 HTTP 模式，以及事件订阅。

Slack Bolt SDK 基础 是 CoddyKit 上的免费 AI Agents 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

为什么使用 Slack Bolt 开发代理？

Slack Bolt 是用于构建 Slack 应用的官方 Python SDK。它负责处理 OAuth、事件路由、中间件以及请求/响应生命周期，因此您的代理可以专注于业务逻辑，而不必处理 HTTP 底层通信。Bolt 同时支持套接字模式（WebSocket）和 HTTP 模式。

# Install Slack Bolt
# pip install slack-bolt

# Slack Bolt handles:
# - Event subscriptions (messages, mentions, reactions)
# - Slash commands (/summarize, /ask)
# - Interactive components (buttons, modals, select menus)
# - Shortcuts (global and message shortcuts)
# - OAuth 2.0 for multi-workspace apps
# - Request signature verification (security)

print('Slack Bolt is the official Python SDK for Slack apps')

机器人令牌和签名密钥

Slack 应用需要两项凭据：用于调用 API 和发布消息的机器人令牌（以 xoxb- 开头），以及用于验证传入事件确实来自 Slack 的签名密钥。两者都可以在 Slack 应用设置控制台中找到。

import os
from slack_bolt import App

# Load credentials from environment variables
# Never hardcode tokens!
BOT_TOKEN = os.environ['SLACK_BOT_TOKEN']        # xoxb-...
SIGNING_SECRET = os.environ['SLACK_SIGNING_SECRET']  # hex string

# Initialize the Bolt app
app = App(
    token=BOT_TOKEN,
    signing_secret=SIGNING_SECRET
)

print('Slack Bolt app initialized')
print(f'Bot token prefix: {BOT_TOKEN[:10]}...')

所需的机器人令牌权限范围

Slack 应用使用 OAuth 权限范围来定义机器人可以执行的操作。请在 Slack 应用控制台的 OAuth & 权限 → 权限范围 → 机器人令牌权限范围下添加权限范围。AI 代理机器人常用的权限范围包括：

chat:write — 发布消息
app_mentions:read — 接收 @mentions
channels:history — 读取频道消息
commands — 接收斜杠命令
im:write — 发送私信

# Required scopes for a typical AI agent bot:
# - chat:write          → post messages to channels
# - app_mentions:read   → receive @bot mentions
# - channels:history    → read message history
# - channels:read       → list channels
# - commands            → handle slash commands
# - im:write            → send DMs
# - im:read             → receive DMs
# - users:read          → get user info (name, email)

# Add these in Slack App settings:
# https://api.slack.com/apps -> Your App -> OAuth & Permissions

print('Configure scopes in Slack App dashboard before installing')

套接字模式与 HTTP 模式

套接字模式通过持久的 WebSocket 连接到 Slack——无需公共 URL，非常适合开发和内部工具。HTTP 模式需要一个 Slack 用于发送事件的公共 HTTPS 端点，这是生产应用和多工作区安装所必需的。

# SOCKET MODE (development / internal tools):
# - No public URL needed
# - Uses an App-Level Token (xapp-...)
# - Great for local development
from slack_bolt.adapter.socket_mode import SocketModeHandler

APP_TOKEN = os.environ['SLACK_APP_TOKEN']  # xapp-...
handler = SocketModeHandler(app, APP_TOKEN)

# handler.start()  # blocks and handles events

# HTTP MODE (production):
# - Requires public HTTPS URL configured in Slack app settings
# - Works with Flask, FastAPI, etc.
from slack_bolt.adapter.flask import SlackRequestHandler
from flask import Flask, request

flask_app = Flask(__name__)
slack_handler = SlackRequestHandler(app)

print('Socket Mode: dev/internal; HTTP Mode: production')

初始化应用并启动套接字模式

套接字模式下最简的 Slack Bolt 应用需要：创建 App、至少注册一个处理器，然后启动 SocketModeHandler。该处理器会连接到 Slack 的事件基础设施，并持续保持连接，直到您停止进程。

import os
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

app = App(
    token=os.environ['SLACK_BOT_TOKEN'],
    signing_secret=os.environ['SLACK_SIGNING_SECRET']
)

@app.event('app_mention')
def handle_mention(event, say):
    user = event['user']
    text = event['text']
    say(f'Hi <@{user}>! You said: {text}')

# Start the app
if __name__ == '__main__':
    handler = SocketModeHandler(
        app,
        os.environ['SLACK_APP_TOKEN']
    )
    handler.start()  # blocks until process is killed

使用 ngrok 测试（HTTP 模式）

在使用 HTTP 模式开发期间，请使用 ngrok 将本地服务器暴露到互联网。运行 ngrok http 3000 获取公共 HTTPS URL，然后更新 Slack 应用的事件订阅和斜杠命令 URL，使其指向该地址。

# HTTP mode setup with Flask:
from flask import Flask, request
from slack_bolt import App
from slack_bolt.adapter.flask import SlackRequestHandler
import os

app = App(
    token=os.environ['SLACK_BOT_TOKEN'],
    signing_secret=os.environ['SLACK_SIGNING_SECRET']
)

@app.event('app_mention')
def handle_mention(event, say):
    say('Hello from HTTP mode!')

flask_app = Flask(__name__)
handler = SlackRequestHandler(app)

@flask_app.route('/slack/events', methods=['POST'])
def slack_events():
    return handler.handle(request)

# Run: python app.py
# In another terminal: ngrok http 3000
# Set https://abc123.ngrok.io/slack/events as your Request URL in Slack

套接字模式的应用级令牌

套接字模式需要额外的应用级令牌（以 xapp- 开头），并且该令牌需要 connections:write 权限范围。这与机器人令牌是分开的。请在 Slack 应用设置的基本信息 → 应用级令牌下生成该令牌。

# App-Level Token setup:
# 1. Go to https://api.slack.com/apps -> Your App
# 2. Click 'Basic Information'
# 3. Scroll to 'App-Level Tokens'
# 4. Click 'Generate Token and Scopes'
# 5. Name it 'socket-mode-token'
# 6. Add scope: connections:write
# 7. Click 'Generate'
# 8. Copy the xapp-... token

# In your .env file:
# SLACK_BOT_TOKEN=xoxb-...
# SLACK_SIGNING_SECRET=abc123...
# SLACK_APP_TOKEN=xapp-...

from slack_bolt.adapter.socket_mode import SocketModeHandler
import os

handler = SocketModeHandler(
    app=app,
    app_token=os.environ['SLACK_APP_TOKEN']  # xapp-...
)
print('App-Level Token required for Socket Mode')

Bolt 中间件

Bolt 支持中间件——在每个事件处理器之前运行的函数。您可以将中间件用于日志记录、身份验证、速率限制，或使用用户数据丰富事件。调用 next() 将控制权交给下一个中间件或处理器。

from slack_bolt import App
import time
import logging

app = App(
    token=os.environ['SLACK_BOT_TOKEN'],
    signing_secret=os.environ['SLACK_SIGNING_SECRET']
)

logger = logging.getLogger(__name__)

# Request logging middleware
@app.middleware
def log_request(logger, body, next):
    event_type = body.get('event', {}).get('type', 'unknown')
    start = time.time()
    logger.info(f'Incoming event: {event_type}')
    next()  # must call next() to continue
    elapsed = time.time() - start
    logger.info(f'Handled {event_type} in {elapsed:.2f}s')

print('Middleware runs before every event handler')

Bolt 中的错误处理

使用 @app.error 注册全局错误处理器，以捕获事件处理器中未处理的异常。这样可以防止应用崩溃，并让您记录错误、通知监控频道，或向用户返回错误消息。

from slack_bolt import App
import traceback

app = App(
    token=os.environ['SLACK_BOT_TOKEN'],
    signing_secret=os.environ['SLACK_SIGNING_SECRET']
)

@app.error
def custom_error_handler(error, body, logger):
    logger.error(f'Error handling event: {error}')
    logger.error(traceback.format_exc())

    # Try to notify the user who triggered the error
    event = body.get('event', {})
    channel = event.get('channel')
    if channel:
        app.client.chat_postMessage(
            channel=channel,
            text='Sorry, I encountered an error. The team has been notified.'
        )

print('Global error handler prevents unhandled crashes')

使用 Slack Web API 客户端

app.client 属性可以直接访问 Slack Web API，用于执行事件处理器未涵盖的操作。您可以使用它发布消息、上传文件、邀请用户加入频道，或通过编程方式获取频道历史记录。

from slack_bolt import App

app = App(
    token=os.environ['SLACK_BOT_TOKEN'],
    signing_secret=os.environ['SLACK_SIGNING_SECRET']
)

# Use app.client for direct API calls
def post_to_channel(channel_id, text):
    result = app.client.chat_postMessage(
        channel=channel_id,
        text=text
    )
    print(f'Message posted: ts={result["ts"]}')
    return result

# Get channel list
def list_channels():
    result = app.client.conversations_list(
        types='public_channel',
        limit=100
    )
    channels = result['channels']
    print(f'Found {len(channels)} public channels')
    return channels

# Look up user info
def get_user(user_id):
    result = app.client.users_info(user=user_id)
    return result['user']

环境设置检查清单

在 Slack 机器人正式上线前，请完成以下设置检查清单，以确保配置正确：

环境变量中已设置机器人令牌和签名密钥
已在 Slack 应用控制台中添加所需权限范围
已启用事件订阅（app_mention、message.im 等）
已启用套接字模式（或为 HTTP 模式设置公共 URL）
应用已安装到工作区（OAuth 流程已完成）

import os
from slack_bolt import App

def verify_slack_setup():
    required_env = [
        'SLACK_BOT_TOKEN',
        'SLACK_SIGNING_SECRET',
        'SLACK_APP_TOKEN'
    ]
    missing = [var for var in required_env if not os.environ.get(var)]
    if missing:
        raise EnvironmentError(f'Missing env vars: {missing}')

    token = os.environ['SLACK_BOT_TOKEN']
    if not token.startswith('xoxb-'):
        raise ValueError('SLACK_BOT_TOKEN must start with xoxb-')

    app_token = os.environ['SLACK_APP_TOKEN']
    if not app_token.startswith('xapp-'):
        raise ValueError('SLACK_APP_TOKEN must start with xapp-')

    print('Slack environment setup looks correct!')

verify_slack_setup()

快速检查：套接字模式与 HTTP 模式

测试您对 Slack Bolt 部署模式的理解。

Slack Bolt 基础知识回顾

您已经掌握了使用 Bolt 构建 Slack 机器人的基础：

App(token, signing_secret) — 使用环境变量中的凭据初始化 Bolt 应用
机器人令牌（xoxb-）用于 API 调用；应用级令牌（xapp-）用于套接字模式
套接字模式 — 使用 WebSocket，无需公共 URL，非常适合开发和内部工具
HTTP 模式 — 使用公共 HTTPS 端点，生产应用和多工作区应用必需
权限范围 — 在 Slack 应用控制台中配置，只添加所需的权限
中间件和 @app.error — 用于日志记录、验证和错误处理

常见问题解答

「Slack Bolt SDK 基础」课时是免费的吗？

是的 — 「Slack Bolt SDK 基础」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「Slack Bolt SDK 基础」这节课中我会学到什么？

应用初始化、机器人令牌、套接字模式与 HTTP 模式，以及事件订阅。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「Slack Bolt SDK 基础」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents