1. Zenova 概览与配置流程

完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向首次接触 Zenova 的租户管理员和试点负责人，说明 Zenova 解决什么问题、员工和管理员分别从哪些入口使用它、Zenova 在模型网关之上多出了哪些员工侧与智能体能力。随后给出两条完整路线：管理员的首次配置路线（接入上游、确认模型、创建模型分组并分发、设置默认模型、建立工作空间、打通对话与 API 调用），以及员工的上手路线。读完本章，管理员可以让第一位员工在对话中用上智能体、用自己的 API 密钥调用模型，并在管理后台查到这些调用。

1.1 产品定位

Zenova 是部署在企业内部的员工 AI 工作平台。它由两部分能力组成：

• 模型与工具网关：企业的业务系统、开发工具、外部智能体和 Zenova 自己的智能体，都通过同一个网关调用模型与工具。网关负责统一入口、凭据托管、授权、流量治理和调用追溯。
• 员工工作台与智能体：员工在工作台里与智能体对话，使用企业知识库、文件、应用与技能，让智能体调用工具完成任务；管理员把模型、工具、知识和智能体模板按部门、职能组或工作空间分发给员工。

网关在中间承担四件事：

平台在逻辑上分为三层：

• 控制面提供工作台与管理后台，保存组织、模型、规则、智能体等配置，并把配置下发到网关节点。
• 网关数据面接收模型与工具调用，在网关上完成认证、按规则处理，再转发给上游。调用记录由数据面产生，回传到控制台。
• 智能体运行时执行员工交给智能体的任务：组织上下文、通过网关调用模型、调用工具、在需要时请求审批，并产出可核对的结果。智能体发出的模型调用同样经过网关，因此与业务系统的调用使用同一套授权、规则和记录。

在「管理后台 › 观测中心 › 运行总览」中可以看到全公司的运行指标：总消耗费用、总 Token、网关耗时 P95、网关实时并发，以及模型调用交付成功率及其失败构成（平台配置拒绝、上游故障、调用方取消、传输中断、未归类）。这些数字来自真实的网关调用，不是估算值。

组件自身的运行状态在 /platform-status 平台状态页查看。页面按组件列出探活时间线，社区版部署默认包含 PostgreSQL、SpiceDB、容器运行时、IDP、模型网关、ClickHouse、对象存储七项。时间线用于判断某个依赖是否在观察窗口内出现过中断，与业务指标相互独立。

注意：交付成功率的分母包含被平台规则拒绝的请求。做容量评估时，先看失败构成，再判断是上游不稳定还是策略配置不符合预期。

1.2 使用面与入口

Zenova 有两个使用面：员工日常使用的工作台，以及管理人员使用的管理后台。两者用同一个账号登录，看的是同一批对象，只是姿态不同。

登录后落地页：普通成员登录后进入工作台「首页」；租户管理员与平台账号登录后进入管理后台。管理后台侧栏顶部的「返回工作台」回到工作台。

1.2.1 工作台顶栏

工作台顶部是一行一级入口，左上角是工作空间切换器，右上角是搜索（Ctrl+K / ⌘K）与账号菜单。

能力中心的目录页在未登录时也可以浏览已公开发布的内容；能否使用由分发范围决定，登录后才会显示「获取 API 密钥」等操作。

工作空间切换器：员工可能属于多个工作空间（含自己的「个人空间」）。切换工作空间后，「智能体」入口下的对话、智能体、文件等内容随之切换。切换器菜单中还有「工作空间设置」和「创建工作空间」，见第 3.10 节。

1.2.2 首页

「首页」左侧分组如下：

「使用情况」显示问候语、近 30 天的调用指标与一年的活跃热力图；「调用日志」逐条列出本人的模型调用；「API keys」列出本人创建的密钥；「账户安全」用于修改密码、绑定两步验证与通行密钥（第 3.8 节）；「IM 工具」「渠道绑定」用于把智能体接入钉钉、飞书、企业微信等 IM 工具（第 16 章）。

1.2.3 智能体入口

顶栏「智能体」进入员工与智能体协作的区域，左侧固定七项：

侧栏下方是会话列表。当前工作空间还没有智能体时，「新对话」页提示「当前工作空间还没有智能体，创建一个开始对话吧」。

1.2.4 管理后台

管理后台的侧栏按职责分组。租户管理后台的分组为：观测中心、模型、能力、智能体、组织与权限、护栏、流量、运行与排障、审计与合规、系统设置。其中「智能体」分组（角色模板、频道管理、智能体运营）是 Zenova 在网关之上增加的管理面。

「网关域名接入」不在侧栏中：在「运行总览 › 会话」打开一场会话，会话详情的网关提示条显示「本会话没有经过网关的请求。……」时，点提示条上的「查看接入方式」进入。

