# 选择接入方式

根据使用场景选择机器人、网页嵌入或 API 等接入方式。

数据智能体可以通过网页、飞书、Slack、嵌入页面或 API 使用。接入方式决定访问入口和身份认证方式；数据访问权限由智能体、角色和策略共同控制。

![AskTable 接入方式地图：飞书机器人、嵌入地址、CLI、MCP、OpenAPI、扣子与定时分析报告](https://docs.asktable.com/img/diagrams/integration-map.svg)

各入口复用同一份项目、角色和数据策略；下图以飞书频道为例，Slack 的配置见对应专题。

## 开始前

- 权限：配置接入方式需要项目负责人或项目管理员权限；项目成员可以使用已开放的功能。具体数据范围仍由角色与策略控制。
- 前置：先建好一个数据智能体并给它挂上数据源。走 左侧主导航 → 「更多」（直接落到「智能体」页） → 右上角「创建」。
- 凭证：需要写代码的入口（CLI、MCP、OpenAPI、扣子）都用项目「API-Key」。新建走 左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」，在弹窗的类型里选 `asker`（只问数）或 `admin`（要管资源）。
- 私有部署：飞书和 Slack 频道要额外跑一个 `asktable-feishu-gateway` 容器，主 compose 里没有它，见[部署消息网关](https://docs.asktable.com/deploy/feishu-gateway)。

## 操作步骤

**先定调用方是谁**

三个选项，对应三套身份模型：

- 内部成员：网页对话使用 AskTable 登录身份；飞书和 Slack 频道使用各平台的人员身份与频道授权。
- 外部匿名访客：用一条嵌入地址，不登录，数据范围固定在一个角色里。
- 自动化服务：用项目 API-Key（CLI、MCP、OpenAPI、扣子插件）。

**按调用方挑入口**

| 你要解决的问题                                | 用哪个入口                                                              | 用户要登录 AskTable 吗 | 界面位置                      |
| -------------------------------------- | ------------------------------------------------------------------ | ---------------- | ------------------------- |
| 在网页里探索数据、追问、看结果                        | [对话](https://docs.asktable.com/conversation)                       | 是                | 左侧主导航 → 「新对话」             |
| 让同事在飞书私聊或群里 `@` 机器人提问                  | [飞书机器人](https://docs.asktable.com/integrations/feishu)             | 否                | 打开智能体 → 标签「频道」            |
| 让同事在 Slack 中向机器人提问                     | [Slack 机器人](https://docs.asktable.com/integrations/slack)          | 否                | 打开智能体 → 标签「频道」→ 平台选 Slack |
| 在自己网站或门户里放一个匿名问数窗口                     | [网页嵌入](https://docs.asktable.com/integrations/embed)               | 否                | 打开智能体 → 标签「嵌入」            |
| 按点自动跑分析、把结论推到飞书群或邮箱                    | [定时分析报告](https://docs.asktable.com/integrations/scheduled-reports) | 否（收件人）           | 打开智能体 → 标签「定时任务」          |
| 在终端或流水线里批量维护资源和发起问数                    | [命令行工具](https://docs.asktable.com/integrations/cli)                | 用 API-Key        | 终端执行 `asktable`           |
| 让 Claude 等支持 MCP 的 AI 客户端直接调用 AskTable | [MCP](https://docs.asktable.com/integrations/mcp)                  | 用 API-Key        | 客户端配置                     |
| 把问数接进业务系统，自己处理返回值                      | [OpenAPI](https://docs.asktable.com/integrations/openapi)          | 用 API-Key        | 服务端调用 `/v1`               |
| 让扣子机器人用一句话查数据                          | [接入扣子 Coze](https://docs.asktable.com/integrations/coze)           | 用 API-Key        | 扣子插件配置                    |
| 员工从企业微信工作台登录                           | [企业微信](https://docs.asktable.com/integrations/wecom)               | 是（企业身份）          | 管理员配置                     |
| 员工从 WPS 工作台登录                          | [WPS 协作](https://docs.asktable.com/integrations/wps)               | 是（企业身份）          | 管理员配置                     |

「对话」和「定时任务」都由同一个智能体回答，区别在谁发起：对话是人问一次答一次，定时任务到点自己跑一次并把结论推出去。

**准备身份和凭证**

- 飞书频道要飞书开放平台的自建应用 App ID、App Secret；Slack 要 App-Level Token 和 Bot Token。
- 一个智能体同时只启用一个频道平台。切换平台或选择「不启用」会保留已有凭证与配置，便于重新启用。
- 嵌入地址要在 AskTable 里选一个固定角色，角色带必填变量时一并填好。
- API-Key 只在创建时完整显示一次，之后列表里只留掩码。把它交给脚本或服务端的密钥管理，不要写进浏览器代码、iframe 页面或代码仓库。

**按对应页面完成配置**

上表最后两列给出入口位置，每个入口的字段、默认值和验收步骤在各自的页面里。需要管资源的操作（建数据源、改权限、删智能体）用 `admin` Key；只发起问数用 `asker` Key 就够。

**用最小范围先验证一次**

在测试项目里跑通一次成功调用，再故意用错 Key 和无权限的数据范围各跑一次，确认能看到明确的错误码或界面提示。这样上线后排查有对照。

## 关键约束

| 项目            | 值或默认                                              | 在哪里改                                                       |
| ------------- | ------------------------------------------------- | ---------------------------------------------------------- |
| 项目 API-Key 数量 | 每个项目最多 10 个                                       | 左侧主导航 → 「设置」 → 「API-Key」                                   |
| API-Key 类型    | `admin` 管该项目全部资源；`asker` 只问数                      | 「创建 API-KEY」弹窗的类型                                          |
| API 根路径       | `/v1`                                             | 无界面开关；接口文档在 `<你的站点>/v1/redoc`                              |
| MCP 服务地址      | 云端 `https://mcp.asktable.com/`；私有部署 `<你的站点>/mcp/` | 底部头像 → 「文档」 → 「MCP 服务」                                     |
| 嵌入地址的启用状态     | 新建即启用                                             | 「智能体」→「嵌入」列表项右侧开关                                          |
| 频道平台          | 默认不启用；选择飞书或 Slack，首次配置需保存凭证后才启用                   | 「智能体」→「频道」→「平台」                                            |
| 定时任务          | 新建后是已停用                                           | 「智能体」→「定时任务」→ 表单里的启用开关                                     |
| 消息网关容器        | 私有部署需单独加，SaaS 不需要                                 | 见[部署消息网关](https://docs.asktable.com/deploy/feishu-gateway) |

## 出问题怎么判断

| 现象                 | 判定条件                                                      | 处理                                                                                                                 |
| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 写代码的入口一律失败         | 响应体 `code` 是 `AUTH_ERROR`（HTTP 401）                       | 换一个项目 API-Key；确认请求头是 `Authorization: Bearer <API-Key>`                                                             |
| 接口返回 HTTP 403      | 响应体 `code` 是 `PERMISSION_DENIED`                          | 这个 Key 类型或项目角色不够；管理类操作换成 `admin` Key                                                                               |
| 请求参数被拒             | 响应体 `code` 是 `VALIDATION_ERROR`（HTTP 422），`message` 里带字段名 | 按 `message` 指出的字段补齐或改正参数                                                                                           |
| 飞书或 Slack 机器人没有回复  | 检查当前平台连接状态，再看最近消息的处理状态和回复投递状态；已连接不代表每条消息都成功               | 见[飞书机器人](https://docs.asktable.com/integrations/feishu)或 [Slack](https://docs.asktable.com/integrations/slack)的排查表 |
| iframe 打开是空白或提示不可用 | 嵌入地址列表项显示为已禁用，或访客页提示该嵌入暂不可用                               | 见[网页嵌入](https://docs.asktable.com/integrations/embed)                                                              |
| 定时报告到点没收到          | 「定时任务」的下次触发时间不对，或最近一次运行状态是执行失败、通知失败                       | 见[定时分析报告](https://docs.asktable.com/integrations/scheduled-reports)                                                |

## 下一步

- 先把智能体建起来，再选入口：[创建并配置数据智能体](https://docs.asktable.com/agent/overview)
- 用「人员」「角色」「策略」把数据范围定下来：[权限与数据安全](https://docs.asktable.com/permissions)
- 私有部署要单独跑飞书网关或 MCP 容器：[私有部署（Docker）](https://docs.asktable.com/deploy/docker)