> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 模型凭证

> 添加 OpenModels API 密钥、同步模型目录，并管理艾维斯模型能力使用的凭证。

“模型凭证”用于把 OpenModels API 密钥连接到艾维斯。每个已保存的凭证会加密存储一把 API 密钥，同步这把密钥可访问的模型目录，并把这些模型提供给后续模型配置页面选择。

添加凭证不等于自动启用所有模型，也不会自动替换默认模型。目录同步完成后，请继续到[语言模型](/aivis/models/language-models)以及图像、视频、语音等能力页面，选择实际要启用的模型。

## 准备事项

| 准备项               | 说明                                        |
| ----------------- | ----------------------------------------- |
| Admin 权限          | 只有管理员应添加、轮换、刷新或删除模型凭证。                    |
| OpenModels API 密钥 | 创建新凭证时必须填写。请先从 OpenModels 获取，再只粘贴到受保护表单中。 |
| 已批准的模型范围          | 在设置默认模型前，先确认工作区允许使用哪些模型类型。                |
| 网络访问              | 艾维斯部署环境需要能访问 OpenModels API。              |

## 获取 OpenModels API 密钥

如果组织已经有 OpenModels 账号，请向账号 owner 获取工作区批准使用的 API 密钥，或申请创建密钥的权限。如果还没有密钥：

1. 打开 [OpenModels](https://openmodels.market/)。
2. 登录或注册用于支付模型用量的组织账号。
3. 购买或开通艾维斯部署获准使用的模型访问权限。
4. 在 OpenModels 账号中创建或复制 OpenModels API 密钥。
5. 在粘贴到艾维斯前，请先把密钥保存在团队的密钥管理工具中。

共享部署建议使用生产环境归属的密钥，不要使用个人试用密钥。如果请求提示 OpenModels API Key 余额不足，也请到同一个 OpenModels 账号中检查余额或充值。

## 页面概览

![模型凭证页面，展示一个已同步的 OpenModels 凭证、可用模型数量、刷新、编辑和删除操作](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/e645c660d1e7984899d834691d18919e7a59932422a78a11600625c87f98b2b2/assets/aivis/model-credentials/model-credentials-list.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120101Z&X-Amz-Expires=604800&X-Amz-Signature=9f1979b5a4894abff4f792b9fbfae487da618d456c6eb6a791098590d26e6103&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

每张凭证卡片代表一把 OpenModels API 密钥及其已同步模型目录。

| 页面元素       | 含义                                          |
| ---------- | ------------------------------------------- |
| 凭证名称       | 管理员识别凭证时使用的标签。配置模型时会显示该名称，但不会发送到模型服务。       |
| 已遮挡密钥      | 只显示部分密钥，用于确认是哪把密钥；完整密钥不会再次展示。               |
| 同步状态       | 可能是“目录已同步”“同步失败”或“从未同步”。密钥变更或模型目录变更后，应刷新目录。 |
| 可用 / 不可用模型 | 可用模型可以被艾维斯能力选择；不可用模型只作为目录上下文或兼容性提示。         |
| 模型类型数量     | 目录会按语言、图像、视频、STT、TTS 五类汇总。                  |
| 上次同步       | 显示最近一次目录同步的时间。                              |
| 卡片操作       | 可编辑名称或密钥、刷新目录、删除凭证。                         |
| 可用模型抽屉     | 展开卡片后，可按模型类型查看可用模型列表。                       |

## 添加模型凭证

![添加模型凭证弹窗，展示名称和 OpenModels API 密钥字段](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/6154210367a165c544575e887500e0803950a869881204aa48973d859846ae99/assets/aivis/model-credentials/model-credentials-add-dialog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120101Z&X-Amz-Expires=604800&X-Amz-Signature=3e2f2714ee2f9997dfc30e625eba4056747bb189ae3fd94afffc9704a3ea5fde&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

1. 以 Admin 身份登录。
2. 打开 **管理后台 > 模型凭证**。
3. 点击 **添加凭证**。
4. 填写清晰的 **名称**，例如 `公司 OpenModels 密钥` 或 `生产环境 OpenModels`。
5. 粘贴 **OpenModels API 密钥**。
6. 点击 **保存并同步**。

艾维斯会保存凭证，并立即同步这把密钥可访问的模型目录。同步成功后，凭证卡片会显示“目录已同步”和可用模型数量。同步失败时，请重新打开表单检查密钥，修正后使用刷新按钮重新同步目录。

名称只用于管理员后续识别凭证，不会在模型请求中发送给 OpenModels。

## 查看可用模型

点击凭证卡片底部的 **查看可用模型**。展开后，模型目录会按能力分组：

* **语言**：用于对话、Agent 和文本推理。
* **图像**：用于图像生成或图像编辑。
* **视频**：用于文生视频、图生视频或视频编辑。
* **STT**：用于语音转文字。
* **TTS**：用于文字转语音。

在配置默认模型前，先用这个视图确认预期模型类型已经出现在目录中。

## 刷新、编辑或删除

| 操作   | 什么时候使用                             | 行为                                     |
| ---- | ---------------------------------- | -------------------------------------- |
| 刷新目录 | OpenModels 账号新增或失去模型权限，或需要重试失败的同步。 | 艾维斯会用已保存密钥重新拉取当前目录，并更新模型数量。            |
| 编辑凭证 | 修改凭证名称或轮换 API 密钥。                  | 编辑时如果密钥字段留空，会保留当前已保存密钥；只有粘贴新密钥时才会更新密钥。 |
| 删除凭证 | 密钥不再被批准使用，或该环境不再需要它。               | 如果还有模型设置依赖该凭证，艾维斯会阻止删除。请先把相关设置迁移到其他凭证。 |

编辑或刷新凭证后，如果默认模型或某个能力绑定依赖这个目录，请回到[语言模型](/aivis/models/language-models)、[图像生成](/aivis/features/image-generation)、[视频生成](/aivis/features/video-generation)和[语音](/aivis/features/voice)页面检查配置。

## 常见问题

| 现象             | 检查项                                                     |
| -------------- | ------------------------------------------------------- |
| **保存并同步** 不可点击 | 新建凭证时名称和 API 密钥都是必填项。检查是否只有空格或未填写。                      |
| 同步失败           | 确认 OpenModels API 密钥有效、未停用，并且艾维斯部署环境能访问 OpenModels API。 |
| 预期模型没有出现       | 确认这把密钥在 OpenModels 中有该模型权限，然后刷新目录。                      |
| 模型显示为不可用       | 目录里存在该模型，但艾维斯无法把它用于对应能力。请选择可用模型，或查看页面中的兼容性差异提示。         |
| 删除失败           | 该凭证仍被一个或多个模型设置引用。请先把这些设置迁移到其他凭证。                        |

## 安全实践

不要把 OpenModels API 密钥粘贴到 Agent 指令、对话消息、源代码、截图、工单或共享文档中。密钥只应通过“模型凭证”表单保存。

不同环境或访问边界建议使用不同凭证。按组织安全流程轮换密钥后，请刷新目录，并确认预期默认模型仍可正常使用。

## 相关页面

* [语言模型](/aivis/models/language-models) 说明如何在配置访问权限后选择目录模型。
* [生成与对话能力](/aivis/models/generation-and-chat) 介绍特定能力的配置和验证方式。
* [图像生成](/aivis/features/image-generation)、[视频生成](/aivis/features/video-generation)和[语音](/aivis/features/voice)会使用已同步目录配置各自的默认模型。