cyrus-setup-slack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CRITICAL: Never use
Read
,
Edit
, or
Write
tools on
~/.cyrus/.env
or any file inside
~/.cyrus/
. Use only
Bash
commands (
grep
,
printf >>
, etc.) to interact with env files — secrets must never be read into the conversation context. Never scrape, extract, or read secret values from web pages — guide the user to copy them manually.

重要提示：切勿对
~/.cyrus/.env
或
~/.cyrus/
内的任何文件使用
Read
、
Edit
或
Write
工具。仅使用
Bash
命令（如
grep
、
printf >>
等）与环境文件交互——绝不能将机密信息读取到对话上下文里。切勿从网页抓取、提取或读取机密值——引导用户手动复制。

Setup Slack

Slack设置

Creates a Slack application from a pre-built manifest so Cyrus can respond to messages in Slack channels.

通过预构建的清单创建Slack应用，使Cyrus能够在Slack频道中响应消息。

Step 1: Check Existing Configuration

步骤1：检查现有配置

bash

grep -E '^SLACK_BOT_TOKEN=' ~/.cyrus/.env 2>/dev/null

SLACK_BOT_TOKEN

is already set, inform the user:

Slack is already configured. Skipping this step. To reconfigure, remove
SLACK_BOT_TOKEN
and
SLACK_SIGNING_SECRET
from
~/.cyrus/.env
and re-run.

Skip to completion.

bash

grep -E '^SLACK_BOT_TOKEN=' ~/.cyrus/.env 2>/dev/null

如果已设置

SLACK_BOT_TOKEN

，请告知用户：

Slack已完成配置，跳过此步骤。如需重新配置，请从
~/.cyrus/.env
中移除
SLACK_BOT_TOKEN
和
SLACK_SIGNING_SECRET
后重新运行。

直接跳至完成环节。

Step 2: Read Variables

步骤2：读取变量

