3.10 应用接入

应用接入 key（moai-ac- 前缀）是业务系统调用 MoAI 能力的统一凭证：一个 key 按功能范围授权，可以直连模型网关调用模型、读写知识库与知识图谱、以应用身份对话，以及走 MCP、ACP、A2A 等标准协议。范围随时调整、实时生效。

入口在团队空间的「应用接入」菜单（团队管理员可见）：

列表展示每个 key 的接入名称、掩码显示的 Key、访问范围标签、创建时间与最近使用时间；行操作可编辑、删除。Key 默认掩码显示，点击眼睛图标查看完整 key 或复制。

创建接入 key

点击「新建接入」，勾选需要的能力范围：

范围	说明
知识库	三档：无权限 / 只读 / 可写，控制外部接口对知识库的操作边界
知识图谱	三档同上，控制图谱的外部读写（含按业务 key 同步）
模型网关	开启后可用该 key 直连模型网关调用团队可用模型（见 3.11）
应用对话	以应用身份与指定应用对话
知识库 MCP / 知识图谱 MCP	开启对应 MCP 服务器通道（见 3.5.7）
应用 ACP / 应用 A2A	开启对应标准协议端点

配置原则与创建步骤：

1. 最小授权：从最小范围开始，按需增加——范围是安全边界，不是功能清单；
2. 填写接入名称与描述（说明用途与负责人，便于后续审计）；
3. 保存后立即展示完整 key，这是唯一一次明文展示，此后列表中只显示掩码；
4. 交给业务系统配置，妥善保管、避免泄露。

日常管理

• 调整范围：行操作「编辑」随时增减范围，保存立即生效——发现 key 被滥用时，第一动作是收窄范围；
• 吊销：行操作「删除」，key 立即失效（依赖它的集成即刻断开）；需要轮换时新建 key、切换业务系统、再删除旧 key；
• 审计：「最近使用」列可发现长期未用的 key（应及时清理）与异常活跃的 key。

典型接入方式

• 直连模型网关：把业务系统里 OpenAI SDK 的 BaseAddress 指向网关地址、API Key 填接入 key（详见 3.11 模型网关）；
• 读写知识库：按知识库外部接口的 REST 约定调用，key 决定读写档位（见 3.5.4 安全）；
• 图谱按 key 同步：业务系统以业务 key 为锚点增量 upsert 图谱数据（见 3.6 知识图谱）；
• 应用对话：需要注意，需要「授权的外部应用对话」仍须用 appId 换取外部用户 token 后再对话，key 只负责通道授权；
• 协议接入：MCP / ACP / A2A 端点同样以 key 鉴权。

案例：报表系统直连 MoAI

BI 团队的报表系统要调用大模型生成分析结论：

1. 建 key：新建接入「BI-报表系统」，只勾选「模型网关」，交付 BI 服务；
2. 改调用：BI 系统把 OpenAI SDK 的 base_url 指向网关地址、api_key 填 key——现有代码零改动，模型换成团队可用模型即跑通；
3. 扩范围：后续 BI 还要把分析结论写回知识库，编辑 key 增加知识库「可写」——不用换 key；
4. 轮换：年底安全检查发现 key 疑似泄露：新建新 key → BI 系统切换 → 删除旧 key，全程旧 key 即时失效，无需重启任何服务。

常见问题

key 和外部用户 token 是什么关系？
key 授权「系统能力」（网关、知识库、协议通道）；外部用户 token 标识「正在对话的人」。需要授权的外部应用对话两者都要：先以 appId 换 token，对话请求再携带。

范围改了为什么不生效？
范围变更实时生效；如果业务侧有网关或代理缓存，请排除缓存因素后再排查。仍不生效时检查编辑的是否为同一个 key。

key 泄露了怎么办？
立即删除（或先收窄范围止损）→ 新建 key → 通知业务系统切换。删除即刻失效，不存在等待过期的问题。

一个团队能建多少个 key？
没有硬性数量限制，但建议按「一个集成一个 key」管理，便于按用途授权与审计。