實戰手冊 · Field Manual 2026 夏季號

github.com/stablyai/agent-slack · 451 ★

Slack Automation / Agent Tooling

把 Slack,
交給 Agent
處理

agent-slack 是 stablyai 維護的 Slack automation CLI for AI agents,以 TypeScript 與 Bun 實作。它讓 agent 讀取 Slack 訊息、瀏覽 thread、搜尋訊息與檔案、下載附件、草擬訊息、執行明確授權的寫入動作,並提供可安裝到 Claude Code、Codex、Cursor 等環境的 agent skill。

451

GitHub Stars

v0.9.3

Latest Release

22.5+

Node Engine

MIT

License

工具定位

AI agent 的
Slack 操作入口

agent-slack 是一個 Slack CLI,目標讀者是 AI agent 與使用 agent 的工程團隊。README 將它定義為 TypeScript + Bun 寫成的 Slack automation CLI,並列出讀取訊息、瀏覽頻道歷史、搜尋訊息與檔案、下載附件、寫入訊息、管理 channel、讀取 Canvas 等能力。

工具的預設介面是 agent-slack ...。repo 同時提供 skills/agent-slack/,可安裝到 Claude Code、Codex、Cursor 等支援 agent skill 的環境,讓 agent 直接載入命令地圖、target 規則與輸出格式。

輸出固定為 JSON,空值會被修剪,附件會下載成 agent 可讀的本機路徑。這讓 agent 可以先讀取 Slack context,再用 message draft 建立人工可確認的回覆。

agent-slack · 基本工作流

Auth→ Read→ Search→ Draft→ Explicit Action→ JSON Output

Slack automation CLI for AI agents

— stablyai/agent-slack README

CLI 與 Skill

二段式安裝
CLI 與 agent skill

先安裝 agent-slack CLI,再把 skills/agent-slack/ 安裝到你的 agent 環境。README 提供 Bun 安裝、npm global install 與 Nix flake 三種 CLI 入口;package metadata 標示 Node engine 為 >=22.5。

# Bun installer, README recommended path
curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/main/install.sh | sh

# npm global install, Node >= 22.5
npm i -g agent-slack

# Nix flake
nix run github:stablyai/agent-slack
      

Agent skill 安裝

repo 內建的 skill 是 agent 使用說明書。使用 skills.sh 安裝時,命令會指向 GitHub repo;手動安裝時,從 clone 後的 repo 執行腳本。

# Recommended by README
npx skills add stablyai/agent-slack

# Manual installation from a local clone
bash ./scripts/install-skill.sh
      

驗證 Slack credentials

macOS 與 Windows 預設讀取 Slack Desktop local data。失敗時,macOS 可改用 Brave、Chrome 或 Firefox 匯入;也可設定 Slack token 與 cookie 環境變數。

agent-slack auth whoami
agent-slack auth import-desktop
agent-slack auth import-brave
agent-slack auth import-chrome
agent-slack auth import-firefox
agent-slack auth test

# Alternative browser token path
export SLACK_TOKEN="xoxc-..."
export SLACK_COOKIE_D="xoxd-..."
agent-slack auth test

# Standard Slack token path
export SLACK_TOKEN="xoxb-..."
agent-slack auth test
      

瀏覽器匯入限制。import-brave 與 import-chrome 透過 AppleScript 從已登入的 Slack tab 讀取 token。README 指出兩個瀏覽器預設關閉 Allow JavaScript from Apple Events;執行前到 View → Developer 啟用。

Command Map

Slack 操作的
命令地圖

README 的 high-level command map 將 Slack 工作分成 auth、message、channel、user、search、workflow、canvas 等群組。skill 版本再補上 safety 規則:讀取與搜尋可自由執行;送出、編輯、刪除、反應、邀請、建立 channel、mark read、排程、上傳與取消排程都需要明確指示。

Auth · 01

auth whoami / test / import-*

Credential 驗證

列出已設定 workspace 與 token source,測試 Slack credentials,或從 Slack Desktop 與瀏覽器匯入 credentials。

Read · 02

message get <target>

單則訊息

讀取一則 Slack message。threaded message 會回傳 thread metadata,不會直接展開完整 thread 內容。

Read · 03

message list <target>

Thread 與歷史

指定 thread 時列出完整 replies;未指定 thread 時瀏覽近期 channel messages,支援 reaction 與時間區間篩選。

Draft · 04

message draft <target> [text]

人工確認的草稿

開啟 Slack-like browser editor,支援粗體、斜體、刪除線、連結、清單、引用、inline code 與 code block。

Write · 05

message send / edit / delete / react

明確授權的寫入

送出、回覆、編輯、刪除與 reaction。message send 支援附件、Block Kit、thread broadcast 與排程。

Schedule · 06

message scheduled list / cancel

排程佇列

列出 Slack server-side scheduled message queue,並可在訊息送出前取消指定 scheduled message。

Search · 07

search all / messages / files

訊息與檔案搜尋

