Back to Details

slack

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Slack Skill

Slack 技能

Slack workspace integration with two components:
  1. Scripts — 7 Python scripts for on-demand Slack operations (bundled here)
  2. Session Bridge — connect THIS Claude Code session to Slack (background listener + inbox file, no extra API costs)
Daemon & Soul Engine: The Claudicle daemon (unified launcher, soul engine, cognitive pipeline, three-tier memory, Soul Monitor TUI) now lives in its own repo: github.com/tdimino/claudicle. Install Claudicle separately for daemon features.
Slack工作区集成包含两个组件：
  1. 脚本 — 7个用于Slack按需操作的Python脚本（已打包在此）
  2. Session Bridge — 将当前Claude Code会话连接到Slack（后台监听器+收件箱文件，无额外API费用）
守护进程与灵魂引擎：Claudicle守护进程（统一启动器、灵魂引擎、认知管道、三层记忆、Soul Monitor TUI）现在托管在独立仓库中：github.com/tdimino/claudicle。如需使用守护进程功能，请单独安装Claudicle。

When to Use This Skill

何时使用该技能

Scripts (on-demand)

按需脚本

  • Posting messages to Slack channels or threads
  • Reading channel history or thread replies
  • Searching messages or files across the workspace
  • Adding or managing reactions on messages
  • Uploading files or code snippets
  • Listing channels, getting channel info, or joining channels
  • Looking up users by name, ID, or email
  • 向Slack频道或线程发送消息
  • 读取频道历史消息或线程回复
  • 在整个工作区内搜索消息或文件
  • 为消息添加或管理反应
  • 上传文件或代码片段
  • 列出频道、获取频道信息或加入频道
  • 通过名称、ID或邮箱查找用户

Session Bridge (recommended)

Session Bridge（推荐使用）

  • Connecting any running Claude Code session to Slack
  • Responding to @mentions and DMs with full tool access (this session IS the brain)
  • No extra API costs — messages processed in the current session context
  • Auto-notification of new messages via UserPromptSubmit hook
  • Personality as Claudicle via soul.md instructions (no XML machinery needed)
  • 将任意运行中的Claude Code会话连接到Slack
  • 借助完整工具权限回复@提及和私信（当前会话即为核心处理逻辑）
  • 无额外API费用 — 消息在当前会话上下文中处理
  • 通过UserPromptSubmit钩子自动通知新消息
  • 通过soul.md指令以Claudicle的人设响应（无需XML机制）

Prerequisites

前置条件

All scripts require the 
SLACK_BOT_TOKEN
environment variable (a Bot User OAuth Token starting with 
xoxb-
). Scripts also require 
requests
(
uv pip install --system requests
).
bash
undefined
所有脚本都需要设置
SLACK_BOT_TOKEN
环境变量（以
xoxb-
开头的Bot用户OAuth令牌）。脚本还依赖
requests
库（可通过
uv pip install --system requests
安装）。
bash
undefined

Verify token is set

验证令牌是否已设置

echo $SLACK_BOT_TOKEN
undefined
echo $SLACK_BOT_TOKEN
undefined

First-Time Setup

首次设置

  1. Go to api.slack.com/apps -> Create New App -> From Scratch
  2. Name it "Claude Code" -> select your workspace
  3. OAuth & Permissions -> Bot Token Scopes -> add all: 
    • app_mentions:read
    • channels:history
      , 
      groups:history
      , 
      im:history
      , 
      mpim:history
    • channels:read
      , 
      groups:read
      , 
      im:read
      , 
      im:write
    • chat:write
    • files:write
      , 
      files:read
    • reactions:write
      , 
      reactions:read
    • search:read
    • users:read
      , 
      users:read.email
    • users:write
      (optional — enables green presence dot)
  4. Settings -> Socket Mode -> toggle ON -> generate an App-Level Token:
    • Name: 
      socket-mode
    • Scope: 
      connections:write
    • Copy the 
      xapp-
      token
  5. Event Subscriptions -> toggle ON (no Request URL needed with Socket Mode) -> Subscribe to Bot Events -> add: 
    • app_mention
      — channel @mentions
    • message.im
      — direct messages (required for DMs to work)
    • app_home_opened
      — App Home tab rendering
  6. App Home -> Show Tabs -> enable "Allow users to send Slash commands and messages from the messages tab"
  7. Install to Workspace -> approve permissions -> copy Bot User OAuth Token
  8. Set environment variables (add to shell profile):
    bash
    export SLACK_BOT_TOKEN=xoxb-...   # Bot User OAuth Token
export SLACK_APP_TOKEN=xapp-...   # App-Level Token (Socket Mode)
  9. Invite the bot to channels: 
    /invite @Claude Code
