常见问题 FAQ

新手最常踩的坑集中营：npx 卡住、端口占用、MISSING_CREDENTIAL、插件装完没反应、数据迁移……按类速查。

约 7 分钟读完

使用说明

这里收集了新手最常踩的坑。按"安装、模型、插件、其他"分成四类，遇到问题先对号入座；没找到答案的话，可以去 DSH 官方 Discussions 提问，社区响应很快。

安装相关

node -v 有版本，但 npx 启动报错？

最常见的两种情况：

  • 版本低于 22：DSH 要求 Node.js 22 或更高。去 nodejs.org 装最新的 LTS 版，装完重开终端；
  • 报 command not found: npx：Node.js 没装成功或没进 PATH。重开一个终端窗口再试；Windows 用户注意用"PowerShell"而不是老的"命令提示符"。

npx 下载特别慢或卡住？

网络问题。给 npm 换国内镜像源（一次配置，永久生效）：

npm config set registry https://registry.npmmirror.com

然后重新运行 npx @deepseek-ai/dsh web。

浏览器打开 127.0.0.1:3080 显示无法访问？

按顺序检查：

  1. 跑 dsh 的终端窗口还开着吗？关了窗口服务就停了；
  2. 终端里有没有红色报错？有就先解决报错；
  3. 端口被占了？换个端口启动：dsh web --port 3081，浏览器访问 127.0.0.1:3081。

杀毒软件弹出警告正常吗？

正常。dsh 需要在本机开一个端口提供网页服务，部分杀毒软件会询问。选择"允许"即可——DSH 只监听本机回环地址，不会向外部网络开放任何东西。

模型相关

提示 MISSING_CREDENTIAL 怎么办？

就是没填 API Key。打开 设置 → 模型，在 DeepSeek 卡片里粘贴 Key 并保存。保存后不用重启，直接重发刚才的问题即可。

报 401 或"余额不足"？

  • 401：Key 抄错了或已作废。回平台重新复制一遍，注意别多复制空格；
  • 余额不足：DeepSeek API 是预充值模式，去 platform.deepseek.com 充值后重试。

能用网页版那个免费额度吗？

不能。网页版 DeepSeek 和开放平台的 API 是两套体系：前者在 chat.deepseek.com 上消费，后者按 token 计费、需要充值。DSH 走的是 API 这套。好在价格很低，轻度使用一个月通常也就几块钱。

想用其他公司的模型可以吗？

可以，DSH 是模型无关的。设置 → 模型 → 添加提供方（选厂商）或添加自定义提供方（填 OpenAI 兼容接口地址 + Key）。详见配置模型教程。

插件相关

插件装完没反应？

九成是没重启。安装/卸载/升级插件后，必须停止 dsh（终端 Ctrl + C）再启动（dsh web），插件才会加载。浏览器再刷新一下页面。

安装时报 prepare / allowBuilds 错误？

pnpm 的安全机制：默认拒绝在安装时执行陌生包的构建脚本。解决方法（详见安装插件教程）：

  1. 打开 ~/.dsh/profiles/web/pnpm-workspace.yaml；
  2. 按报错提示把包名加进 allowBuilds；
  3. 重新执行安装命令。

只给你信任的插件加授权。

插件之间冲突了怎么办？

症状通常是某个功能失灵或启动报错。排查思路：

  1. 回忆最近装了什么，先卸载它试试；
  2. 仍然异常就重置 profile（见下一条）；
  3. 重置前可以用 dsh plugin --profile web ls 把插件清单存一份，之后按需装回。

怎么把插件全部清空重来？

# 先退出 dsh，然后：
rm -rf ~/.dsh/profiles/web

下次 dsh web 自动重建干净的 web profile。你的 API Key 存在 ~/.dsh/.credentials.yaml，不受影响，无需重填。

其他

我的对话记录存在哪？能迁移电脑吗？

全部在 ~/.dsh 目录里（Windows 是 C:\Users\你\.dsh）。把整个目录拷到新电脑的相同位置，记录、配置、密钥就都过去了。迁移前记得先退出 dsh。

DSH 是免费的吗？

软件本身 MIT 协议开源，完全免费。花钱的地方只有一处：调用模型的 API 费用，按用量计费。

和 Claude Code、Codex 这类工具是什么关系？

它们都是"AI 编码智能体"，定位类似。DSH 的差异点是一切皆插件的开放架构——模型、工具、界面都能换，你可以完全按自己的需求组装，而不是接受厂商给定的黑盒。如果你喜欢折腾、想要完全掌控自己的 AI 工具链，DSH 值得一试。

去哪里反馈 bug、交流经验？

教程导航

全部教程