agent-slackbot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent SlackBot

A TypeScript CLI tool that enables AI agents and humans to interact with Slack workspaces using bot tokens (xoxb-). Unlike agent-slack which extracts user tokens from the desktop app, agent-slackbot uses standard Slack Bot tokens for server-side and CI/CD integrations.

这是一款TypeScript CLI工具，支持AI Agent和人类使用Bot令牌（xoxb-）与Slack工作区进行交互。与从桌面应用提取用户令牌的agent-slack不同，agent-slackbot使用标准的Slack Bot令牌，适用于服务器端和CI/CD集成场景。

Quick Start

快速开始

bash

undefined

bash

undefined

Set your bot token

设置你的Bot令牌

agent-slackbot auth set xoxb-your-bot-token

Or set with a custom bot identifier for multi-bot setups

或者为多Bot配置设置自定义Bot标识符

agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

Verify authentication

验证身份验证状态

agent-slackbot auth status

Send a message

发送消息

agent-slackbot message send C0ACZKTDDC0 "Hello from bot!"

List channels

列出频道

agent-slackbot channel list

undefined

agent-slackbot channel list

undefined

Authentication

身份验证

Bot Token Setup

Bot令牌设置

agent-slackbot uses Slack Bot tokens (xoxb-) which you get from the Slack App configuration:

bash

undefined

agent-slackbot使用从Slack应用配置中获取的Slack Bot令牌（xoxb-）：

bash

undefined

Set bot token (validates against Slack API before saving)

设置Bot令牌（保存前会通过Slack API验证有效性）

agent-slackbot auth set xoxb-your-bot-token

Set with a custom bot identifier

设置带自定义Bot标识符的令牌

agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

Check auth status

检查身份验证状态

agent-slackbot auth status

Clear stored credentials

清除已存储的凭据

agent-slackbot auth clear

undefined

agent-slackbot auth clear

undefined

Multi-Bot Management

多Bot管理

Store multiple bot tokens and switch between them:

bash

undefined

存储多个Bot令牌并在它们之间切换：

bash

undefined

Add multiple bots

添加多个Bot

agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot" agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"

List all stored bots

列出所有已存储的Bot

agent-slackbot auth list

Switch active bot

切换活跃Bot

agent-slackbot auth use deploy

Use a specific bot for one command (without switching)

在单次命令中使用指定Bot（无需切换活跃Bot）

agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert

Remove a stored bot

删除已存储的Bot

agent-slackbot auth remove deploy

Disambiguate bots with same ID across workspaces

区分不同工作区中ID相同的Bot

agent-slackbot auth use T123456/deploy


The `--bot <id>` flag is available on all commands to override the active bot for a single invocation.

agent-slackbot auth use T123456/deploy


所有命令都支持`--bot <id>`参数，用于在单次调用时覆盖当前活跃Bot。

Getting a Bot Token

获取Bot令牌

Go to api.slack.com/apps
Create New App (or select existing)
Go to OAuth & Permissions
Add required bot token scopes (see below)
Install app to workspace
Copy the Bot User OAuth Token (starts with
```
xoxb-
```
)

访问 api.slack.com/apps
创建新应用（或选择现有应用）
进入 OAuth & Permissions（OAuth与权限）页面
添加所需的Bot令牌权限范围（见下文）
将应用安装到工作区
复制 Bot User OAuth Token（Bot用户OAuth令牌，以
```
xoxb-
```
开头）

Required Bot Token Scopes

所需Bot令牌权限范围

Scope	Used For
`chat:write`	Sending messages
`channels:history`	Reading public channel messages
`channels:read`	Listing public channels
`channels:join`	Joining public channels
`groups:history`	Reading private channel messages
`groups:read`	Listing private channels
`users:read`	Listing users
`users:read.email`	Reading user email addresses
`reactions:write`	Adding/removing reactions
`reactions:read`	Listing reactions

权限范围	用途
`chat:write`	发送消息
`channels:history`	读取公开频道消息
`channels:read`	列出公开频道
`channels:join`	加入公开频道
`groups:history`	读取私有频道消息
`groups:read`	列出私有频道
`users:read`	列出用户
`users:read.email`	读取用户邮箱地址
`reactions:write`	添加/移除表情反应
`reactions:read`	列出表情反应

Environment Variables (CI/CD)

环境变量（CI/CD场景）

For CI/CD pipelines, set these environment variables instead of using

auth set

bash