After any scope or event subscription change: reinstall the app (Install App -> Reinstall to Workspace) and restart the listener.
  1. 访问api.slack.com/apps -> 创建新应用 -> 从头开始创建
  2. 命名为“Claude Code” -> 选择你的工作区
  3. OAuth与权限 -> Bot令牌权限 -> 添加以下所有权限： 
    • app_mentions:read
    • channels:history
      , 
      groups:history
      , 
      im:history
      , 
      mpim:history
    • channels:read
      , 
      groups:read
      , 
      im:read
      , 
      im:write
    • chat:write
    • files:write
      , 
      files:read
    • reactions:write
      , 
      reactions:read
    • search:read
    • users:read
      , 
      users:read.email
    • users:write
      （可选 — 启用在线状态绿点）
  4. 设置 -> Socket模式 -> 开启 -> 生成应用级令牌：
    • 名称：
      socket-mode
    • 权限范围：
      connections:write
    • 复制
      xapp-
      开头的令牌
  5. 事件订阅 -> 开启（Socket模式下无需请求URL） -> 订阅Bot事件 -> 添加： 
    • app_mention
      — 频道@提及
    • message.im
      — 私信（私信功能必需）
    • app_home_opened
      — 应用主页标签渲染
  6. 应用主页 -> 显示标签 -> 启用“允许用户从消息标签发送斜杠命令和消息”
  7. 安装到工作区 -> 批准权限 -> 复制Bot用户OAuth令牌
  8. 设置环境变量（添加到Shell配置文件）：
    bash
    export SLACK_BOT_TOKEN=xoxb-...   # Bot用户OAuth令牌
export SLACK_APP_TOKEN=xapp-...   # 应用级令牌（Socket模式）
  9. 邀请机器人加入频道：
    /invite @Claude Code
权限范围或事件订阅变更后：重新安装应用（安装应用 -> 重新安装到工作区）并重启监听器。

Quick Start

快速开始

bash
undefined
bash
undefined

Post a message

发送消息

python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Hello from Claude"
python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Hello from Claude"

Read recent messages

读取近期消息

python3 ~/.claude/skills/slack/scripts/slack_read.py "#general" -n 10
python3 ~/.claude/skills/slack/scripts/slack_read.py "#general" -n 10

Search the workspace

搜索工作区

python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment status"
python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment status"

Connect this session to Slack via Claudicle Session Bridge

通过Claudicle Session Bridge将当前会话连接到Slack

(requires Claudicle installed — see github.com/tdimino/claudicle)

—
cd ~/.claudicle/daemon && python3 slack_listen.py --bg python3 ~/.claude/skills/slack/scripts/slack_check.py

---
#（需安装Claudicle — 详见github.com/tdimino/claudicle） cd ~/.claudicle/daemon && python3 slack_listen.py --bg python3 ~/.claude/skills/slack/scripts/slack_check.py

---

Session Bridge

Session Bridge

Connect any running Claude Code session to Slack. A background listener catches @mentions and DMs -> 
inbox.jsonl
. This session reads the inbox, processes with full tool access, posts responses back. No extra API costs.
Requires Claudicle daemon installed — see github.com/tdimino/claudicle.
bash
undefined
将任意运行中的Claude Code会话连接到Slack。后台监听器捕获@提及和私信 -> 写入
inbox.jsonl
。当前会话读取收件箱，借助完整工具权限处理消息，然后回复消息。无额外API费用。
需安装Claudicle守护进程 — 详见github.com/tdimino/claudicle。
bash
undefined

Connect

连接

cd ~/.claudicle/daemon && python3 slack_listen.py --bg
cd ~/.claudicle/daemon && python3 slack_listen.py --bg

Check messages

检查消息

python3 ~/.claude/skills/slack/scripts/slack_check.py
python3 ~/.claude/skills/slack/scripts/slack_check.py

Respond to thread, remove hourglass, mark handled

回复线程，移除沙漏反应，标记为已处理

python3 ~/.claude/skills/slack/scripts/slack_post.py "C12345" "response" --thread "TS" python3 ~/.claude/skills/slack/scripts/slack_react.py "C12345" "TS" "hourglass_flowing_sand" --remove python3 ~/.claude/skills/slack/scripts/slack_check.py --ack 1
python3 ~/.claude/skills/slack/scripts/slack_post.py "C12345" "response" --thread "TS" python3 ~/.claude/skills/slack/scripts/slack_react.py "C12345" "TS" "hourglass_flowing_sand" --remove python3 ~/.claude/skills/slack/scripts/slack_check.py --ack 1

Disconnect

断开连接

cd ~/.claudicle/daemon && python3 slack_listen.py --stop