平台管理后台的侧栏依次是平台首页、租户、运行监控、网关、扩展、平台账号与登录、通知渠道、集成与导出、系统维护，见第 2.6 节与第 33 章。

1.3 Zenova 比纯网关多出的能力

只部署模型网关时，员工侧只有能力中心、首页和提示词；Zenova 在此之上提供以下员工侧与智能体能力。网关与治理部分（模型、MCP、API、护栏、流量、观测）两者一致。

这些能力共用网关：智能体的每一次模型调用都按调用人的授权、模型分组的配额和流量规则处理，记入用量与请求记录。因此「谁能用哪个模型」只需要在模型分组的可用范围里配置一次，对话、智能体和 API 调用同时生效。

1.4 管理角色与菜单可见性

管理角色

管理权限以「对象 × 动作」为单位（例如「流量规则 · 新建」），一组权限组成一个角色，角色经「授予」赋给成员或职能组，范围为全租户或某个部门（含下级部门）。平台内置 8 个角色，也可以新建自定义角色：

系统管理员、安全管理员、审计员两两互斥，同一成员只能持有其中一类权限，用于满足三员分立要求；运营、财务、只读审计可以与其他角色叠加。各角色的完整权限、自定义角色、授予与按部门委派见第 3.5 节。

工作空间另有自己的角色（管理员、编辑者、查看者），只决定在该工作空间内能做什么，与上表的管理角色相互独立：成为工作空间管理员不会获得管理后台权限，持有管理角色也不会自动加入某个工作空间（第 3.10 节）。

菜单可见性

看不到某个菜单时，按以下顺序核对三件事：

1. 管理范围：租户管理后台与平台管理后台是两级。租户管理员只能看到本租户的菜单；在租户管理后台的地址栏直接输入平台页面（例如 /admin/tenants）会被送回「运行总览」，相应的平台接口返回 403。两级边界见第 2.6 节。
2. 授予：侧栏只出现成员经授予有权查看的入口，页面中的按钮只出现被允许的操作。例如系统管理员的侧栏不含 SSO 配置、成员与部门、角色管理与操作审计；按部门授予的成员只看到其角色涉及的入口，且只看到范围内的记录。
3. 许可模块：许可证未包含某个模块时，对应菜单与工作台入口不显示，相关接口拒绝访问（第 2.7 节）。例如未授予智能体相关模块时，顶栏不出现「智能体」。

1.5 管理员首次配置路线

首次配置的目标是：一位员工能在对话中使用智能体，也能用自己的 API 密钥成功调用模型，并且管理员能在管理后台查到这些调用。

开始前确认：已用管理员账号登录管理后台；已准备好上游模型厂商的地址与账号密钥，或本地推理服务的地址。

步骤 1：建立组织

在「管理后台 › 组织与权限 › 成员与部门」中新建试点部门并添加成员，或先接入 SSO 与通讯录同步。组织先于能力配置，后续可以按部门或职能组整体授权。操作见第 3 章。

步骤 2：接入上游模型来源

在「管理后台 › 模型 › 模型供应商」中添加上游。供应商对象保存请求地址、请求格式与账号密钥，是平台连接一个上游来源的唯一方式。内置供应商目录覆盖主流公有云、聚合平台与本地部署的推理服务；接入本地服务时按部署类型选择对应的请求格式。

你会看到：保存前，每个要启用的上游模型在「模型」页签的「决策」列给出去向：同名的关联到已有模型，其余默认新建同名模型，可以改名。保存后供应商出现在列表中，「管理后台 › 模型 › 模型」中出现对应的模型；只有启用的上游才会为模型提供服务。

字段含义、连接测试与定价见第 4 章、第 5 章。

步骤 3：确认模型并创建模型分组

平台中有三个对象：上游是供应商侧的具体模型，模型是调用方请求时使用的调用名，由一个或多个上游提供；模型分组是一组模型的集合，授权与配额都挂在分组上。员工与智能体直接选择模型，不需要知道背后的供应商是谁。三个对象的完整说明见第 6 章。

1. 进入「管理后台 › 模型 › 模型」，确认步骤 2 启用的上游已出现为模型，「上游」列列出对应的供应商。
2. 打开模型详情，在「试用」页签发送一条消息，确认模型能正常返回回复。
3. 进入「管理后台 › 组织与权限 › 模型分组」，点「添加模型分组」。
4. 填写名称与描述。名称按用途取，例如「通用对话」「低价批处理」；描述里建议写明适用任务与成本等级，员工在能力中心会看到这段文字。
5. 点「添加模型」，勾选要纳入分组的模型，保存。