export E2E_SLACKBOT_TOKEN=xoxb-your-bot-token
export E2E_SLACKBOT_WORKSPACE_ID=T123456
export E2E_SLACKBOT_WORKSPACE_NAME="My Workspace"

在CI/CD流水线中，可设置以下环境变量替代

auth set

命令：

bash

export E2E_SLACKBOT_TOKEN=xoxb-your-bot-token
export E2E_SLACKBOT_WORKSPACE_ID=T123456
export E2E_SLACKBOT_WORKSPACE_NAME="My Workspace"

Commands

命令列表

Message Commands

消息相关命令

bash

undefined

bash

undefined

Send a message

发送消息

agent-slackbot message send <channel> <text> agent-slackbot message send C0ACZKTDDC0 "Hello world"

Send a threaded reply

发送线程回复

agent-slackbot message send C0ACZKTDDC0 "Reply" --thread <ts>

List messages

列出消息

agent-slackbot message list <channel> agent-slackbot message list C0ACZKTDDC0 --limit 50

Get a single message by timestamp

通过时间戳获取单条消息

agent-slackbot message get <channel> <ts>

Get thread replies (includes parent message)

获取线程回复（包含父消息）

agent-slackbot message replies <channel> <thread_ts> agent-slackbot message replies C0ACZKTDDC0 1234567890.123456 --limit 50

