`dsh web` 已启动,模型却不通:先判断是 profile 选错还是密钥未配置

简介: Profile 是「一组有名称的插件配置」,不是模型名,也不是权限预设。选错 profile、把 `sdk-minimal` 当成 `sdk` 的别名、误以为 `dsh web` 和完整写法对应两套配置,或指望选择 profile 时顺便验证密钥,都会让「启动成功」与「可用」之间出现明显落差。本文梳理四项独立判断,并按「选哪个、怎么写、首次启动创建什么、配置何时生效」展开,附五个内置 profile 的接口对照表。

dsh web 启动成功,页面也能打开,但一发请求就不通。 这类问题中,「启动」和「可用」是两件事,中间至少隔着四个独立判断。

先把最容易混淆的一点说清楚:

Profile 是一组有名称的插件配置,不是模型名称,也不是权限预设。

官方参考说明 profile 保存的是组合包列表和用户补丁;CLI 参考说明内置启动方式和输入通道。因此,「我选了 web,为什么模型不能用」这个问题把两件事混在了一起:选择 profile 决定的是使用哪套插件组合、走哪个接口,模型和凭据则需要另外配置。

一、按接口选择五个内置 profile

需求 Profile 接口和边界
在浏览器里交互 web Web 应用与浏览器客户端
脚本执行一次任务 headless 位置参数传任务,标准输出给最终文本
SDK 客户端集成 sdk 标准输入输出承载 JSON-RPC
ACP 客户端集成 acp 标准输入输出承载 ACP
更小的 SDK 组合 sdk-minimal 同为 JSON-RPC,能力和权限不同

选择时看由谁发起交互:是人通过浏览器操作、脚本执行一次任务,还是协议客户端发起调用。

sdk-minimal 不是 sdk 的别名

表中这一项需要特别留意。CLI 参考说明,sdk-minimal 使用独立的组合包,并且:

  • 省略文本文件系统工具;
  • 省略指令发现;
  • 省略 SQLite;
  • 配置树固定为 danger-full-access;
  • 不挂载审批或权限设置服务。

也就是说,它「同为 JSON-RPC,但能力和权限都不同」。名字里的 minimal 容易让人以为它只是「更轻量的同一个东西」,实际上少掉的是能力,多出来的是权限,选择前需要把这两点都核对清楚。

二、dsh web 是简写,不是另一套配置

简写的规则

  • dsh web 就是 dsh --profile web,两种写法选择的是同一个名称;
  • 简写名称必须紧跟 dsh;
  • plugin 在这个位置表示插件管理命令,所以名为 plugin 的 profile 只能用 --profile 选择;
  • 简写之后再给一个 --profile 会被拒绝。

参数怎么分流

启动器先处理自己的参数;遇到第一个不认识的参数后,会把剩余参数原样交给应用。

例如 dsh --profile web --port 8080:--port 8080 会交给 Web 应用。因此,使用 --patch 这类启动器参数时,要放在应用参数之前。

下面两种查帮助的写法也要区分:

  • dsh --help——查看启动器帮助;
  • dsh --profile web --help——查看 Web 应用帮助,且不会启动应用。

两种写法不会产生两套配置

这一点能省去不少排查:自定义 profile 即使包含 Web 组合包,也可能因为组合包列表和补丁不同而表现不同。所以,不能只凭名称判断 profile 里到底有什么。同名不等于同内容。

三、首次启动创建了什么

首次使用时,web、headless、sdk、sdk-minimal 和 acp 会根据随包模板自动初始化。

  • 选中的 profile 位于 $DSH_HOME/profiles/<name>;
  • manifest 记录组合包层;
  • profile 自己的 cordis.patch.yml 保存用户覆盖;
  • 随包组合包从当前 dsh 安装解析,启动器不会为运行时解析创建回退链接。

两个容易踩的边界

  1. 普通启动时,如果自定义 profile 不存在,会报错并提示插件管理途径,不会自动把它当作 web。因此,输入 --profile foo 后不会静默进入 web;如果看到报错,就说明没有 fallback。
  2. --from-default-profile 会用新模板替换自定义目标;成功替换时,旧依赖和用户补丁也会被删除。

第 2 条是这里唯一有破坏性的操作。普通首次启动不需要使用这个选项;如果确实要用,请先阅读参考并保存必要内容。

四、五步判断「到底通不通」

  1. 确认交互方:是人、单次脚本,还是协议客户端。
  2. 按对应语法启动:浏览器场景用 dsh web;单次任务可用 dsh --profile headless "run the tests"。
  3. 为该环境配置模型和凭据。选择 profile 不会验证密钥,这是「启动了但不通」最常见的原因。模型相关配置见配置模型与提供商。
  4. 用小任务验证接口。SDK 和 ACP 需要通过相应的协议客户端连接,不要把普通任务文本直接写进协议流。
  5. 结果异常时,记录 profile 和启动目录。基于 base 的 profile 默认以运行命令的目录作为工作区根目录。

