配置模型与凭证
添加模型档案、读取模型目录、验证连接、设置默认模型与思考等级,并配置构建部署所需的云端凭证。
模型配置决定「Agent 能调用哪个模型」。这一页把模型档案、API Key、思考等级和云端凭证一次配好,之后创建 Agent 时才能在「绑定能力」步骤选中模型。
前置条件
- 一个 OpenAI 兼容的模型服务地址,或一个金山云 / OpenAI 官方 Key。
- 能访问该端点的网络。企业内网网关需要先确认 Host 所在机器可以直连。
- 只有构建、部署和访问云端资源时,才需要页底的云端凭证。
操作步骤
打开模型与凭证设置
从 设置 → 模型与凭证 进入。首次启动会自动打开这个面板;错过引导也可以手动进入。
页面分两块:上面是模型与提供商,下面是云端凭证。只做本地对话时,云端凭证可以一直留空。
界面位置
添加模型档案
点右上角 + 添加模型。新档案的初始值:
| 字段 | 初始值 |
|---|---|
| 提供商 | 金山云模型服务 |
| API 地址 | 该提供商的官方默认地址 |
| 凭证名 | AGENTKIT_MODEL_API_KEY_<时间戳>,自动生成 |
| 启用 | 是 |
一个档案就是一条「提供商 + 地址 + 模型 + 凭证」的组合。要同时用两个供应商,就建两个档案。
界面位置
填写连接与凭证
连接
| 提供商 | API 地址 | 说明 |
|---|---|---|
| 金山云模型服务 | 只读,显示官方默认地址 | 无需填写,切换为自定义后可改 |
| OpenAI | 预填官方地址 | 可改成同协议的代理地址 |
| 自定义提供商 | 需要自己填 | 任何兼容 OpenAI 协议的服务 |
地址校验规则:必须是 HTTP(S),且不能带账号密码、查询参数或片段。失败返回 MODEL_ENDPOINT_INVALID,提示「模型服务地址须使用 HTTP(S),且不包含账号、查询参数或片段」。尾部多余的 /chat/completions、/responses、/models 会被自动裁掉。
凭证
在 API Key 输入框填入密钥。已经配置过的档案,占位符显示「已配置,留空保持不变」——留空表示不修改。
Key 存在哪里
API Key 只写入本机 Host 的凭证存储,不会进入 Agent 配置、浏览器表单回填或日志。 凭证来源在输入框下方显示,取值有「本机保存 / 全局配置 / 当前工作区 / 环境变量 / 本次会话 / 未配置」。 见安全与公开边界。
填完 Key 后点 读取模型,浏览器不会直连模型服务——读取由 Host 发起。
选择模型名称与思考等级
模型名称:点过读取模型后可以用下拉选择;也可以直接手写目录外的模型名。
思考等级:下拉里每一项都写成「界面档位 → 实际发送值」,例如 最高 → high。可选「不启用」,此时不写入任何思考档位。
| 提供商 | 可选档位 | 默认档 | 实际发送 reasoning_effort |
|---|---|---|---|
| 金山云模型服务 | 低 / 高 / 最高 | 高 | low / high / max |
| OpenAI | 低 / 中 / 高 | 中 | low / medium / high |
| Codex | 低 / 高 / 最高 | 高 | low / high / high(最高降级为 high) |
| 自定义提供商 | 低 / 高 | 高 | low / high |
切换提供商时,如果原档位不在新提供商的枚举里,会自动落到新提供商的默认档并给出提示,而不是等上游拒绝。
输入能力一行只读,显示模型目录识别到的 文字 / 图片。识别不到时分别提示「模型目录未提供能力信息」「暂时无法读取模型目录」「模型目录中未找到该模型」。
界面位置
管理多个档案
| 操作 | 位置 | 行为 |
|---|---|---|
| 设为默认 | 详情区右上 | 新会话使用该模型;同时取消其他档案的默认 |
| 停用 / 启用 | 详情区右上 | 停用后不出现在 Agent 的可选模型里 |
| 撤销修改 | 详情区右上 | 只丢弃当前档案的内存草稿,回到已保存配置 |
| 移除 | 详情区右上 | 删掉该档案;只剩一个档案时按钮消失 |
三条硬约束:
- 至少要保留一个启用的模型,否则提示「至少保留一个启用的模型」。
- 每个档案都必须填写模型名称,否则提示「每个模型配置都需要填写模型名称」。
- 默认档案必须有可用凭证,否则提示「请填写模型 API Key」。
改动先写进内存草稿,档案卡片上出现未保存标签。关掉面板再打开,草稿还在;刷新页面或换窗口,草稿就没了。
保存配置
点右下角 保存配置(首次引导里是保存并继续或保存并完成,取决于进入方式)。
保存会依次完成:写入模型档案 → 同步凭证 → 把档案应用到 DSH 的 provider 路由 → 广播模型变更事件。过程中按钮显示保存中…。
成功后底部提示:
已保存多个模型配置;标记为“默认”的模型用于新会话,Agent 可在创建或编辑时多选模型绑定。重新读取会显式丢弃全部草稿,回到存储里的配置;如果确实丢弃过草稿,会额外提示「已丢弃未保存的草稿,并重新读取已保存的配置」。
可选:配置云端凭证
只有构建、部署和访问云端资源时才需要。
| 字段 | 必填 | 说明 |
|---|---|---|
| Access Key | 是(首次) | 已配置时占位符显示「已配置,留空保持不变」 |
| Secret Key | 是(首次) | 同上 |
| Account ID | 否 | 可选 |
| 区域 | 否 | 例如 cn-beijing-6 |
| 控制面地址 | 否 | AgentEngine 控制面地址 |
| 对象存储桶 | 否 | 可选 |
后四项收在高级云端设置折叠区里。首次配置时 Access Key 与 Secret Key 必须同时填写,否则提示「请填写 Access Key 和 Secret Key,或跳过云端配置」。保存成功提示「云端凭证已保存」。
界面位置
成功后的样子
同时满足以下四条:
- 模型卡片右侧显示绿色的已配置,不是需要配置。
- 卡片标题旁出现默认标签(只有一个档案能带)。
- 右上角状态条显示当前默认模型名称。
- 去创建 Agent 的「绑定能力」步骤,默认模型下拉能列出这个模型。
常见错误
| 错误码 | 原因 | 处理 |
|---|---|---|
MODEL_CREDENTIAL_MISSING | 默认档案还没有 API Key | 在该档案的 API Key 里填写密钥后保存 |
MODEL_PROFILE_INVALID | 模型 ID、模型名称或凭证引用格式不合法 | 模型 ID 需匹配 ^[a-z][a-z0-9._-]{1,127}$,凭证名需匹配 ^[A-Za-z_][A-Za-z0-9_]*$ |
MODEL_PROFILE_EXISTS | 资源库里的模型资源名称重复 | 换一个名称,或在已有资源上编辑 |
MODEL_ENDPOINT_INVALID | API 地址不是合法 HTTP(S),或带了账号、查询参数、片段 | 去掉 ?、# 和 user:pass@ 部分 |
MODEL_CATALOG_FAILED | 读取模型目录时上游返回非 2xx | 检查 Key 权限与端点地址;测试连接看具体状态 |
MODEL_CATALOG_UNAVAILABLE | 目录整体不可用 | 只显示已配置档案;确认网络与凭证后点重新读取 |
MODEL_CREDENTIAL_STATUS_FAILED | 查询凭证状态失败 | 重开面板;持续失败时检查 Host 日志 |
MODEL_CREDENTIAL_SYNC_FAILED | 凭证同步到 DSH 失败 | 重试保存;仍然失败时重启 Host 后重试 |
请填写模型 API Key | 默认档案没有 Key 且从未配置过 | 填写 Key 后保存 |
相关参考
| 你想知道 | 去哪里 |
|---|---|
| 思考等级与上游枚举的完整映射 | src/model-reasoning.mjs |
| 地址归一化规则 | src/model-endpoint.mjs |
| 模型档案字段与运行时选项 | src/model-profile-contract.mjs、src/model-service.mjs |
| 模型与凭证面板源码 | src/client/pages/model-settings.mjs |
| 凭证相关的环境变量 | 环境变量参考 |
| 用模型档案创建 Agent | 创建与编辑 Agent |