Update a message (bot's own messages only)

更新消息（仅支持Bot自己发送的消息）

agent-slackbot message update <channel> <ts> <new-text>

Delete a message (bot's own messages only)

删除消息（仅支持Bot自己发送的消息）

agent-slackbot message delete <channel> <ts> --force

undefined

agent-slackbot message delete <channel> <ts> --force

undefined

Channel Commands

频道相关命令

bash

undefined

bash

undefined

List channels the bot can see

列出Bot可见的频道

agent-slackbot channel list agent-slackbot channel list --limit 50

Get channel info

获取频道信息

agent-slackbot channel info <channel> agent-slackbot channel info C0ACZKTDDC0

undefined

agent-slackbot channel info <channel> agent-slackbot channel info C0ACZKTDDC0

undefined

User Commands

用户相关命令

bash

undefined

bash

undefined

List users

列出用户

agent-slackbot user list agent-slackbot user list --limit 50

Get user info

获取用户信息

agent-slackbot user info <user-id>

undefined

agent-slackbot user info <user-id>

undefined

Reaction Commands

表情反应相关命令

bash

undefined

bash

undefined

Add reaction

添加表情反应

agent-slackbot reaction add <channel> <ts> <emoji> agent-slackbot reaction add C0ACZKTDDC0 1234567890.123456 thumbsup

Remove reaction

移除表情反应

agent-slackbot reaction remove <channel> <ts> <emoji>

undefined

agent-slackbot reaction remove <channel> <ts> <emoji>

undefined

Output Format

输出格式

JSON (Default)

JSON格式（默认）

All commands output JSON by default for AI consumption:

json

{
  "ts": "1234567890.123456",
  "channel": "C0ACZKTDDC0",
  "text": "Hello world"
}

所有命令默认输出JSON格式，便于AI处理：

json

{
  "ts": "1234567890.123456",
  "channel": "C0ACZKTDDC0",
  "text": "Hello world"
}

Pretty (Human-Readable)

美化格式（人类可读）

Use

--pretty

flag for formatted output:

bash

agent-slackbot channel list --pretty

使用

--pretty

参数获取格式化输出：

bash

agent-slackbot channel list --pretty

Common Patterns

常见使用模式

See

references/common-patterns.md

for typical AI agent workflows.

请查看

references/common-patterns.md

了解典型AI Agent工作流。

Templates

模板示例

See

templates/

directory for runnable examples:

```
post-message.sh
```
- Send messages with error handling
```
monitor-channel.sh
```
- Monitor channel for new messages
```
workspace-summary.sh
```
- Generate workspace summary

请查看

templates/

目录中的可运行示例：

```
post-message.sh
```
- 带错误处理的消息发送脚本
```
monitor-channel.sh
```
- 频道新消息监控脚本
```
workspace-summary.sh
```
- 工作区摘要生成脚本

Error Handling

错误处理

All commands return consistent error format:

json

{
  "error": "No credentials. Run \"auth set\" first."
}

Common errors:

```
missing_token
```
: No credentials configured
```
invalid_token_type
```
: Token is not a bot token (must start with xoxb-)
```
not_in_channel
```
: Bot needs to join the channel first
```
slack_webapi_rate_limited_error
```
: Hit rate limit (auto-retries with backoff)

所有命令返回一致的错误格式：

json

{
  "error": "No credentials. Run \"auth set\" first."
}

常见错误：

```
missing_token
```
: 未配置凭据
```
invalid_token_type
```
: 令牌不是Bot令牌（必须以xoxb-开头）
```
not_in_channel
```
: Bot需要先加入频道
```
slack_webapi_rate_limited_error
```
: 触发速率限制（会自动重试并退避）

Configuration

配置信息

Credentials stored in:

~/.config/agent-messenger/slackbot-credentials.json

Format:

json

{
  "current": {
    "workspace_id": "T123456",
    "bot_id": "deploy"
  },
  "workspaces": {
    "T123456": {
      "workspace_id": "T123456",
      "workspace_name": "My Workspace",
      "bots": {
        "deploy": {
          "bot_id": "deploy",
          "bot_name": "Deploy Bot",
          "token": "xoxb-..."
        },
        "alert": {
          "bot_id": "alert",
          "bot_name": "Alert Bot",
          "token": "xoxb-..."
        }
      }
    }
  }
}

Security: File permissions set to 0600 (owner read/write only)

凭据存储路径：

~/.config/agent-messenger/slackbot-credentials.json

存储格式：

json

{
  "current": {
    "workspace_id": "T123456",
    "bot_id": "deploy"
  },
  "workspaces": {
    "T123456": {
      "workspace_id": "T123456",
      "workspace_name": "My Workspace",
      "bots": {
        "deploy": {
          "bot_id": "deploy",
          "bot_name": "Deploy Bot",
          "token": "xoxb-..."
        },
        "alert": {
          "bot_id": "alert",
          "bot_name": "Alert Bot",
          "token": "xoxb-..."
        }
      }
    }
  }
}

安全性：文件权限设置为0600（仅所有者可读写）

Key Differences from agent-slack

与agent-slack的核心差异

Feature	agent-slack	agent-slackbot
Token type	User token (xoxc-)	Bot token (xoxb-)
Token source	Auto-extracted from desktop app	Manual from Slack App config
Message search	Yes	No (requires user token)
File operations	Yes	No
Snapshot	Yes	No
Edit/delete messages	Any message	Bot's own messages only
Workspace management	Multi-workspace	Multi-bot, multi-workspace
CI/CD friendly	Requires desktop app	Yes (just set token)

功能	agent-slack	agent-slackbot
令牌类型	用户令牌（xoxc-）	Bot令牌（xoxb-）
令牌来源	从桌面应用自动提取	从Slack应用配置手动获取
消息搜索	支持	不支持（需要用户令牌权限）
文件操作	支持	不支持
工作区快照	支持	不支持
编辑/删除消息	可操作任意消息	仅可操作Bot自身发送的消息
工作区管理	多工作区	多Bot、多工作区
CI/CD友好性	需要依赖桌面应用	支持（仅需设置令牌）

Limitations

限制说明

No real-time events / Socket Mode
No message search (requires user token scope)
No file upload/download
No workspace snapshot
Bot can only edit/delete its own messages
Bot must be invited to private channels
No scheduled messages
Plain text messages only (no blocks/formatting)

不支持实时事件/Socket模式
不支持消息搜索（需要用户令牌权限范围）
不支持文件上传/下载
不支持工作区快照
Bot仅能编辑/删除自身发送的消息
Bot必须被邀请才能进入私有频道
不支持定时消息
仅支持纯文本消息（不支持块/格式化内容）

Troubleshooting

故障排查

agent-slackbot: command not found

agent-slackbot: command not found

The

agent-messenger

package is not installed. Run it directly using a package runner. Ask the user which one to use:

bash

npx -p agent-messenger agent-slackbot ...
bunx -p agent-messenger agent-slackbot ...
pnpm dlx --package agent-messenger agent-slackbot ...

If you already know the user's preferred package runner, use it directly instead of asking.

未安装

agent-messenger

包。可通过包运行器直接调用。询问用户偏好的包运行器后使用对应命令：

bash

npx -p agent-messenger agent-slackbot ...
bunx -p agent-messenger agent-slackbot ...
pnpm dlx --package agent-messenger agent-slackbot ...

若已知用户偏好的包运行器，可直接使用对应命令无需询问。

References

参考文档

Authentication Guide
Common Patterns

身份验证指南
常见使用模式