AgentKit Studio
帮助

排障

按「症状 → 错误码 → 原因 → 处理」四列定位问题,覆盖 Studio 源码中最高频的七十余个错误码。

Studio 的错误码全部来自 src/** 里的 code: '...' 字面量,可以直接在源码里搜。这一页按出错位置分组,同一个错误码只出现一次。

先确认错误码是不是真的错误码

界面上的错误文案有时是自然语言,错误码在被折叠的详情里。展开工具卡片、或到 运行中心 → 观测 看 Trace,能拿到原始 code 与 HTTP 状态。

模型与凭证

症状错误码原因处理
发消息立刻失败,提示去配 KeyMODEL_CREDENTIAL_MISSING模型配置没有可用的 API Key(src/model-service.mjs:71,116)设置 → 模型与凭证,选中模型填 Key 后保存
选了模型但请求打到空MODEL_NOT_FOUND模型配置不存在、已停用,或不在网关目录中(model-service.mjs:61)在「默认模型」里重选;网关模式先刷新模型目录
保存模型时报地址无效MODEL_ENDPOINT_INVALID服务地址不是合法 URL(src/model-endpoint.mjs:9)补全 https:// 与主机名
同上,但报的是协议MODEL_URL_INVALID只接受 https: 端点(model-service.mjs:37)换成 HTTPS 端点,本地调试用 localhost 代理
保存后模型列表为空MODEL_PROFILE_INVALID模型名称、模型 ID 或凭证引用三者有一项无效(model-service.mjs:34)重新「读取模型目录」,从目录里选而不是手打
想重名保存被拒MODEL_PROFILE_EXISTS模型资源名称已被占用(model-service.mjs:41)换一个名称
「读取模型目录」失败MODEL_CATALOG_FAILED目录接口返回非 2xx(model-service.mjs:89)检查端点、Key 与出网策略;错误文案带状态码
云端资源页空CLOUD_CREDENTIALS_MISSING没配云端 AK/SK(src/server-client.mjs:361,462,519)设置 → 模型与凭证 → 云端配置,填 AK/SK
请求被 413 拒绝REQUEST_TOO_LARGE模型请求体超过 16 MiB(src/model-proxy-handler.mjs:47)减少附件、缩短历史,或拆成多轮
回答只出了一半就断UPSTREAM_STREAM_TRUNCATED上游模型流没返回完成标记就断开(model-proxy-handler.mjs:150)重试;持续出现时检查代理/网关的空闲超时
兼容端点要求重传历史STATELESS_INPUT_REQUIRED该端点不保存远端 Response ID(model-proxy-handler.mjs:55)客户端必须每轮传完整对话历史
选 Codex 模型被拒CODEX_AGENT_REQUIRED没有绑定 Codex Agent(src/providers/dsh-runtime.mjs:585)先在 Agent 上绑定 Codex 运行时,再选模型

Agent 与构建

症状错误码原因处理
会话里发消息失败STUDIO_AGENT_REQUIRED当前会话没有绑定 Agent(dsh-runtime.mjs:604)从智能体面板选中一个 Agent 再发
发送按钮点了没反应STUDIO_INPUT_REQUIRED输入为空且没有图片(dsh-runtime.mjs:605)输入文字或附加图片
编辑后保存报「不存在」AGENT_NOT_FOUND本地 Agent 已被删除或 ID 漂移(src/host/routes/agents.mjs:13)刷新智能体列表后重选
请求缺参数INVALID_AGENT_IDAgentId 为空(agents.mjs:52)从列表进入,不要手拼 URL 或命令
部署/运行被拒BUILD_NOT_READYAgent 还没有可运行的 Build(src/host-remote.mjs:166)先创建 Build 并等它完成
冻结会话创建失败STUDIO_PRESET_RUNTIME_UNSUPPORTED当前 runtime 没有 DSH 原生会话适配器(src/agent-preset-admission.mjs:161)换成 dsh-native 运行时再冻版本
老会话打不开DSH_PRESET_ROUTE_UNAVAILABLE会话原有的 Agent 运行预设不可用(agent-preset-admission.mjs:343)重新绑定运行时;不要试图恢复已删除的预设
MCP 工具调用失败STUDIO_NATIVE_MCP_SCHEMA_ENGINE_REQUIRED会话的 MCP 工具 schema 引擎不可用(src/providers/dsh-runtime-plugin.mjs:209)「请重新绑定当前会话的 MCP 工具」
模型要调一个不存在的工具TOOL_NOT_FOUNDDSH Tool 未注册,或不在当前 Agent 绑定范围(dsh-runtime-plugin.mjs:173)在 Agent 编辑页补绑该 Tool,或改提示词

运行时

症状错误码原因处理
全程无响应HOST_CONNECTION_MISSINGStudio 本地任务需要已连接的 Studio Host(src/remote/control-client.mjs:144)看右上角状态胶囊;重启 Host 后重试
插件加载被拒STUDIO_HOST_INCOMPATIBLE宿主版本不满足 engines.dsh(src/host/compatibility.mjs:40)升级到固定的 DSH 基线 0.2.2-rc.1
托管会话起不来NATIVE_ENGINE_UNAVAILABLE托管 Native Harness 需要独立服务绑定(src/host/bootstrap.mjs:406)配置并启动独立的 Harness 服务
报「没有绑定独立 Harness」NATIVE_ENGINE_WORKSPACE_UNAVAILABLE当前工作区没绑定独立 Harness(agent-preset-admission.mjs:335)换到已配置的工作区
Harness 配置报错NATIVE_ENGINE_CONFIG_INVALID工作区、服务地址、凭据或预览地址有一项无效(src/providers/engine-service-workspaces.mjs:57)逐项核对四项配置
Native 引擎要模型NATIVE_ENGINE_MODEL_UNAVAILABLE需要已配置接口地址的模型(dsh-runtime.mjs:629)在 Agent 上绑定网关模型
一轮跑完是失败DSH_TURN_FAILED运行时本轮未完成(src/dsh-history-display.mjs:6)重试;持续失败看模型与工具连接
老的进程内会话操作LOCAL_HARNESS_RETIRED进程内 Harness 已退役(src/host/routes/http.mjs:24)改用 Native Harness 会话
同上,另一入口STUDIO_LEGACY_HARNESS_RETIRED该操作属于已退役的进程内 Harness 会话(src/host/routes/sessions.mjs:8)重新创建 Native 会话
冻结版本跑不动RUNTIME_MODEL_UNAVAILABLE冻结模型没有可用的运行时路由(src/frozen-build-runtime.mjs:72)重新构建,让模型进入冻结绑定
冻结版本报模型不符RESPONSES_FROZEN_MODEL_MISMATCH请求的模型不在冻结绑定中(frozen-build-runtime.mjs:88)用冻结时绑定的模型发请求
宿主能力不足RUNTIME_HOST_CAPABILITY_UNAVAILABLE冻结运行时需要支持请求指纹的 DSH 宿主(frozen-build-runtime.mjs:58)升级宿主
自动化跑不起来AUTOMATION_SERVICE_UNAVAILABLE自动化需要的 DSH 服务未启动(src/native-automation-runner.mjs:32)按提示启动对应服务
自动化卡住AUTOMATION_TIMEOUT自动化运行超时(native-automation-runner.mjs:85)缩短任务或拆成多步

Star Harness

star-harness/* 五个 operation 管的是本机 Star Harness(harness 运行时)的安装、启停与工作区绑定。它们只对 Studio 宿主所有者开放,非所有者调用会直接拿到 STAR_HARNESS_OWNER_REQUIRED。

症状错误码原因处理
点安装没反应STAR_HARNESS_NOT_INSTALLED还没装就点了启用或绑定(src/host/services/star-harness.mjs:14)先在插件页安装 Star Harness,再启用
安装报找不到 npmSTAR_HARNESS_NPM_MISSINGStudio 宿主进程找不到 npm(star-harness-release.mjs:72)装 Node.js 与 npm,确保宿主启动时的 PATH 里有 npm
安装卡在下载STAR_HARNESS_DOWNLOAD_FAILED从 npm registry 下载失败(star-harness-release.mjs:138)检查网络与代理;确认版本号在 registry 上存在
安装报文件完整性失败STAR_HARNESS_RELEASE_INVALID版本号无效,或下载产物摘要不匹配(star-harness-release.mjs:80)重新安装;反复失败说明本地缓存损坏,删掉 Star Harness 状态目录后重装
安装后启动不起来STAR_HARNESS_START_FAILED子进程启动失败或协议握手超时(star-harness-release.mjs:225)看宿主日志里的子进程 stderr;确认端口与工作区目录可写
这份版本没被校验STAR_HARNESS_RELEASE_UNREVIEWED该版本没有当前 Studio 的校验记录(star-harness-release.mjs:28)先更新 Studio,再装与之匹配的版本
版本与 Studio 不兼容STAR_HARNESS_INCOMPATIBLE引擎协议版本、包名或能力集不匹配(star-harness-release.mjs:168)换成 Studio 校验过的版本;不要手改 pins
选的版本不被接受STAR_HARNESS_VERSION_UNSUPPORTED既不是新版,也不是上次回退的那个版本(star-harness.mjs:191)选更新的版本,或回退到「上次使用的版本」
版本号格式被拒STAR_HARNESS_INVALID_REQUEST版本号不是三段 semver,或参数类型不对(star-harness.mjs:13)用 x.y.z 形式;从列表里选,不要手打
绑定工作区被拒STAR_HARNESS_WORKSPACE_CONFLICT目录与已有绑定、外部 Harness 或 Star Harness 状态目录重叠(star-harness.mjs:71)换一个不嵌套、不重叠的目录
绑了工作区却起不来STAR_HARNESS_MODEL_CHANGED工作区绑定的模型档案被改过(star-harness.mjs:65)解绑后重新绑定,选当前可用的模型档案
任务跑着改版本被拒STAR_HARNESS_BUSY有任务在运行,或有变更正在应用(star-harness.mjs:11)等当前任务结束或取消后再改;不要在运行中连续点
管理服务已关闭STAR_HARNESS_CLOSED宿主正在关闭,管理服务已释放(star-harness.mjs:12)重启 Studio 宿主
本地设置读不出来STAR_HARNESS_CONFIG_INVALIDsettings.json 缺失、损坏或字段类型不对(star-harness.mjs:41)删掉 Star Harness 状态目录下的 settings.json 后重新绑定
提示没有权限STAR_HARNESS_OWNER_REQUIRED非所有者主体调用了 star-harness/*(src/host/routes/http.mjs:65)用 Studio 宿主所有者账号操作
当前部署不支持STAR_HARNESS_UNSUPPORTED该部署没有挂载本机 Star Harness 管理器(src/host/routes/star-harness.mjs:6)改用独立 Harness 服务;本机管理只存在于桌面端与源码运行

资源

症状错误码原因处理
MCP 绑定报重复MCP_BINDING_AMBIGUOUS同一 Agent 版本的 MCP 绑定别名重复(src/host/services/resource-tools.mjs:17)改别名,保证唯一
模型调 MCP 工具失败MCP_RESOURCE_NOT_BOUNDMCP 未绑定到当前 Agent 版本(resource-tools.mjs:16)在 Agent 编辑页重新绑定
Skill 下载被拒SKILL_DOWNLOAD_URL_INVALID下载地址不是 HTTPS(src/providers/native-skill-service.mjs:288)改 HTTPS;开发环境才允许 localhost
云端 Skill 加载失败SKILL_MANIFEST_MISSING云端 Skill 缺 SKILL.md(src/skill-files.mjs:35)重新打包并上传
Skill 调用中途失效SKILL_AUTHORIZATION_EXPIREDSkill Service 请求授权过期(native-skill-service.mjs:152)重新发起该轮请求
工具目录搜不出结果RESOURCE_CATALOG_TOO_LARGE目录过大,被要求缩小范围(src/native-tool-catalog.mjs:56)加关键词缩小搜索
资源总览只显示一部分RESOURCE_OVERVIEW_TRUNCATED总览只展示该类前 200 项(src/resource-catalog.mjs:87)去「模型与工具」页搜索完整目录
托管资源请求被拒MANAGED_RESOURCE_PERMIT_REQUIRED托管记忆请求缺少可信业务授权(src/managed-resource-context.mjs:4)从带授权的入口重发
删不掉托管 RuntimeMANAGED_RUNTIME_REQUIRED只支持删除经 AgentEngine API 创建的 ManagedRuntime(agents.mjs:81)到控制台删除外部创建的实例
删除后云端还在MANAGED_RUNTIME_DELETE_UNCONFIRMED云端未确认删除(agents.mjs:86)刷新云端列表核对,必要时重试
部署记录写失败DEPLOYMENT_STORE_IO_FAILED记录目录不可写(同步盘、网络主目录、安全软件拦截,src/deployment-store.mjs:16)把 AGENTKIT_HOME 指向本机磁盘

云端与部署

症状错误码原因处理
云资源页空CLOUD_CONFIGURATION_REQUIRED云端凭证未配置(src/remote/control-client.mjs:439)配置云端凭证后刷新资源目录
切执行权限被拒CLOUD_EXECUTION_MODE_UNAVAILABLE云端执行权限尚未启用(agents.mjs:112)先在部署侧开启该权限
同上,镜像不支持CLOUD_EXECUTION_MODE_UNSUPPORTED当前云端镜像不支持切换执行权限(agents.mjs:115)更新实例镜像版本
权限超范围CLOUD_EXECUTION_MODE_DENIED请求的权限超出部署声明范围(agents.mjs:118)收敛到部署声明的上限内
权限值非法CLOUD_EXECUTION_MODE_INVALID不是 read-only/workspace-write/danger-full-access(src/cloud-execution-modes.mjs:42)用枚举值
云端发图失败CLOUD_IMAGE_INPUT_UNAVAILABLE云端镜像尚不支持图片输入(dsh-runtime.mjs:834)改用本地 Agent 处理图片
回答内容前后不一致CLOUD_STREAM_ITEM_CHANGED云端已结束的消息内容发生变化(dsh-runtime.mjs:480)以最终快照为准;不断重放则报 issue
更新卡在中间DEPLOYMENT_UPDATE_INTERRUPTED更新在提交云端前中断(src/deployment-rollouts.mjs:167)刷新确认原实例状态后重新检查版本

会话与历史

症状错误码原因处理
打开会话报不存在SESSION_NOT_FOUNDSession 已被删除或不属于当前 Host(src/host/routes/sessions.mjs:27)回智能体面板重新进入
导出被拒SESSION_EXPORT_TOO_LARGE会话日志超过 8 MiB(sessions.mjs:29)从原生会话用 /export 导出完整 ZIP
导出不可用SESSION_EXPORT_UNAVAILABLEDSH Session 持久化不可用(sessions.mjs:23)检查 Host 的持久化目录权限
图片打不开STUDIO_IMAGE_ATTACHMENT_UNAVAILABLE无法读取会话图片(src/providers/dsh-messages.mjs:29)确认 DSH 附件服务已启用
审批状态读不到无固定码原生审批 RPC 失败(src/client/dsh/native-approval.mjs)按提示「刷新」后重新核对原生运行状态

还是没解决

带上帮助总览里列的六项信息开 issue。如果是「这本来就不支持」,先看已知限制。

本页导航