你会看到：试用时先显示进度条，随后返回完整回复，回复下方显示首字耗时、总耗时与 Token 数。分组保存后出现在「模型分组」列表中，详情页有「基本信息」「可用范围与配额」「调用情况」「操作审计」等页签。

注意

• 同一个模型可以出现在多个分组中；按用途拆成多个分组，便于分别设置可用范围、配额与计价。
• 试用会真实计费，也计入调用记录与操作审计。
• 推理型模型的输出长度由 max_tokens 约束。把 max_tokens 设得过小时，推理过程会先耗尽额度，正文返回为空、结束原因为长度截断，这属于上游的正常表现。试用时不要设置过小的上限。

步骤 4：分发给成员（设置可用范围）

新建的模型分组默认没有可用范围，任何人都不能使用，智能体也选不到其中的模型。

操作步骤

1. 打开分组详情，切到「可用范围与配额」页签，点「编辑可用范围」。
2. 在弹窗左侧下拉中切换授权对象类型：所有用户、部门、职能组、工作空间，或按成员逐一勾选。勾选后右侧列出已选对象。
3. 点「下一步」，进入「配置目标有效期」。保留「长期有效」，或选择固定的天数与自定义起止时间。
4. 点「保存」。

你会看到：保存后可用范围表按对象逐行列出，包含范围名称与类型。

注意

• 授权后，范围内的员工才能在能力中心看到分组内的模型，并在「获取 API 密钥」的归属下拉中选到该分组；授权给工作空间时，该分组出现在工作空间的「模型分组」页签，工作空间内的智能体可以选用分组内的模型。
• 把员工移出可用范围后，员工侧不再看到该分组，其原有密钥经该分组的调用随后转为被拒绝（返回 401 invalid_api_key）。授权变更下发到网关需要一定时间，撤权后如需确认已生效，按第 3.9 节核对。
• 配额与预算在同一页签设置，见第 7 章。

步骤 5：设置默认模型

员工新建智能体时默认使用哪个模型、知识库用哪个模型做嵌入，由全局默认模型决定。

1. 进入「管理后台 › 系统设置 › 全局设置」，在「默认模型」区域点「编辑」。
2. 至少为「新建智能体的对话模型」选择一个模型。计划使用知识库时，同时设置「知识库嵌入」。
3. 点「保存」。

你会看到：对应行的「状态」显示「正常」或「已生效」。

注意：「新建智能体的对话模型」属于用户直接使用的功能，员工还需要在包含所选模型的某个模型分组的可用范围内才能用上它。全部十项功能的含义见第 5.10 节。

步骤 6：建立试点工作空间

工作空间是员工协作和智能体的边界：同一工作空间的成员共享该空间内的智能体、知识库与文件。每位员工另有一个只属于自己的「个人空间」。

1. 进入「管理后台 › 组织与权限 › 工作空间」，点「新建工作空间」，填写名称与描述。
2. 创建后进入详情，在「成员」页签点「邀请」，把试点成员或部门加入，并选择工作空间角色。
3. 在「模型分组」页签核对已分发给该工作空间的模型分组。这里只读，增减分组在模型分组的「可用范围」中完成（步骤 4）。

详情页的六个页签（基本信息、模型分组、成员、智能体、操作日志、资源上限）见第 3.10 节。

步骤 7：员工完成第一次对话

1. 员工登录工作台，在左上角切换到试点工作空间。
2. 点顶栏「智能体」，在「智能体」页点「添加智能体」，按「选择起点 › 身份与模型 › 技能与应用」三步完成；也可以直接用管理员已共享到工作空间的智能体。
3. 回到「新对话」，在输入框中输入任务并发送。

你会看到：智能体流式返回回复；需要调用工具时，按审批模式请求确认。对话与智能体的完整用法见第 8 章、第 13 章。

步骤 8：员工获取 API 密钥并调用

API 密钥由员工本人创建，每把密钥绑定一个模型分组，可以调用该分组内的全部模型，供业务系统或开发工具使用。

1. 员工点顶栏「模型」进入模型目录，用搜索框、厂商或分类找到要用的模型，打开详情。
2. 点「获取 API 密钥」。
3. 在「API 密钥归属」中选择归属于哪个授权对象。下拉只列出本人在可用范围内的分组，形如「个人专属 · 通用对话」或「研发中心 · 部门 · 通用对话」。「指定 API 密钥（可选）」留空时由系统生成。
4. 选择挂靠的客户端，或新建一个客户端。客户端用于在用量与请求记录中区分调用来源。
5. 点「创建」。

模型详情的「首次调用 API」页签给出本平台的接入地址与各协议的示例代码，可直接复制。以 OpenAI 兼容协议为例：

curl https://<网关地址>/api/v1/agent-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [{"role": "user", "content": "用一句话介绍你自己。"}]
  }'