搜尋 Slack messages 與 files,支援 workspace、channel、user、日期、content type、limit 與 content length 控制。

Artifacts · 08

message files[] / search files

附件下載

訊息與搜尋結果中的 snippets、images、attachments 會下載成本機檔案,並在 JSON 中回傳絕對路徑。

Channels · 09

channel list / new / invite / mark

Channel 管理

列出 conversations、建立公開或私有 channel、邀請內部或 Slack Connect 使用者,並可 mark channel / DM as read。

Users · 10

user list / get / dm-open

成員與DM

列出 users、以 id 或 handle 查詢單一使用者,並為一到多位使用者開啟 DM 或 group DM channel id。

Workflow · 11

workflow list / preview / get / run

Slack workflow 觸發

列出 channel 內 bookmarked 或 featured workflows,預覽 trigger metadata,讀取 workflow definition,或執行 trigger。

Inbox · 12

unreads / later / canvas get

收件匣與文件

讀取 unreads、管理 Slack Later saved messages,並將 Slack Canvas 取回為 Markdown。

任務與命令對照

任務	建議命令	輸出或結果
讀一則 Slack permalink	`agent-slack message get "SLACK_URL"`	單則 message 與 thread summary
讀完整 thread	`agent-slack message list "SLACK_URL"`	`messages[]` JSON array
瀏覽近期 channel history	`agent-slack message list "general" --limit 20`	近期 messages 與 optional cursor
準備可審查回覆	`agent-slack message draft "SLACK_URL" "text"`	Browser editor 與 Slack permalink
搜尋歷史訊息與檔案	`agent-slack search all "query" --channel "general"`	`messages[]` 與 `files[]`
取回 Slack Canvas	`agent-slack canvas get "CANVAS_URL"`	Markdown content

Official Rules

讀取、草稿與
明確執行

以下規則來自 README 與 bundled references,不是社群經驗整理。它們定義 agent 使用 Slack 時的 target 選擇、payload 控制、寫入邊界與多 workspace 行為。

TIP 01

優先使用 Slack message URL

message get、message list、message send、message edit、message delete、reaction 與 mark read 都接受 Slack permalink。URL target 可攜帶 workspace、channel 與 timestamp context。

來源 · references/targets.md

TIP 02

Channel name 需要 workspace selector

多個 workspace 已設定時,channel name 會產生歧義。使用 --workspace "https://myteam.slack.com"、唯一 substring,或設定 SLACK_WORKSPACE_URL;channel ID 不需要這個參數。

來源 · references/targets.md

TIP 03

`message get` 與 `message list` 的分工

message get 回傳單則 message 與 thread summary。需要完整 thread conversation 時,改用 message list;需要近期 channel history 時,對 channel target 執行 message list。

來源 · README

TIP 04

搜尋優先指定 channel

README 的 search tips 建議加上 --channel。Channel-scoped search 會掃描 history/files 並在本機過濾,可降低跨 workspace 或全域搜尋的模糊性。

來源 · README

TIP 05

限制 body 與 search payload

message get/list 支援 --max-body-chars。Search commands 支援 --max-content-chars 與 --limit,可在 agent context budget 內保留可讀輸出。

來源 · references/commands.md

TIP 06

附件輸出是本機路徑

Message 與 search 結果中的附件會下載到 agent-friendly temp directory。macOS default root 是 ~/.agent-slack/tmp/downloads/;設定 XDG_RUNTIME_DIR 時會改到該 runtime directory 底下。

來源 · README / references/output.md

TIP 07

寫入前使用 `message draft`

Bundled skill 明確要求讀取與搜尋可自由執行,寫入類動作需明確指示。非簡單回覆先用 message draft,讓人類在 browser editor 檢查 formatting 與內容。

來源 · skills/agent-slack/SKILL.md

TIP 08

Workflow run 之前先 preview

workflow preview 讀取 trigger metadata 且無副作用。需要表單欄位與 steps 時用 workflow get;執行 trigger 時才用 workflow run。

來源 · README / references/commands.md

Worked Example

Incident thread 的
讀取與草稿

此例使用 repo 文件中的真實命令語法,但不假設任何 workspace 內資料。流程只執行讀取、搜尋與草稿,符合 bundled skill 對 side effect 的預設邊界。

agent-slack · incident thread · read and draft

You › 請讀這個 Slack incident thread,找出誰在處理 rollback,再幫我草擬一段狀態回覆。

Agent › 先確認 credentials 與 workspace。

$ agent-slack auth whoami { "workspaces": [{ "workspace_url": "https://workspace.slack.com", "source": "slack_desktop" }] }

Agent › 先讀 root message。若 thread summary 顯示有 replies,再展開完整 thread。

$ agent-slack message get "https://workspace.slack.com/archives/C123/p1770165109628379" --include-reactions --resolve-users { "message": { "ts": "...", "text": "...", "user": "U123" }, "thread": { "ts": "...", "length": 6 } }

