Thiết lập tích hợp Slack

Hướng dẫn này chỉ cho bạn cách kết nối Slack với một không gian làm việc Control Center, hoặc bằng cách để Control Center tạo app, hoặc bằng cách tự bạn dựng lấy.

Để có một lần chạy đầu tiên theo hướng dẫn, xem Nối Slack với không gian làm việc của bạn.

Điều kiện tiên quyết

Vai trò owner hoặc admin trong không gian làm việc Control Center — kết nối một app chat là một thay đổi cài đặt không gian làm việc
Quyền tạo và cài app trong không gian làm việc Slack
Không cần gì truy cập được từ công khai: kết nối là hướng ra (Socket Mode), nên máy chủ không cần cổng vào, tunnel hay tên miền

Ba cách để có app

Cách	Bạn cung cấp	Control Center làm
Theo hướng dẫn	Token cấu hình app (`xoxe-…`)	Tạo app với đúng scope, sự kiện, Socket Mode và lệnh slash; đưa cho bạn hai bước mà Slack không có API cho chúng
Tạo trên Slack	Không gì cả	Mở Slack với cùng cấu hình đã điền sẵn; bạn chọn một không gian làm việc và xác nhận
Làm thủ công	Token của app đã hoàn tất	Xác minh chúng rồi kết nối

Cách theo hướng dẫn là cách duy nhất còn giúp app vẫn quản lý được từ Control Center, và chính điều đó mở ra khả năng Tùy chỉnh chatbot. Một app Tạo trên Slack có thể được nâng thành app được quản lý sau đó bằng cách dán token cấu hình vào hộp thoại kết nối.

Cố ý không có nút “cài app Slack của Control Center”. Cài một app Slack phân tán đòi hỏi một client secret dùng chung (Slack không có PKCE), còn Socket Mode phân phối sự kiện của một app ngẫu nhiên qua các kết nối của nó — nên một app dùng chung sẽ chuyển tin nhắn của không gian làm việc bạn tới máy chủ của người khác. Vì vậy mỗi không gian làm việc sở hữu app riêng của mình, và ba cách trên nói về việc điều đó tốn của bạn ít công sức đến đâu.

Phương án A: để Control Center tạo app

Tạo một cặp token cấu hình app tại api.slack.com/apps và sao chép token làm mới (xoxe-…)
Trong Control Center, vào Cài đặt → Không gian làm việc → Chung và cuộn tới thẻ Cầu nối chat
Trên khối Slack, nhấp vào Tạo app giúp tôi
Dán token, chỉnh tên app, tên bot, các mô tả và lệnh slash, rồi nhấp vào Tạo app
Thực hiện hai bước còn lại mà hộp thoại hiển thị, mỗi bước là một liên kết vào Slack:
- Basic Information → App-Level Tokens: tạo một token với scope connections:write (xapp-…)
- Install App: cài vào không gian làm việc và sao chép Bot User OAuth Token (xoxb-…)
Nhấp vào Dán thông tin xác thực và tiếp tục với Kết nối

Token cấu hình được xoay vòng sau mỗi lần dùng. Control Center lưu giá trị đã xoay ngay khi thực hiện, nên bạn không bao giờ phải dán lại.

Phương án B: tạo trên Slack, với cấu hình điền sẵn

Vẫn là app đó, không cần token cấu hình — Slack mở cho bạn màn hình tạo app của chính nó với toàn bộ manifest đã điền sẵn.

Trong Control Center, vào Cài đặt → Không gian làm việc → Chung và cuộn tới thẻ Cầu nối chat
Trên khối Slack, nhấp vào Tạo app giúp tôi
Chỉnh tên app, tên bot, các mô tả và lệnh slash — những thông tin này đi kèm theo liên kết
Nhấp vào Tạo trên Slack. Trình duyệt của bạn mở trang tạo app của Slack với cấu hình điền sẵn
Chọn không gian làm việc Slack và xác nhận. Các scope, sự kiện, Socket Mode và lệnh slash đều đã đúng
Quay lại Control Center, thực hiện hai bước còn lại mà hộp thoại hiển thị:
- Basic Information → App-Level Tokens: tạo một token với scope connections:write (xapp-…)
- Install App: cài vào không gian làm việc và sao chép Bot User OAuth Token (xoxb-…)
Nhấp vào Dán thông tin xác thực và tiếp tục với Kết nối