**Soul Formatter** (optional): `scripts/slack_format.py` adds Open Souls cognitive step formatting — perception framing, dialogue extraction, monologue logging.

```bash
python3 slack_format.py perception "Tom" "What's the status?"   # -> Tom said, "..."
echo "$raw" | python3 slack_format.py extract                   # -> external dialogue only
echo "$raw" | python3 slack_format.py extract --narrate --log   # -> narrated + logged
python3 slack_format.py instructions                            # -> cognitive step XML format
Automated Respond: 
/slack-respond
processes all pending messages as Claudicle with full cognitive steps — perception, monologue, dialogue, post, ack — in a single invocation. See 
~/.claude/skills/slack-respond/SKILL.md
.
For full installation, architecture, inbox format, auto-notification hook, and troubleshooting, see 
references/session-bridge.md
.
cd ~/.claudicle/daemon && python3 slack_listen.py --stop

**灵魂格式化工具**（可选）：`scripts/slack_format.py`添加Open Souls认知步骤格式化 — 感知框架、对话提取、独白日志。

```bash
python3 slack_format.py perception "Tom" "What's the status?"   # -> Tom said, "..."
echo "$raw" | python3 slack_format.py extract                   # -> 仅提取外部对话
echo "$raw" | python3 slack_format.py extract --narrate --log   # -> 带旁白+日志
python3 slack_format.py instructions                            # -> 认知步骤XML格式
自动回复：
/slack-respond
以Claudicle身份处理所有待处理消息，包含完整认知步骤 — 感知、独白、对话、回复、确认 — 一键执行。详见
~/.claude/skills/slack-respond/SKILL.md
。
完整的安装说明、架构、收件箱格式、自动通知钩子和故障排查，请查看
references/session-bridge.md
。

Script Selection Guide

脚本选择指南

TaskScriptExample
Post a message
slack_post.py
slack_post.py "#general" "Hello"
Reply to a thread
slack_post.py
slack_post.py "#ch" "reply" --thread TS
Schedule a message
slack_post.py
slack_post.py "#ch" "msg" --schedule ISO
Read channel history
slack_read.py
slack_read.py "#general" -n 20
Read thread
slack_read.py
slack_read.py "#ch" --thread TS
Search messages
slack_search.py
slack_search.py "query"
Search files
slack_search.py
slack_search.py "query" --files
Add reaction
slack_react.py
slack_react.py "#ch" TS emoji
Upload file
slack_upload.py
slack_upload.py "#ch" ./file.pdf
Share code snippet
slack_upload.py
slack_upload.py "#ch" --snippet CODE
List channels
slack_channels.py
slack_channels.py
Join channel
slack_channels.py
slack_channels.py --join "#ch"
Find user by email
slack_users.py
slack_users.py --email user@co.com
For full script documentation (all parameters, examples, test suite, common workflows), see 
references/scripts-reference.md
.
任务脚本示例
发送消息
slack_post.py
slack_post.py "#general" "Hello"
回复线程
slack_post.py
slack_post.py "#ch" "reply" --thread TS
定时发送消息
slack_post.py
slack_post.py "#ch" "msg" --schedule ISO
读取频道历史
slack_read.py
slack_read.py "#general" -n 20
读取线程消息
slack_read.py
slack_read.py "#ch" --thread TS
搜索消息
slack_search.py
slack_search.py "query"
搜索文件
slack_search.py
slack_search.py "query" --files
添加反应
slack_react.py
slack_react.py "#ch" TS emoji
上传文件
slack_upload.py
slack_upload.py "#ch" ./file.pdf
分享代码片段
slack_upload.py
slack_upload.py "#ch" --snippet CODE
列出频道
slack_channels.py
slack_channels.py
加入频道
slack_channels.py
slack_channels.py --join "#ch"
通过邮箱查找用户
slack_users.py
slack_users.py --email user@co.com
所有脚本的完整文档（所有参数、示例、测试套件、常见工作流），请查看
references/scripts-reference.md
。

Rate Limit Awareness

速率限制说明

TierRateKey Methods
Tier 11/min
conversations.history
, 
conversations.replies
Tier 220/min
conversations.list
, 
users.list
, 
search.messages
Tier 350/min
reactions.*
, 
conversations.info
, 
chat.update
Tier 4100+/min
files.getUploadURLExternal
, 
files.completeUploadExternal
Special1/sec/channel
chat.postMessage
All scripts handle rate limits automatically via 
_slack_utils.py
(local cooldown + retry with 
Retry-After
). See 
references/rate-limits.md
for full details.
层级速率核心方法
层级11次/分钟
conversations.history
, 
conversations.replies
层级220次/分钟
conversations.list
, 
users.list
, 
search.messages
层级350次/分钟
reactions.*
, 
conversations.info
, 
chat.update
层级4100+次/分钟
files.getUploadURLExternal
, 
files.completeUploadExternal
特殊1次/秒/频道
chat.postMessage
所有脚本通过
_slack_utils.py
自动处理速率限制（本地冷却 + 基于
Retry-After
重试）。完整详情请查看
references/rate-limits.md
。

