/ 快速触发机器人服务的交互方式。开发者可以通过 OpenAPI 为自己的机器人应用注册一组自定义指令，这些指令会以列表形式展示在用户输入 / 后弹出的指令面板中，从而实现更直观、便捷的能力发现与调用。
## 适用场景
Slash Command 适用于以下场景：
高频快捷操作：将应用中最常用、最核心的功能注册为指令，如 /todo 创建任务、/meeting 预定会议，用户无需离开聊天窗口即可完成操作。
信息查询与检索：提供快速的信息查询入口，如 /stock 查询股价、/weather 查询天气，简化信息获取流程。
复杂任务引导：作为复杂工作流的起点，例如 /approval 发起审批，触发后机器人可以发送卡片消息，引导用户完成后续的多步操作。
开发者与运维工具：为开发和运维人员提供便捷的命令行工具，如 /deploy 发布服务、/log 查看日志，将飞书客户端转变为一个轻量级的运维入口。
飞书客户端版本要求：PC 端 7.70 及以上版本，移动端 7.71 及以上版本。
创建并发布应用：你需要在 飞书开放平台 创建一个企业自建应用或商店应用。
启用机器人能力：进入应用详情页，在“应用能力”下添加并启用“机器人”能力。应用需要发布后，机器人才能被用户搜索和使用。
获取 OpenAPI 调用凭证：了解如何获取和使用 tenant_access_token 或 user_access_token，详情参考获取访问凭证。
配置生效延迟：
| 操作 | HTTP 方法 | 接口路径 | 所需权限 (Scope) |
|---|---|---|---|
| 创建指令 | POST | /open-apis/application/v7/app_slash_commands | application:app_slash_command:write |
| 查询指令列表 | GET | /open-apis/application/v7/app_slash_commands | application:app_slash_command:read |
| 更新指令 | PATCH | /open-apis/application/v7/app_slash_commands/:command_id | application:app_slash_command:write |
| 删除指令 | DELETE | /open-apis/application/v7/app_slash_commands/:command_id | application:app_slash_command:write |
curl 命令展示了如何完成一次完整的指令生命周期管理。请将 YOUR_TENANT_ACCESS_TOKEN 替换为你自己的访问凭证。icon_key可选列表参考 「Slash Command Icon Key 说明」章节。
#### 1\. 创建一条指令
指令数量上限：每个应用可创建的 Slash Command 存在数量上限（当前为 100 条）。
创建一个名为 /greet 的指令。
```Bash
curl --location --request POST 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"command": "greet",
"description": {
"default_value": "发送一句问候",
"i18n": {
"en_us": "Send a greeting",
"zh_cn": "发送一句问候"
},
"icon": {
"icon_key": "skill_outlined"
}
}
}'
```
成功响应：
```JSON
{
"code": 0,
"msg": "success",
"data": {
"command_id": "7374693847629398036"
}
}
```
必填字段: command (指令名称，不含 /) 和 description (指令描述)。description 内部必须包含 default_value 作为兜底文案。
可选字段：icon（指令 icon key），icon_key 可选列表参考「Slash Command Icon Key 说明」章节。
记录command_id: 请务必记录成功响应中返回的 command_id，这是后续更新和删除该指令的唯一标识。
command_id 更新指定指令的描述和 icon。
```Bash
curl --location --request PATCH 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands/7374693847629398036' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"description": {
"default_value": "发送一句更加热情的问候",
"i18n": {
"en_us": "Send a more enthusiastic greeting",
"zh_cn": "发送一句更加热情的问候"
},
"icon": {
"icon_key": "skill_outlined"
}
}
}'
```
成功响应：
```JSON
{
"code": 0,
"msg": "success",
"data": {}
}
```
#### 4\. 删除一条指令
使用 command_id 删除指定指令。
```Bash
curl --location --request DELETE 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands/7374693847629398036' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN'
```
成功响应：
```JSON
{
"code": 0,
"msg": "success",
"data": {}
}
```
### 典型错误码
在调用过程中，你可能会遇到以下典型错误，可根据错误码和提示信息进行排查。
| 错误码 | HTTP 状态码 | 含义 | 可能原因及解决方案 |
|---|---|---|---|
| 99991661 | 400 | 缺少 Token | 请求头未携带 Authorization。请检查并添加 Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN。 |
| 99991663 | 400 | Token 无效 | Authorization 中携带的 Token 已过期、被伪造或不属于当前应用。请重新获取有效的访问凭证。 |
| 99992402 | 400 | 参数校验失败 | 请求体中缺少必填字段，如 command 或 description。请根据响应中的 field_violations 提示补充字段。 |
| 9499 | 400 | 请求体格式错误 | 请求体 JSON 结构不合法，或字段类型错误（例如 description.i18n 应为对象而非字符串）。请检查 JSON 格式。 |
| 40000000 | 200 | 业务逻辑错误 | 通常由业务约束导致，如 command already exists (指令重名) 或 command_id not found (指令不存在)。请根据 msg 排查。 |
| 40000031 | 200 | icon_key错误 |
icon_key 必须是「Slash Command Icon Key 说明」章节中的可用 icon_key。 |
访问 飞书开放平台，创建一个新的企业自建应用，或选择一个已有的应用。
在应用详情页的 应用能力 中，确保已添加并启用 机器人 能力。
在 权限管理 页面，搜索并开通 application:app_slash_command:write 和 application:app_slash_command:read 权限。
完成上述配置后，创建并发布一个新的应用版本，使权限和机器人能力生效。
tenant_access_token)。请参考 自建应用获取 tenant_access_token，编写获取和刷新 Token 的逻辑。
第 3 步：注册指令 (Create)
调用 POST /open-apis/application/v7/app_slash_commands 接口，为你希望暴露给用户的每一个功能注册一条指令。
一次性注册：建议在你的服务启动或初始化阶段，将所有需要支持的指令一次性批量注册。
记录 ID：将成功创建后返回的 command_id 与你的业务逻辑（例如功能模块、函数名）进行映射，并持久化存储，以便后续更新或删除。
等待生效：指令注册成功后，由于客户端缓存机制，需要等待约 5 分钟才能在聊天输入框中看到。你可以尝试重启飞书客户端来加速缓存刷新。
验证：在与你的机器人单聊的对话框中，输入 /，查看弹出的指令面板中是否包含你刚刚注册的指令。
程序查询：随时可以调用 GET /open-apis/application/v7/app_slash_commands 接口，从服务端视角查询当前应用已成功注册的所有指令列表，从而核对或同步你的本地指令状态。
客户端缓存与延迟的影响：
创建/更新：新的指令或对现有指令的修改，最长可能需要 注册延迟(5分钟) + 缓存刷新(3分钟) 才能在所有用户端可见。
删除：已删除的指令，可能在用户的指令面板中继续“残留”最多 3 分钟，直到下一次缓存过期并重新拉取。
更新：当你需要修改某个指令的描述（例如，文案优化、功能变更说明）时，使用创建时保存的 command_id 调用 PATCH /open-apis/application/v7/app_slash_commands/:command_id 接口。
删除：当某个功能下线或不再希望通过 Slash Command 暴露时，使用对应的 command_id 调用 DELETE /open-apis/application/v7/app_slash_commands/:command_id 接口。
回滚：如果一次发布后希望撤销某条指令，本质上就是删除操作。
重建：指令的 command 名称在被删除后即可再次使用。如果你误删了一条指令，可以立即使用相同的 command 和 description 重新调用创建接口。服务端会生成一个全新的 command_id，实现“原地重建”。
全量清理：在下线整个应用或重构指令体系时，你可以先通过 GET 接口拉取所有指令的 command_id，然后遍历列表，逐一调用 DELETE 接口，完成所有指令的清理工作。
使用业务前缀：为了避免不同应用或应用内不同模块之间的指令冲突，建议为 command 名称添加有意义的前缀。例如，如果你的应用名为 “订单助手”，可以命名为 order_create、order_query。
动词优先：采用 动词-名词 的格式，如 create-task、search-file，使指令意图更加清晰。
简洁明了：指令名称应简短易记，避免使用过长或复杂的单词。
创建操作的幂等性：POST 创建接口本身不是幂等的，但服务端对 command 名称做了唯一性约束。如果短时间内使用相同的 *command 名称发起多次创建请求，只有第一次会成功（返回 code: 0），后续请求将失败并返回 code: 40000000 及 msg: "command already exists"*。因此，调用方无需在客户端实现复杂的创建防重逻辑，只需判断响应码即可。
更新/删除操作的幂等性：PATCH 和 DELETE 操作在设计上是幂等的。对同一个 command_id 多次执行相同的更新，结果保持一致；对一个已删除的 command_id 多次调用删除，后续请求会返回 command_id not found，但从系统状态来看，结果同样是一致的（指令不存在）。
指令已存在 (command already exists)：当创建指令时收到此错误，表明该指令名已被占用。此时应放弃创建，并可根据业务需要调用 GET 接口获取现有指令的 command_id，转为更新逻辑。
指令 ID 未找到 (command_id not found)：当更新或删除时收到此错误，表明目标指令已被删除或从未存在。此时应停止操作，并检查传入的 command_id 是否正确，或同步本地的指令状态。
鉴权错误 (99991661 / 99991663)：收到这类错误时，应检查 Authorization 请求头和 access_token 的有效性，并触发 Token 刷新机制。
参数校验错误 (99992402 / 9499)：这类错误通常由开发阶段的编码疏漏导致。应根据错误提示检查请求体的字段和结构，确保符合 API 定义。
调用 GET 接口拉取当前全量指令列表。
在本地计算出需要删除的指令 command_id 集合。
遍历该集合，逐一调用 DELETE 接口完成删除。
Content-Type: application/json; charset=utf-8：对于 POST 和 PATCH 请求，这是必须的。
Authorization: Bearer <token>：所有请求必须携带。
icon_key参数的可选列表，默认为skill_outlined。
| icon_key | 图标 |
|---|---|
| skill_outlined | |
| light-ai_outlined | |
| chat-ai_outlined | |
| ai-edit-continue_outlined | |
| education-ai_outlined | |
| ai-trans-switch_outlined | |
| language-ai_outlined | |
| toolbar-more-ai_outlined | |
| image-ai_outlined | |
| ai-agent_outlined | |
| ai-deepthink_outlined | |
| ai-style_outlined | |
| ai-reminder_outlined | |
| ai-block_outlined | |
| ai-simplify-expression_outlined | |
| promptword_outlined | |
| meeting-ai_outlined | |
| ai-improvewriting_outlined | |
| slash-ai_outlined | |
| pa-cost-ai_outlined | |
| update-ai_outlined | |
| diagnosis-ai_outlined | |
| ai-functions_outlined | |
| mic-ai_outlined | |
| search-ai_outlined | |
| explanation-ai_outlined | |
| add-ai_outlined | |
| add-chat-ai_outlined | |
| ai-notification_outlined | |
| dynamic-layout_outlined | |
| ai-doc_outlined | |
| home_outlined | |
| mail_outlined | |
| browser-mac_outlined | |
| flag_outlined | |
| calendar-line_outlined | |
| sent_outlined | |
| gift_outlined | |
| tag_outlined | |
| cloud_outlined | |
| bonus-payroll_outlined | |
| vote_outlined | |
| chat_outlined | |
| emoji_outlined | |
| member_outlined | |
| robot_outlined | |
| mic_outlined | |
| raisehand_outlined | |
| officephone_outlined | |
| effects_outlined | |
| labs_outlined | |
| computer_outlined | |
| clear_outlined | |
| mouse_outlined | |
| cellphone_outlined | |
| cursor_outlined | |
| plugin_outlined | |
| edit_outlined | |
| style-fillcolor_outlined | |
| codeblock_outlined | |
| code_outlined | |
| folder_outlined | |
| file-link-word_outlined | |
| file-link-sheet_outlined | |
| file-link-image_outlined | |
| global-link_outlined | |
| champion_outlined | |
| local_outlined | |
| day_outlined | |
| waiting_outlined | |
| database_outlined | |
| marketplace_outlined | |
404 Not Found？
A1：404 错误通常由以下原因导致：
URL 路径错误：请检查你的请求 URL 是否严格遵循文档格式 /open-apis/application/v7/app_slash_commands (对于列表和创建) 或 /open-apis/application/v7/app_slash_commands/:command_id (对于更新和删除)。特别注意路径是复数形式 commands。
环境不匹配：如果你在测试环境（如 BOE）进行调试，但请求发往了线上环境域名 (open.feishu.cn)，或者未正确携带 x-tt-env 头部，可能导致路由失败。
/ 看不到？
A2：这通常是由于缓存和生效延迟导致的。
服务端延迟：从接口调用成功到配置在所有数据中心同步完成，有分钟级的延迟。
客户端缓存：飞书客户端会对指令列表进行缓存（约 3 分钟）。
排查步骤：
耐心等待：在创建或更新后，至少等待 5 分钟。
重启客户端：完全退出飞书客户端再重新登录，可以强制刷新缓存。
调用 GET 接口确认：调用列表接口，检查你的指令是否已存在于服务端返回的列表中。如果存在，说明服务端已处理成功，问题在于客户端缓存。
code: 99991640, msg: "lacks permission"，这是为什么？
A3：这个错误明确表示你的应用缺少调用该接口所需的权限。
检查权限范围 (Scope)：请前往 飞书开放平台 > 你的应用 > “权限管理”页面。
确认权限：确保 application:app_slash_command:write (用于写操作) 和 application:app_slash_command:read (用于读操作) 已被添加并处于“已开通”状态。
重新发布版本：如果在应用已发布后才添加的权限，你需要创建一个新的应用版本并重新发布，权限才会正式生效。
description.i18n 国际化配置没有生效？
A4：i18n 字段的 key 必须是标准的语言代码，value 为对应语言的描述文本。
i18n 的值是一个严格的 map[string]string 结构，且 key 使用 zh_cn, en_us 等标准代号。
Q5：我可以为一个应用创建多少个 Slash Command？
A5：目前，单个应用最多可以创建 100 条 Slash Command。建议你精选应用的核心功能进行注册，保持指令列表的简洁和高效。如果指令过多，用户反而难以查找和使用。