配置与管理
选择接入方式
根据使用场景选择机器人、网页嵌入或 API 等接入方式。
数据智能体可以通过网页、飞书、Slack、嵌入页面或 API 使用。接入方式决定访问入口和身份认证方式；数据访问权限由智能体、角色和策略共同控制。
开始前
- 权限：配置接入方式需要项目负责人或项目管理员权限；项目成员可以使用已开放的功能。具体数据范围仍由角色与策略控制。
- 前置：先建好一个数据智能体并给它挂上数据源。走 左侧主导航 → 「更多」（直接落到「智能体」页） → 右上角「创建」。
- 凭证：需要写代码的入口（CLI、MCP、OpenAPI、扣子）都用项目「API-Key」。新建走 左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」，在弹窗的类型里选
asker（只问数）或admin（要管资源）。 - 私有部署：飞书和 Slack 频道要额外跑一个
asktable-feishu-gateway容器，主 compose 里没有它，见部署消息网关。
操作步骤
先定调用方是谁
三个选项，对应三套身份模型：
- 内部成员：网页对话使用 AskTable 登录身份；飞书和 Slack 频道使用各平台的人员身份与频道授权。
- 外部匿名访客：用一条嵌入地址，不登录，数据范围固定在一个角色里。
- 自动化服务：用项目 API-Key（CLI、MCP、OpenAPI、扣子插件）。
按调用方挑入口
| 你要解决的问题 | 用哪个入口 | 用户要登录 AskTable 吗 | 界面位置 |
|---|---|---|---|
| 在网页里探索数据、追问、看结果 | 对话 | 是 | 左侧主导航 → 「新对话」 |
让同事在飞书私聊或群里 @ 机器人提问 | 飞书机器人 | 否 | 打开智能体 → 标签「频道」 |
| 让同事在 Slack 中向机器人提问 | Slack 机器人 | 否 | 打开智能体 → 标签「频道」→ 平台选 Slack |
| 在自己网站或门户里放一个匿名问数窗口 | 网页嵌入 | 否 | 打开智能体 → 标签「嵌入」 |
| 按点自动跑分析、把结论推到飞书群或邮箱 | 定时分析报告 | 否（收件人） | 打开智能体 → 标签「定时任务」 |
| 在终端或流水线里批量维护资源和发起问数 | 命令行工具 | 用 API-Key | 终端执行 asktable |
| 让 Claude 等支持 MCP 的 AI 客户端直接调用 AskTable | MCP | 用 API-Key | 客户端配置 |
| 把问数接进业务系统，自己处理返回值 | OpenAPI | 用 API-Key | 服务端调用 /v1 |
| 让扣子机器人用一句话查数据 | 接入扣子 Coze | 用 API-Key | 扣子插件配置 |
| 员工从企业微信工作台登录 | 企业微信 | 是（企业身份） | 管理员配置 |
| 员工从 WPS 工作台登录 | 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 不需要 | 见部署消息网关 |
出问题怎么判断
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 写代码的入口一律失败 | 响应体 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 机器人没有回复 | 检查当前平台连接状态，再看最近消息的处理状态和回复投递状态；已连接不代表每条消息都成功 | 见飞书机器人或 Slack的排查表 |
| iframe 打开是空白或提示不可用 | 嵌入地址列表项显示为已禁用，或访客页提示该嵌入暂不可用 | 见网页嵌入 |
| 定时报告到点没收到 | 「定时任务」的下次触发时间不对，或最近一次运行状态是执行失败、通知失败 | 见定时分析报告 |
下一步
- 先把智能体建起来，再选入口：创建并配置数据智能体
- 用「人员」「角色」「策略」把数据范围定下来：权限与数据安全
- 私有部署要单独跑飞书网关或 MCP 容器：私有部署（Docker）