Slack không báo nó đã tạo app nào, nên Control Center không biết id của app và các liên kết ở bước 6 dẫn tới danh sách app của bạn thay vì mở thẳng app đó. Tùy chỉnh bot cần token cấu hình.

Phương án C: tự dựng app

Tạo một app tại api.slack.com/apps, rồi thiết lập như sau.

Socket Mode: bật nó và để trống mọi URL yêu cầu. Slack từ chối một manifest yêu cầu cả Socket Mode lẫn phân phối qua webhook.

Scope của token bot (OAuth & Permissions):

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

Đăng ký sự kiện (sự kiện của bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels và message.groups chính là thứ khiến một phản hồi bên trong một luồng Slack đã được nối hoạt động. Không có chúng, chỉ lượt nhắc đầu tiên mới đến được.

Lệnh slash: /cc (tên nào cũng được — cầu nối dùng đúng lệnh mà nó được gọi lần gần nhất).

App Home: bật tab Messages và để nó cho phép ghi, để thành viên có thể nhắn tin riêng cho bot.

Token: tạo một token cấp ứng dụng với connections:write, rồi cài app và sao chép token OAuth của người dùng bot.

Kết nối

Vào Cài đặt → Không gian làm việc → Chung và cuộn tới thẻ Cầu nối chat
Trên khối Slack, nhấp vào Kết nối Slack
Điền vào các trường:

Trường	Giá trị	Nằm ở đâu trong Slack
Token OAuth của người dùng bot	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
Token cấp ứng dụng	`xapp-…`	Basic Information → App-Level Tokens (`connections:write`)
Token làm mới cấu hình app (tùy chọn)	`xoxe-…`	Cặp token cấu hình app trên api.slack.com/apps

Tiền tố của mỗi giá trị đều được kiểm tra ở cả hai phía trước khi gửi bất cứ thứ gì, nên một giá trị bị dán vào sai ô sẽ bị từ chối bằng đúng cùng một câu trong cả hai trường hợp.

Nhấp vào Kết nối

Control Center xác minh token bot bằng auth.test của Slack trước khi lưu bất cứ thứ gì, nên một lỗi gõ sẽ được báo cho bạn thay vì biến thành một socket âm thầm không bao giờ hoạt động. Token cấp ứng dụng chỉ có thể được chứng minh bằng cách mở socket, nên một token hỏng sẽ hiện ra ngay sau đó dưới dạng lỗi kết nối trên cùng dòng.

Nếu không có token làm mới cấu hình app (tùy chọn), kết nối vẫn chạy tốt — bạn chỉ không thể chỉnh bot từ Control Center.

Việc kết nối làm gì

Lưu thông tin xác thực trong thư mục riêng của không gian làm việc, bên cạnh cơ sở dữ liệu của nó, chỉ chủ sở hữu đọc được. Chúng không bao giờ đi ngược về máy khách
Mở một kết nối Socket Mode cho không gian làm việc này và bắt đầu nhận các lượt nhắc, phản hồi trong luồng Slack, DM và lệnh slash
Trang bị lại mọi luồng Slack đã được nối trước đó, nên việc kết nối lại sẽ tiếp tục các cuộc hội thoại đang có thay vì bỏ mặc chúng
Không tốn gì cho những không gian làm việc không có app chat: không socket, không timer, không lưu lượng

Thông tin xác thực của bot là một tệp JSON thuần cho mỗi nhà cung cấp tại <dataDir>/<workspaceId>/chat_credentials/, được ghi theo kiểu nguyên tử và siết quyền chỉ chủ sở hữu. Đó là chủ đích, không phải sơ suất: xóa một không gian làm việc sẽ gỡ liên kết thư mục đó nên token đi theo nó, còn workspace.export và các bản sao lưu chỉ sao chép workspace.db — không sao chép thư mục — nên một không gian làm việc bạn chuyển cho người khác không bao giờ mang theo token bot còn sống bên trong. Hệ quả là khôi phục một không gian làm việc ở nơi khác đồng nghĩa với việc kết nối lại Slack tại đó.

Quyền truy cập cầu nối dựa trên tư cách thành viên của không gian làm việc, không bao giờ dựa trên việc nắm giữ token. Một tài khoản Slack phải được liên kết với người dùng Control Center là thành viên có vai trò ghi. Kết nối, ngắt kết nối, thiết lập theo hướng dẫn, liên kết thiết lập và tùy chỉnh bot đều yêu cầu quyền quản trị viên.

Kiểm tra

Dòng Slack hiển thị một nhãn trạng thái: Trực tiếp, Đang kết nối…, Lỗi kết nối (kèm lỗi của chính Slack ngay bên cạnh), hoặc Chưa kết nối. Để kiểm tra từ đầu đến cuối:

Trong Slack, mời bot vào một kênh: /invite @your-bot-name
Nhắc tới nó kèm một yêu cầu
Một phản hồi trong luồng Slack xuất hiện và một space tương ứng xuất hiện trong Control Center

Sau đó mỗi thành viên muốn dùng cầu nối sẽ liên kết tài khoản của riêng mình — xem Liên kết tài khoản Slack của bạn.

Một phản hồi trông như thế nào trong Slack

Phía trên những từ được truyền theo luồng là một thẻ được nhóm lại, với một dòng cho mỗi bước. Phần thiết lập là một dòng có tiêu đề chuyển từ Working on it… sang Cloning … rồi sang Starting the agent…. Việc suy luận thêm một dòng Thinking…; khi bước đó kết thúc, một suy nghĩ ngắn có thể xuất hiện trên dòng đó. Mỗi công cụ có một dòng riêng (Read lib/main.dart). Câu trả lời đến dưới dạng văn bản thông thường bên dưới thẻ. Thẻ chuyển sang trạng thái hoàn tất khi lượt kết thúc và sang trạng thái lỗi khi lượt chạy thất bại, bị ngắt, hoặc chạm giới hạn lượt.

Thẻ bắt đầu ngay khi bot chấp nhận lượt nhắc — Working on it… — nên luồng Slack không im lặng trong lúc không gian làm việc vẫn đang được dựng. Lượt nhắc đầu tiên của bạn trong một kênh Slack sẽ tạo cuộc hội thoại, và việc đó clone các repo mà agent làm việc trong đó, nên dòng thiết lập lần lượt đọc Cloning acme/widgets…, rồi Setting up Reviewer…, rồi Starting the agent…, rồi một dòng Thinking… ngay khi agent thực sự suy luận. Với một kho mã lớn, lần thiết lập đầu tiên mất khá lâu; thẻ chính là cách bạn biết nó đang làm việc chứ không phải đang phớt lờ bạn. Những lượt nhắc sau trong cùng luồng Slack vẫn mở đầu bằng Working on it…, rồi bỏ qua các bước clone vì không gian làm việc đã có sẵn.

Phần suy luận dưới dạng một bức tường chữ và đầu ra công cụ không bao giờ rời khỏi Control Center — suy nghĩ trên dòng Thinking… là một dòng ngắn, không phải bản ghi hội thoại. View in Control Center trên thẻ mở cuộc hội thoại đầy đủ trong ứng dụng desktop — liên kết trỏ tới máy chủ Control Center của chính bạn, máy chủ này chuyển trình duyệt sang ứng dụng.

Nếu không có gì xảy ra khi bạn nhấp vào, nghĩa là máy chủ đã gửi tin nhắn không truy cập được từ máy bạn đang nhấp (ví dụ một máy chủ chỉ chạy trên loopback bị nhấp từ điện thoại), hoặc Control Center không chạy ở đó. Một máy chủ không có địa chỉ truy cập được sẽ gửi một thẻ không có nút, chứ không gửi một nút dẫn tới hư không.

Xoay vòng token

Dán lại giá trị mới trong hộp thoại kết nối và nhấp vào Kết nối. Việc kết nối sẽ thay thế kết nối đang chạy cho không gian làm việc này, nên socket được quay số lại bằng thông tin xác thực mới.

Hai token bắt buộc phải có mặt trong mọi lần kết nối. Token làm mới cấu hình app (tùy chọn) giữ nguyên giá trị đã lưu khi bạn để trống ô, nên việc xoay vòng token bot không bao giờ làm bạn mất khả năng chỉnh app.

Ngắt kết nối

Nhấp vào Ngắt kết nối trên dòng Slack (chỉ quản trị viên). Socket đóng lại và thông tin xác thực bị quên.

Các liên kết space và người dùng cố ý được giữ lại: kết nối lại cùng một app sẽ khôi phục mọi luồng Slack đã được nối. Chúng là những hàng thuộc phạm vi không gian làm việc, nên xóa không gian làm việc thì chúng cũng bị xóa.

Xử lý sự cố

Dòng đó ghi “Lỗi kết nối”

Đọc lỗi hiển thị bên cạnh nhãn. Một thông tin xác thực bị từ chối (invalid_auth, not_authed, token_revoked, account_inactive) là dứt điểm — cầu nối ngừng thử lại và chờ token mới, vì thử lại mãi một token đã bị thu hồi thì chỉ chuốc lấy giới hạn tần suất. Hãy dán lại các token trong hộp thoại kết nối.

Lỗi missing_scope nghĩa là app được cài với ít scope hơn mức cầu nối cần. Thêm scope còn thiếu, cài lại app trong Slack, rồi kết nối lại.

Mọi trục trặc tạm thời (socket bị rớt, Slack chập chờn) đều tự kết nối lại với backoff lũy thừa giới hạn ở 30 giây, và việc xoay socket định kỳ của Slack không làm tăng backoff đó.

Bot không trả lời một lượt nhắc

Bot đã ở trong kênh chưa? Slack chỉ chuyển tin nhắn kênh tới những app là thành viên. Chạy /invite @your-bot-name
Bạn đã liên kết chưa? Một thành viên chưa liên kết sẽ nhận được phản hồi ngay trong luồng Slack đó giải thích cách liên kết. Xem Liên kết tài khoản Slack của bạn
Bạn có phải thành viên của không gian làm việc với vai trò ghi không? Một viewer hoặc guest sẽ được thông báo rằng vai trò của họ là chỉ đọc. Cầu nối không bao giờ bắt đầu công việc thay cho người mà nó không thể quy kết
Không gian làm việc có agent nào không? Khi không có agent, tin nhắn vẫn được lưu nhưng không có ai trả lời nó

Nó trả lời trong kênh nhưng phớt lờ tin nhắn thường

Đó là chủ đích. Ngoài DM, cầu nối chỉ hành động trên một tin nhắn có nhắc tới bot, hoặc một phản hồi bên trong luồng Slack mà nó đã sở hữu. Mọi thứ khác là cuộc hội thoại của người khác.

Phản hồi đến thành một tin nhắn lớn thay vì được truyền theo luồng

Dòng đó ghi “Luồng trực tiếp đang tắt cho ứng dụng Slack này — phản hồi đến thành một tin nhắn.” Phản hồi theo luồng của Slack cần tính năng Agents & AI Apps trên gói trả phí; khi Slack từ chối, cầu nối ngừng yêu cầu nó trong suốt phần đời còn lại của kết nối đó và đăng nguyên phản hồi thay vào đó. Không mất gì cả — bản ghi hội thoại đầy đủ luôn nằm trong Control Center.

Việc truyền theo luồng cũng cần một điểm neo luồng Slack, nên một phản hồi không có luồng Slack nào để lớn lên sẽ được đăng nguyên vẹn. Thẻ công việc vẫn đến trong cả hai trường hợp: với một phản hồi nguyên vẹn, nó đi kèm cùng tin nhắn đó và đã hoàn tất sẵn.

Phản hồi không có thẻ nào phía trên

Thẻ công việc của Slack thuộc cùng bề mặt Agents & AI Apps mới như việc truyền theo luồng, và Slack chỉ từ chối vào lúc gọi. Khi điều đó xảy ra, Control Center giữ lại phản hồi và bỏ thẻ trong suốt phần đời còn lại của kết nối đó — một câu trả lời không có dòng trạng thái vẫn hơn một dòng trạng thái không có câu trả lời.

“Control Center cần token cấu hình app để chỉnh bot”

Dòng Tùy chỉnh bot bị vô hiệu hóa vì kết nối không có token cấu hình app. Đây là điều dễ hiểu với một app làm thủ công hoặc tạo qua Tạo trên Slack — Slack chưa bao giờ cho Control Center biết đó là app nào. Hãy tạo một cặp token trên api.slack.com/apps và kết nối lại với token làm mới đã được điền.

Một câu trả lời dài bị cắt cụt

Slack giới hạn một tin nhắn ở 40.000 ký tự, nên cầu nối cắt ở 39.000 và nối thêm một con trỏ tới Control Center — một phản hồi bị rút ngắn vẫn hơn một phản hồi bị Slack từ chối thẳng. Toàn bộ văn bản luôn nằm trong bản ghi hội thoại của space.

Hướng dẫn liên quan

Khái niệm liên quan

Cầu chat