Read the base URL (set by

setup-endpoint

bash

grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-

You also need

AGENT_NAME

and

AGENT_DESCRIPTION

— these were collected in Step 0 of the orchestrator and should be available from the conversation context.

读取基础URL（由

setup-endpoint

设置）：

bash

grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-

你还需要

AGENT_NAME

和

AGENT_DESCRIPTION

——这些信息已在编排器的步骤0中收集，可从对话上下文获取。

Step 3: Build Manifest JSON

步骤3：构建清单JSON

Construct the manifest, substituting

<AGENT_NAME>

<AGENT_DESCRIPTION>

, and

<CYRUS_BASE_URL>

with actual values.

IMPORTANT: Use the manifest template EXACTLY as shown below. The event subscription path MUST be

/slack-webhook

(not

/slack/events

or any other path). This matches the route registered by

SlackEventTransport

in the Cyrus codebase.

NOTE: this list of scopes must be kept in sync with the Slack App configuration and the list of scopes defined at https://github.com/cyrusagents/cyrus-hosted/blob/main/apps/app/src/lib/slack/constants.ts. If you change scopes here, propose matching changes there and update any live Slack App configuration that relies on this manifest.

json

{
    "display_information": {
        "name": "<AGENT_NAME>",
        "description": "<AGENT_DESCRIPTION>",
        "background_color": "#00240e"
    },
    "features": {
        "bot_user": {
            "display_name": "<AGENT_NAME>",
            "always_online": true
        }
    },
    "oauth_config": {
        "redirect_urls": [
            "<CYRUS_BASE_URL>/slack/oauth/callback"
        ],
        "scopes": {
            "user": [
                "canvases:read",
                "canvases:write",
                "channels:history",
                "chat:write",
                "groups:history",
                "im:history",
                "mpim:history",
                "users:read",
                "users:read.email",
                "reactions:write",
                "search:read.public",
                "search:read.private",
                "search:read.mpim",
                "search:read.im",
                "search:read.files",
                "search:read.users"
            ],
            "bot": [
                "groups:read",
                "app_mentions:read",
                "assistant:write",
                "canvases:write",
                "channels:history",
                "channels:read",
                "chat:write",
                "chat:write.customize",
                "groups:history",
                "im:history",
                "im:read",
                "files:read",
                "files:write",
                "mpim:history",
                "reactions:write",
                "search:read.files",
                "search:read.public",
                "search:read.users",
                "users:read",
                "users:read.email",
                "mpim:read"
            ]
        },
        "pkce_enabled": false
    },
    "settings": {
        "event_subscriptions": {
            "request_url": "<CYRUS_BASE_URL>/slack-webhook",
            "bot_events": [
                "app_mention",
                "member_joined_channel",
                "message.channels",
                "message.groups",
                "message.mpim",
                "message.im"
            ]
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}

构建清单，将

<AGENT_NAME>

、

<AGENT_DESCRIPTION>

和

<CYRUS_BASE_URL>

替换为实际值。

**重要说明：必须严格使用如下所示的清单模板。**事件订阅路径必须为

/slack-webhook

（不能是

/slack/events

或其他路径），这与Cyrus代码库中

SlackEventTransport

注册的路由一致。

注意：此权限范围列表必须与Slack应用配置以及https://github.com/cyrusagents/cyrus-hosted/blob/main/apps/app/src/lib/slack/constants.ts中定义的权限范围保持同步。如果在此修改权限范围，请同时在上述仓库中提出对应变更，并更新依赖此清单的所有在线Slack应用配置。

json

{
    "display_information": {
        "name": "<AGENT_NAME>",
        "description": "<AGENT_DESCRIPTION>",
        "background_color": "#00240e"
    },
    "features": {
        "bot_user": {
            "display_name": "<AGENT_NAME>",
            "always_online": true
        }
    },
    "oauth_config": {
        "redirect_urls": [
            "<CYRUS_BASE_URL>/slack/oauth/callback"
        ],
        "scopes": {
            "user": [
                "canvases:read",
                "canvases:write",
                "channels:history",
                "chat:write",
                "groups:history",
                "im:history",
                "mpim:history",
                "users:read",
                "users:read.email",
                "reactions:write",
                "search:read.public",
                "search:read.private",
                "search:read.mpim",
                "search:read.im",
                "search:read.files",
                "search:read.users"
            ],
            "bot": [
                "groups:read",
                "app_mentions:read",
                "assistant:write",
                "canvases:write",
                "channels:history",
                "channels:read",
                "chat:write",
                "chat:write.customize",
                "groups:history",
                "im:history",
                "im:read",
                "files:read",
                "files:write",
                "mpim:history",
                "reactions:write",
                "search:read.files",
                "search:read.public",
                "search:read.users",
                "users:read",
                "users:read.email",
                "mpim:read"
            ]
        },
        "pkce_enabled": false
    },
    "settings": {
        "event_subscriptions": {
            "request_url": "<CYRUS_BASE_URL>/slack-webhook",
            "bot_events": [
                "app_mention",
                "member_joined_channel",
                "message.channels",
                "message.groups",
                "message.mpim",
                "message.im"
            ]
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}

Step 4: Create Slack App

步骤4：创建Slack应用

All paths use the "From a manifest" flow. Never create the app "From scratch".

Determine which browser automation mode to use (see orchestrator rules):

If
```
claude-in-chrome
```
MCP tools are available → use Path A-1 (claude-in-chrome)
If
```
agent-browser
```
is installed and a Chrome debug session is connected → use Path A-2 (agent-browser)
Otherwise → use Path B (manual)

所有流程必须使用「从清单创建」方式。绝不能选择「从头创建」。

确定要使用的浏览器自动化模式（参考编排器规则）：

如果
```
claude-in-chrome
```
MCP工具可用 → 使用路径A-1（claude-in-chrome）
如果已安装
```
agent-browser
```
且已连接Chrome调试会话 → 使用路径A-2（agent-browser）
否则 → 使用路径B（手动操作）

Path A-1: claude-in-chrome Automation

路径A-1：claude-in-chrome自动化

Use the

mcp__claude-in-chrome__*

tools to navigate and interact with the user's existing Chrome browser.

Navigate to https://api.slack.com/apps
Click Create New App
Select From a manifest in the modal
Pick the workspace
Click Next
Select JSON tab and paste the manifest from Step 3 (fully substituted with real values)
Click Next, review, click Create

After creation, the app lands on the Basic Information page. Do NOT take screenshots of credential pages. Proceed to Step 5 (credential collection).

使用

mcp__claude-in-chrome__*

工具导航并与用户已打开的Chrome浏览器交互。

导航至https://api.slack.com/apps
点击Create New App
在弹窗中选择From a manifest
选择工作区
点击Next
选择JSON标签页，粘贴步骤3中生成的清单（已替换为真实值）
点击Next，确认信息后点击Create

应用创建完成后，页面会跳转到基本信息页。**切勿对凭据页面截图。**继续执行步骤5（凭据收集）。

Path A-2: agent-browser Automation

路径A-2：agent-browser自动化

agent-browser

is connected to a Chrome debug session:

如果

agent-browser

已连接到Chrome调试会话：

4a. Navigate to Slack app creation

4a. 导航至Slack应用创建页面

bash

agent-browser navigate "https://api.slack.com/apps"

Take a screenshot to verify the page loaded and the user is logged in.

bash

agent-browser navigate "https://api.slack.com/apps"

截图确认页面已加载且用户已登录。

4b. Click "Create New App"

4b. 点击「Create New App」

bash

agent-browser click "button:text('Create New App')"

bash

agent-browser click "button:text('Create New App')"

4c. Select "From a manifest" in the modal

4c. 在弹窗中选择「From a manifest」

bash

agent-browser click "button:text('From a manifest')"

bash

agent-browser click "button:text('From a manifest')"

4d. Select workspace

4d. 选择工作区

Take a screenshot to see the workspace picker. Click the appropriate workspace. If multiple are listed, ask the user which one.

bash

agent-browser click "button:text('Next')"

截图查看工作区选择器，点击对应的工作区。如果列出多个工作区，请询问用户选择哪一个。

bash

agent-browser click "button:text('Next')"

4e. Select JSON format and paste manifest

4e. 选择JSON格式并粘贴清单

Click the JSON tab if not already selected:

bash

agent-browser click "button:text('JSON')"

Paste the manifest using JavaScript:

bash

agent-browser eval "var editor = document.querySelector('textarea, [role=\"textbox\"], .ace_editor textarea, .CodeMirror textarea'); if (editor) { var nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set; nativeInputValueSetter.call(editor, JSON.stringify(<MANIFEST_JSON>, null, 2)); editor.dispatchEvent(new Event('input', { bubbles: true })); 'pasted'; } else { 'editor not found'; }"

If that doesn't work, try:

bash

agent-browser click "textarea"
agent-browser keyboard "Control+a"
agent-browser type '<MANIFEST_JSON_STRING>'

Take a screenshot to verify, then click Next:

bash

agent-browser click "button:text('Next')"

如果未选中JSON标签页，点击切换：

bash

agent-browser click "button:text('JSON')"

使用JavaScript粘贴清单：

bash

agent-browser eval "var editor = document.querySelector('textarea, [role=\"textbox\"], .ace_editor textarea, .CodeMirror textarea'); if (editor) { var nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set; nativeInputValueSetter.call(editor, JSON.stringify(<MANIFEST_JSON>, null, 2)); editor.dispatchEvent(new Event('input', { bubbles: true })); 'pasted'; } else { 'editor not found'; }"

如果上述方法无效，尝试：

bash

agent-browser click "textarea"
agent-browser keyboard "Control+a"
agent-browser type '<MANIFEST_JSON_STRING>'

截图确认粘贴成功，然后点击Next：

bash

agent-browser click "button:text('Next')"

4f. Review and create

4f. 确认并创建

Take a screenshot to verify the summary, then click Create:

bash

agent-browser click "button:text('Create')"

After creation, do NOT screenshot credential pages or attempt to scrape secrets. Proceed to Step 5.

截图确认摘要信息，然后点击Create：

bash

agent-browser click "button:text('Create')"

应用创建完成后，**切勿对凭据页面截图或尝试抓取机密信息。**继续执行步骤5。

Path B: Manual Guided Setup

路径B：手动引导设置

Guide the user through the manifest flow:

Create a Slack App

Go to https://api.slack.com/apps

Click Create New App

In the modal, select From a manifest

Pick the workspace you want to associate the app with

Click Next

Select JSON format and paste the following manifest:

Print the fully-substituted manifest JSON for the user to copy.

Click Next, review the summary, then click Create

Proceed to Step 5.

引导用户完成清单创建流程：

创建Slack应用

访问https://api.slack.com/apps

点击Create New App

在弹窗中选择From a manifest

选择要关联应用的工作区

点击Next

选择JSON格式并粘贴以下清单：

打印已替换真实值的完整清单JSON，供用户复制。

点击Next，确认摘要信息后点击Create

继续执行步骤5。

Step 5: Install App & Collect Credentials

步骤5：安装应用并收集凭据

After the app is created (via any path), guide the user through installation and credential collection. The agent must NOT scrape, read, or extract secrets from the page. The user copies them manually.

应用创建完成后（无论通过哪种路径），引导用户完成安装和凭据收集。代理绝不能抓取、读取或提取页面中的机密信息。需由用户手动复制。

5a. Install to Workspace

5a. 安装到工作区

Tell the user:

In your Slack app settings, go to Install App in the left sidebar

Click Install to Workspace

Click Allow

If using browser automation (A-1 or A-2), the agent can navigate to the Install App page and click the buttons — but must stop after installation completes and not screenshot the resulting page.

告知用户：

在Slack应用设置中，点击左侧边栏的Install App

点击Install to Workspace

点击Allow

如果使用浏览器自动化（路径A-1或A-2），代理可以导航到安装页面并点击按钮，但安装完成后必须停止操作，且不能对结果页面截图。

5b. Add Credential Placeholders

5b. 添加凭据占位符

Add placeholder lines to the env file so the user can fill them in:

bash

grep -q '^SLACK_BOT_TOKEN=' ~/.cyrus/.env || echo 'SLACK_BOT_TOKEN=' >> ~/.cyrus/.env
grep -q '^SLACK_SIGNING_SECRET=' ~/.cyrus/.env || echo 'SLACK_SIGNING_SECRET=' >> ~/.cyrus/.env

在环境文件中添加占位符行，方便用户填写：

bash

grep -q '^SLACK_BOT_TOKEN=' ~/.cyrus/.env || echo 'SLACK_BOT_TOKEN=' >> ~/.cyrus/.env
grep -q '^SLACK_SIGNING_SECRET=' ~/.cyrus/.env || echo 'SLACK_SIGNING_SECRET=' >> ~/.cyrus/.env

5c. Open env file for editing

5c. 打开环境文件进行编辑

bash

undefined

bash

undefined

macOS

code --new-window ~/.cyrus/.env 2>/dev/null || open -a TextEdit ~/.cyrus/.env

Linux

code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env

undefined

code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env

undefined

5d. Guide the user to copy credentials

5d. 引导用户复制凭据

Tell the user:

I've opened
~/.cyrus/.env
. You need to paste two values:
Bot User OAuth Token — go to your app's OAuth & Permissions page, copy the Bot User OAuth Token (starts with
xoxb-
), and paste it after
SLACK_BOT_TOKEN=
Signing Secret — go to your app's Basic Information page, scroll to App Credentials, click Show next to Signing Secret, copy it, and paste it after
SLACK_SIGNING_SECRET=
Save and close the file when done.

告知用户：

我已打开
~/.cyrus/.env
文件，请粘贴以下两个值：
Bot User OAuth Token — 进入应用的OAuth & Permissions页面，复制Bot User OAuth Token（以
xoxb-
开头），粘贴到
SLACK_BOT_TOKEN=
之后
Signing Secret — 进入应用的Basic Information页面，滚动到App Credentials部分，点击Signing Secret旁的Show，复制该值并粘贴到
SLACK_SIGNING_SECRET=
之后
完成后保存并关闭文件。

5e. Wait and verify

5e. 等待并验证

After the user confirms they've saved, verify:

bash

grep -c '^SLACK_BOT_TOKEN=.' ~/.cyrus/.env
grep -c '^SLACK_SIGNING_SECRET=.' ~/.cyrus/.env

Both must return 1 (the

after

ensures the value is not empty). If either is 0, ask the user to check the file.

用户确认保存后，进行验证：

bash

grep -c '^SLACK_BOT_TOKEN=.' ~/.cyrus/.env
grep -c '^SLACK_SIGNING_SECRET=.' ~/.cyrus/.env

两个命令的返回值都必须为1（

后的

确保值不为空）。如果任一返回值为0，请提示用户检查文件。

Completion

完成

✓ Slack app created from manifest and installed ✓ Bot token and signing secret saved to
~/.cyrus/.env

Note: The event subscription

request_url

will fail Slack's verification challenge until Cyrus is actually running. Once Cyrus is started, go to the app's Event Subscriptions page and re-enter the URL to trigger verification, or Slack will retry automatically.

✓ 从清单创建并安装Slack应用 ✓ Bot令牌和签名密钥已保存至
~/.cyrus/.env

注意：在Cyrus实际运行之前，事件订阅的
request_url
无法通过Slack的验证挑战。启动Cyrus后，进入应用的Event Subscriptions页面重新输入URL以触发验证，Slack也会自动重试验证。