AgentKit Studio
任务指南

配置模型与凭证

添加模型档案、读取模型目录、验证连接、设置默认模型与思考等级,并配置构建部署所需的云端凭证。

模型配置决定「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_INVALIDAPI 地址不是合法 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

本页导航