使用 OpenAI SDK 时只需改两处：base_url 设为 https://<网关地址>/api/v1/agent-gateway/openai/v1，api_key 设为本人的 API 密钥。

你会看到

• 密钥出现在「首页 › API keys」中，状态为「正常」；管理员在「管理后台 › 组织与权限 › 模型分组 › API 密钥管理」中能看到同一把密钥的归属、调用方、计费对象与状态。
• 对话补全返回标准的 chat.completion 结构；成功的响应头带链路 ID（x-trace-id），用于在控制台定位这次调用。

注意

• 接入地址以模型详情「首次调用 API」页签显示的为准；根路径 /v1/... 不是网关入口。
• 旧版补全接口（completions）对多数模型不适用，请求在网关侧即被拒绝，返回 400 MODEL_ENDPOINT_UNSUPPORTED，不计费。请改用对话补全或 Responses 接口。
• 密钥按掩码显示，请复制后妥善保存。不要在多人或多个系统之间共用同一把密钥。接口细节与错误码见第 20 章、第 21 章和附录 C。

步骤 9：查看调用记录

管理员查看

1. 进入「管理后台 › 运行总览」，切到「请求」页签。
2. 用搜索框或筛选条件收敛列表：可按模型名、发起人、结果、时间范围筛选。
3. 点击记录打开详情，在「概要」「请求」「路由与改写」三个页签中核对发起人与凭据、请求与响应体积、耗时分解，以及本次命中的流量规则。

你会看到

• 员工在对话中产生的模型调用与 API 调用同样出现在列表中，发起人都是该员工。
• 成功的调用显示为「已完成」，并给出端到端耗时与上游耗时。
• 被网关拒绝的请求同样会记录一行，结果为「失败」并标注 HTTP 状态码；在网关侧就被拒绝的请求耗时为 0、计费为 0，其「路由与改写」中会说明本次没有上游尝试。

员工查看：员工在「首页 › 调用日志」中按时间逐条查看本人的调用，包括所调用的模型、状态、Token、耗时与费用；「首页 › 使用情况」「模型用量」给出汇总。

注意：按链路 ID 检索若未命中，改用模型名加时间范围收敛列表，再按时间定位。

1.6 员工上手路线

员工第一次使用 Zenova，按以下顺序熟悉即可：

注意：员工在能力中心看到的模型、MCP、API、知识库与技能，都是管理员已发布并分发给本人（或本人所在部门、职能组、工作空间）的内容。卡片上显示「需要管理员分发」时，表示该能力已公开但尚未分发给本人，请联系管理员。

1.7 后续配置顺序

首次对话与调用打通后，建议按以下顺序完善配置，再逐步扩大使用范围：

1. 组织与身份：接入 SSO 与通讯录同步，按职能组组织跨部门团队，指定系统管理员、安全管理员、审计员，设置会话与密码策略，规划工作空间（第 3 章）。
2. 模型完善：补充上游账号与定价，按用途拆分模型分组，设置配额与预算（第 4 章至第 7 章）。
3. 能力接入：接入 MCP 服务、API 服务、技能与知识库，设置可用范围（第 10 章、第 22 章、第 23 章）。
4. 智能体：维护角色模板，建立代表性的业务智能体，确定工具审批方式与 IM 接入（第 13 章至第 17 章）。
5. 流量与安全：配置敏感数据检测、内容检测与流量规则，保存前用规则预览核对命中顺序；核对运行时安全与凭据（第 18 章、第 24 章至第 26 章）。
6. 告警与审计：配置通知渠道与告警规则，确认日志留存与操作审计符合合规要求（第 32 章）。
7. 分阶段上线：先在试点部门完成正常调用、拒绝、额度耗尽、工具审批与异常输入的验证，再推广（第 35 章、第 36 章）。

1.8 配置完成标准

• 员工能在试点工作空间中与智能体完成对话，需要审批的工具调用能正确请求确认。
• 员工能在能力中心看到获授权分组内的模型，用本人密钥调用成功；可用范围以外的账号看不到这些模型，调用被拒绝。
• 模型的「试用」返回完整回复，并显示首字耗时、总耗时与 Token；「新建智能体的对话模型」状态正常。
• 管理员能在「运行总览 › 请求」中找到试点员工的对话调用与 API 调用，发起人、凭据与用量正确；员工能在「首页 › 调用日志」看到同样的调用。
• 把员工移出可用范围后，员工侧的分组消失，旧密钥的调用转为被拒绝，且能在「运行总览 › 请求」中查到这些被拒绝的请求。
• 系统管理员、安全管理员、审计员由不同人员担任，配置变更能在操作审计中查到操作人与时间。
• 告警接收人、备份恢复责任人与技术支持联系人已经明确。

能力说明

---

下一章：2. 平台对象和边界