Troubleshooting

故障排查

ProblemFix
Bot not responding to @mentionsEnable Socket Mode; verify 
SLACK_APP_TOKEN
(xapp-) is exported
"missing_scope" errorAdd the missing scope in OAuth & Permissions -> reinstall app
No search resultsInvite bot to channels with 
/invite @Claude Code
, or use user token (
xoxp-
)
Rate limited (429)Scripts auto-retry; reduce batch sizes
"Sending messages turned off"App Home -> enable "Allow users to send Slash commands and messages from the messages tab"
No green presence dotAdd 
users:write
scope -> reinstall app
App Home tab blankSubscribe to 
app_home_opened
event
For daemon-specific troubleshooting (soul engine, memory, launcher), see Claudicle docs.
问题解决方法
机器人不响应@提及开启Socket模式；验证已导出
SLACK_APP_TOKEN
（xapp-开头）
"missing_scope"错误在OAuth与权限中添加缺失的权限范围 -> 重新安装应用
无搜索结果使用
/invite @Claude Code
邀请机器人加入频道，或使用用户令牌（xoxp-开头）
速率限制（429错误）脚本会自动重试；减小批量处理大小
"Sending messages turned off"应用主页 -> 启用“允许用户从消息标签发送斜杠命令和消息”
无在线状态绿点添加
users:write
权限范围 -> 重新安装应用
应用主页标签空白订阅
app_home_opened
事件
守护进程相关故障排查（灵魂引擎、记忆、启动器），请查看Claudicle文档。

File Structure

文件结构

scripts/
├── slack_check.py       # Session Bridge: read/ack inbox messages
├── slack_inbox_hook.py  # Session Bridge: UserPromptSubmit auto-check hook
├── slack_format.py      # Soul formatter: perception/extract/instructions (Open Souls paradigm)
├── slack_post.py        # Post messages to channels/threads
├── slack_read.py        # Read channel history or threads
├── slack_search.py      # Search messages or files
├── slack_react.py       # Add/remove reactions
├── slack_upload.py      # Upload files or snippets
├── slack_channels.py    # List/join channels
├── slack_users.py       # Look up users
└── _slack_utils.py      # Shared auth, rate limiting, API calls
scripts/
├── slack_check.py       # Session Bridge：读取/确认收件箱消息
├── slack_inbox_hook.py  # Session Bridge：UserPromptSubmit自动检查钩子
├── slack_format.py      # 灵魂格式化工具：感知/提取/指令（Open Souls范式）
├── slack_post.py        # 向频道/线程发送消息
├── slack_read.py        # 读取频道历史或线程消息
├── slack_search.py      # 搜索消息或文件
├── slack_react.py       # 添加/移除反应
├── slack_upload.py      # 上传文件或代码片段
├── slack_channels.py    # 列出/加入频道
├── slack_users.py       # 查询用户信息
└── _slack_utils.py      # 共享认证、速率限制、API调用

Reference Index

参考索引

ReferenceContents
references/session-bridge.md
Session Bridge: installation, architecture, inbox format, usage workflow, soul formatter, troubleshooting
references/unified-launcher-architecture.md
Unified launcher: installation, architecture, per-channel sessions, SDK integration, data flows, threading model
references/daemon-architecture.md
Soul engine cognitive steps, memory tiers, XML format, App Home, Soul Monitor TUI
references/scripts-reference.md
Full documentation for all 7 scripts, test suite, common workflows
references/onboarding-guide.md
User model interview, CLAUDE.md generation, export commands
references/rate-limits.md
Slack API rate limit tiers and handling strategy
参考文档内容
references/session-bridge.md
Session Bridge：安装、架构、收件箱格式、使用工作流、灵魂格式化工具、故障排查
references/unified-launcher-architecture.md
统一启动器：安装、架构、按频道会话、SDK集成、数据流、线程模型
references/daemon-architecture.md
灵魂引擎认知步骤、记忆层级、XML格式、应用主页、Soul Monitor TUI
references/scripts-reference.md
所有7个脚本的完整文档、测试套件、常见工作流
references/onboarding-guide.md
用户模型访谈、CLAUDE.md生成、导出命令
references/rate-limits.md
Slack API速率限制层级与处理策略

Assets

资源文件

  • assets/app-icon.png
    — Slack app icon for bot configuration
  • assets/app-icon.png
    — 用于机器人配置的Slack应用图标