第 5 条可以结合启动前先选工作区理解:工作区根目录由启动位置决定,而不是由「安装了哪个插件」决定。

五、配置变更什么时候才会生效

配置层级顺序如下:

profile 所列组合包
→ profile 补丁
→ home 补丁
→ 命令行补丁

后面的层可以替换整行配置。

这里有一个模板级的差异:

  • Web 模板包含实时补丁能力;
  • 随包的 headless、SDK 和 ACP 模板在启动时应用补丁。

而组合包成员发生变化需要重启。完整的顺序和替换语义见配置层优先级。

三个「不一定」要记住

  • 不同 profile 可以挂载不同插件,某个界面里的设置不一定存在于另一个 profile;
  • profile 补丁不是所有 profile 共用的 home 补丁;
  • 但 home 偏好可能影响多个 profile。

插件设置可能要到下一个请求或重启时才生效,具体以对应文档为准。

六、团队交接时该记录什么

只记录 profile 名称不够,还要说明由谁使用哪个接口:

  • 浏览器流程:Web UI 运行在哪台主机、谁可以访问;
  • headless 流程:工作目录是什么、输出由谁接收;
  • SDK / ACP 集成:哪个客户端负责协议流。

例如,开发者可以先在本机仓库中选择 web、配置好模型,再通过浏览器观察结果;CI 中的有限任务可以选择 headless,并把退出状态和文本分别保存。

两种选择都不会替对方决定模型提供商——它们各自仍需要有效的路由和凭据。

如果程序需要持续的多轮协议交互,应评估 SDK 接口,不要把单次任务输出硬当成协议服务。

七、别被「同名 profile」骗了

profile 首次从模板初始化后,可能积累本地修改。排查时要分清三件事:

  1. 随包模板;
  2. 磁盘上现有的 profile;
  3. 某次启动最终组合出来的配置树。

升级应用并不意味着已有 profile 一定恢复成原始模板。 正确的排查顺序是:先确认选中的名称,再检查组合包列表与补丁,最后再决定是否修改;不要为了查看模板内容而直接覆盖已有目录。

两台机器即使使用同名 profile,也可能安装了不同插件,或存在本机覆盖。比较问题时,先固定版本和配置来源,避免把「名称相同」误认为「运行内容相同」。

交接时还可以说明:进程如何停止、日志由谁保管、分享前需要删除哪些信息。新维护者据此更容易区分浏览器连接问题、模型请求失败和权限问题。这三类现象看起来都是「用不了」,但对应的排查位置完全不同。

八、一份可复用的验收记录

记录以下五项即可:

  1. 启动命令;
  2. 所在目录;
  3. 选择的模型;
  4. 测试输入;
  5. 观察到的结果。

分别验证三条路径:

  • Web:先确认页面连接的是预期服务,再发起一次小型模型请求。只看到页面不代表模型可用。
  • headless:确认调用方分别收到最终文本与退出状态。
  • 协议客户端:确认客户端能识别所选传输,并能处理连接错误。

启动成功只能证明这次组合启动了,不能证明每个模型、工具或外部集成都已准备好。

九、端口和帮助这两个常见收尾

这些都是确定要用哪种方式之后再处理的事项。先确定交互方式,再调整参数;否则可能会在本来就不合适的 profile 上花很多时间。

十、边界说明

  • Profile 不是模型名,也不是权限预设;选择 profile 不会验证密钥。
  • sdk-minimal 不是 sdk 的别名:能力更少,权限固定为 danger-full-access 且不挂载审批服务。
  • 同名 profile 不代表同内容,两台机器、两个环境都可能不同。
  • --from-default-profile 会删除旧依赖和用户补丁,不是无害的查看操作。
  • 升级应用不会把已有 profile 恢复成模板。
  • 以上为操作建议,不是额外的 CLI 承诺;具体行为仍以安装版本和实际组合的插件文档为准。

十一、相关术语

  • Profile:一组有名称的插件配置,保存组合包列表与用户补丁。
  • 组合包(bundle):由 profile 声明、从当前 dsh 安装解析的插件层。
  • 补丁(patch):覆盖组合配置的层,按 profile → home → 命令行顺序应用。
  • 启动器:处理自己的参数后,把剩余参数交给应用的那一层。

相关阅读

本文依据 DeepSeek Harness 官方参考总览与 CLI 参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog

目录
相关文章
|
18天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
8131 58
|
3天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1552 1
|
6天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
19天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5736 69
|
6天前
|
云安全 人工智能 安全
|
13天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2962 9
|
6天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
3天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
2430 0
|
11天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1893 1

热门文章

最新文章