agentic-slackbot

agentic-slackbot

一个简单的 Slack 机器人，使用 OpenAI Agents SDK 与 模型上下文协议（MCP） 服务交互。

另请参阅：agentic-telegram-bot——一个类似的 Telegram 演示机器人。

功能

• 支持在频道中 @提及和私信（DM）
• 支持感知线程的对话（后续消息会留在同一线程中）
• 通过 servers_config.json 连接任意 MCP 服务
• 可选的本地 shell，由 SHELL_ENABLED 和 SHELL_SKILLS_DIR 控制
• 支持 OpenAI 和兼容 OpenAI 的端点（包括 Azure OpenAI v1 API）
• 按对话保存历史记录，并自动截断（保留最近 10 轮）

安装依赖项

uv sync

Slack 应用设置

1. 在 api.slack.com/apps 创建新的 Slack 应用。
2. 启用 Socket Mode 并生成应用级令牌（xapp-...）。
3. 在 OAuth & Permissions 下添加以下机器人令牌权限范围：
   • app_mentions:read
   • chat:write
   • im:history
   • users:read
4. 在 Event Subscriptions 下订阅：
   • app_mention
   • message.im
5. 将应用安装到工作区，并复制机器人令牌（xoxb-...）。

环境变量

在根目录中创建 .envrc 或 .env 文件：

export SLACK_BOT_TOKEN=""
export SLACK_APP_TOKEN=""
export OPENAI_API_KEY=""

# Local shell (disabled by default)
# export SHELL_ENABLED=1
# export SHELL_SKILLS_DIR="./skills"  # optional; mount skills alongside the shell

如果你使用 Azure OpenAI（v1 API）或其他兼容 OpenAI 的端点：

export OPENAI_API_KEY=""
export OPENAI_BASE_URL="https://<resource-name>.openai.azure.com/openai/v1/"

可选的出站请求 HTTP 代理：

export HTTP_PROXY=""

可选的 OpenAI Agents SDK 详细日志：

export AGENT_VERBOSE_LOG=1

AGENT_VERBOSE_LOG 由本项目定义：设为真值时，应用会在启动期间调用 SDK 的 enable_verbose_stdout_logging() 辅助函数。0、false、no、off（不区分大小写）等值会被视为禁用。

以下环境变量由 OpenAI Agents SDK 直接读取（并非由本项目读取）。默认情况下，SDK 不会记录模型或工具负载。要在调试时临时包含这些内容：

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

这些负载日志可能包含敏感数据。调试后请恢复默认设置：

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1

Agent 指令

在项目根目录中创建 instructions.md 文件，写入 Agent 系统提示词：

You are a helpful assistant in a Slack workspace.
When responding, you must strictly use Slack's `mrkdwn` formatting syntax only.
Keep responses concise and well-structured.

instructions.md.example 中提供了示例。若缺少此文件，机器人将无法启动。

MCP 服务配置（可选）

创建 servers_config.json 文件以添加 MCP 服务。如果未提供此文件，机器人启动时不会配置任何 MCP 服务。

{
  "model": "gpt-5.4",
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"]
    }
  }
}

model 为可选项，默认值为 gpt-5.4。每个 MCP 服务还接受 timeout（秒，默认值为 30.0）和 enabled（默认值为 true）。

对于基于 HTTP 的 MCP 服务（Streamable HTTP），请使用 url：

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

对于本地 MCP 服务，请使用 uv --directory：

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/my-server", "run", "my-entrypoint"]
    }
  }
}

运行机器人

uv run bot

本地 Shell（可选）

机器人可以提供本地 ShellTool。此功能默认禁用。使用以下方式启用：

export SHELL_ENABLED=1

仅设置 SHELL_ENABLED=1 时，Agent 会获得不带预定义技能的基础本地 shell 访问权限。

Shell 技能（可选）

你可以选择在 shell 旁挂载一个技能目录。每个包含 SKILL.md 文件的直接子目录都会注册为一项技能，并作为提示信息提供给 Agent（技能属于建议性元数据——不会对命令执行进行沙盒限制）。

export SHELL_ENABLED=1
export SHELL_SKILLS_DIR="./skills"

除非设置了 SHELL_ENABLED，否则会忽略 SHELL_SKILLS_DIR。如果目录不存在或不包含有效技能，机器人会回退到基础 shell，并记录一条警告。

使用 Docker 镜像时，请在运行时挂载技能目录（镜像构建默认会排除该目录）：

-v /path/to/skills:/app/skills:ro

SKILL.md 文件应包含带有 name 和 description 字段的 YAML frontmatter：

---
name: my-skill
description: A brief description of what this skill does
---

Detailed instructions for the agent...

Docker

docker build -t agentic-slackbot .

docker run -d \
  --name slackbot \
  -e SLACK_BOT_TOKEN="" \
  -e SLACK_APP_TOKEN="" \
  -e OPENAI_API_KEY="" \
  -e SHELL_ENABLED=1 \
  -e SHELL_SKILLS_DIR=/app/skills \
  -v /path/to/instructions.md:/app/instructions.md \
  -v /path/to/skills:/app/skills:ro \
  agentic-slackbot

若要使用 MCP 服务，还需挂载配置文件：

docker run -d \
  --name slackbot \
  -e SLACK_BOT_TOKEN="" \
  -e SLACK_APP_TOKEN="" \
  -e OPENAI_API_KEY="" \
  -e SHELL_ENABLED=1 \
  -e SHELL_SKILLS_DIR=/app/skills \
  -v /path/to/instructions.md:/app/instructions.md \
  -v /path/to/skills:/app/skills:ro \
  -v /path/to/servers_config.json:/app/servers_config.json \
  agentic-slackbot

致谢

本项目基于 sooperset/mcp-client-slackbot 示例。