$ agent-slack message list "https://workspace.slack.com/archives/C123/p1770165109628379" --max-body-chars 1200 --resolve-users { "messages": [{ "ts": "...", "text": "..." }, { "ts": "...", "text": "..." }] }

Agent › 用 channel-scoped search 查相關 rollback 訊息與附件。

$ agent-slack search all "deploy rollback" --channel "#alerts-staging" --after 2026-01-01 --limit 5 { "messages": [{ "ts": "...", "text": "..." }], "files": [{ "name": "report.md", "path": "/Users/.../.agent-slack/tmp/downloads/report.md" }] }

Agent › 可確認狀態:rollback owner 是 thread 中被指派的 on-call,附件包含最新 smoke test 摘要。現在開草稿,不直接送出。

$ agent-slack message draft "https://workspace.slack.com/archives/C123/p1770165109628379" "我讀完 thread 與最新附件。Rollback 目前由 on-call 接手,下一步是補 smoke test 結果與預估完成時間。" { "draft": "opened", "target": "thread reply" }

No send/edit/delete/reaction action was executed.

Prefer message draft.

— skills/agent-slack/SKILL.md

檢查點

通過狀態:credentials 已確認,thread 已讀取,相關 channel search 已執行,附件路徑已回傳,reply draft 已在 browser editor 開啟。未通過狀態:agent 在未取得明確指示時執行 message send、message edit、message delete 或 reaction。

這個模式適合 incident triage、每日 standup 摘要、客戶支援 thread 分析與 release channel 狀態更新。需要送出時,把草稿內容與 target 展示給使用者確認,再執行寫入命令。

限制與邊界

Slack automation 的
操作邊界

寫入類命令需要明確指示。Bundled skill 將 send、edit、delete、react、invite、create channels、mark read、schedule、upload、cancel scheduled messages 列為需要使用者明確要求的動作。
Credentials 屬於敏感資料。SLACK_TOKEN、SLACK_COOKIE_D、Slack browser token 與匯入流程輸出不得貼進公開 log、issue、報告或 prompt history。
Chrome 與 Brave 匯入依賴 Apple Events 設定。README 指出這兩個瀏覽器預設關閉 Allow JavaScript from Apple Events,且 macOS 第一次執行時會要求輸入密碼。
Channel name 在多 workspace 下會歧義。使用 channel name 時傳入 --workspace 或設定 SLACK_WORKSPACE_URL;channel ID target 不需要 workspace selector。
排程訊息受 Slack 限制。--schedule 的時間必須在未來,且需落在 Slack 120-day scheduled-send limit 內。--schedule 與 --schedule-in 互斥。
Block Kit 與附件上傳不可混用。--blocks 可送 raw Block Kit JSON,但 README 標示不能與 --attach 同時使用。
Thread broadcast 有 target 限制。--reply-broadcast 只適用 thread reply,DM target 不支援,且不能與 --attach 同時使用。
Channel list 是分頁結果。channel list 回傳單頁與 optional next_cursor;需要下一頁時傳入 --cursor。--all 與 --user 互斥。
Slack Connect 邀請需要 workspace 權限。--external 對應 Slack Connect external invite,README 標示需要對應 permissions/scopes,且 email targets 才適用。
Unreads 可能受 Enterprise Grid 限制。README 標示 unreads 使用 client.counts API,部分 Enterprise Grid workspace 可能回傳 team_is_restricted。

進階路徑

從 skill 到
工作流整合

agent-slack 的長期價值在於可被 agent 重複執行的 Slack runbook。CLI 提供穩定命令,skill 提供安全邊界,reference files 提供 target 與輸出規格。

進階玩法地圖

1. 建立 credentials 檢查步驟。Runbook 的第一步固定執行 agent-slack auth whoami 與 agent-slack auth test,並確認 workspace selector。

2. 安裝 bundled skill。使用 npx skills add stablyai/agent-slack,讓 agent 讀取 safety、target、output 與 command references。

3. 固定 target 規則。工作流優先收 Slack permalink;只有在缺少 URL 時才使用 channel name 或 channel ID。多 workspace 下強制傳入 --workspace。

4. 將寫入改為草稿優先。Incident update、standup、客戶支援、release announcement 都先走 message draft;只有明確授權後才送出。

5. 為 payload 設定預設上限。在 runbook 中固定 --limit、--max-body-chars 與 --max-content-chars,避免 agent context 被 channel history 填滿。

6. 本機開發與驗證。CONTRIBUTING.md 指定 bun install、bun run dev -- --help、bun run build、bun run test、bun run typecheck 與 bun run lint。

最該讀的三份延伸閱讀

① README.md:安裝、auth、命令地圖與使用範例。
② skills/agent-slack/SKILL.md:agent safety、常用命令與 reference 入口。
③ references/commands.md、targets.md、output.md:命令、target 與 JSON shape。
④ CONTRIBUTING.md:本機開發、build、test、typecheck 與 release flow。

CLI on $PATH: agent-slack ...