端口 3080 被占用导致 DSH 启动失败怎么办？

换端口启动，执行 dsh --profile web --port 8080。--port 是 Web 应用的参数，跟在 profile 后面。

DSH plugin 装完不加载是什么原因？

先核对插件兼容的 DSH 版本；再看是不是 git 托管插件被 allowBuilds 拦住，把允许 key 写进 profile 的 pnpm-workspace.yaml 重新安装。

DSH 模型连不上怎么排查？

在设置→模型里确认 API Key 已保存，保存后模型路由立即生效；自定义端点走 OpenAI 兼容配置，参考官方 providers 文档。

DSH 的配置在哪里查看？

执行 dsh --dump-config 查看组合后的配置树，dsh --dump-default-config 看默认值，配置文件在 $DSH_HOME 下。

DSH 的会话数据存在哪？

会话记录在 ~/.dsh/sessions/ / /session.jsonl，排查或恢复前先备份这一份。

DSH 常见问题排查：端口 3080 占用、插件不加载、模型连不上、Web UI 空白怎么办

DSH 新手最常卡在四件事上：端口 3080 被占用、插件装完不加载、模型连不上、Web UI 打不开。逐个排查就能解决。

端口 3080 被占用（DSH 启动失败）

默认端口被占就换一个端口启动。 --port 是 Web 应用自己的参数，跟在 profile 后面：

bash

dsh --profile web --port 8080

dsh web 是 --profile web 的别名，默认开在 http://127.0.0.1:3080（来源）。启动时留意命令打印的访问地址，别用错端口。8080 也被占用就再换一个数字，只要端口不冲突，DSH 没有其他限制。

DSH plugin 装完不加载

插件装了不生效，先核对兼容版本，再看构建脚本放行。 排查顺序：

到插件详情页看它兼容的 DSH 版本，DSH 是开发者预览（当前 0.1.0-rc.6），版本不匹配可能静默失败。
git 托管的 DSH plugin 首次安装可能被 pnpm 的 allowBuilds 拦住，把报错里的允许 key 写进 profile 目录的 pnpm-workspace.yaml，重新执行 add。
确认安装命令没写错，比如 dsh plugin --profile web add github:ccch1mneyyy/dsh-tui 这类命令要完整复制（来源）。

排查插件问题最有效的办法是先执行 dsh --dump-config，看插件到底加载了没有，再决定改配置还是重装。

DSH 模型连不上

模型不通，九成是 API Key 没配好。 打开 Web UI 的设置 → 模型，输入 DeepSeek API 密钥保存，模型路由立即生效、不用重启（来源）。Key 填错、额度用尽也会表现为连不上。自定义端点走 OpenAI 兼容配置，参考官方 providers 文档。

模型配好后，正常流程是：选择工作区 → 输入任务 → agent 开始干活。agent 能读取和编辑工作区文件、运行命令、委派子任务并维护执行计划；当某个操作在当前权限策略下需要审批时，Web UI 会先弹出询问、等你确认再继续。所以任务"卡住没反应"时，先看是不是在等审批，别急着杀进程。

DSH Web UI 空白或打不开

页面空白先确认进程真的在跑、地址没敲错。 其次看工作区：新的 Web UI 在添加工作区前不会选中任何工作区，需要先点选择工作区加入项目目录，会话输入框才可用（来源）。整个首次使用流程是：设置 → 模型填好密钥 → 选择工作区 → 输入任务运行 → 之后随时回到已存会话继续使用。任一步没做，UI 看起来都像"坏了"。URL 也核对一下是不是 http://127.0.0.1:3080，别连着旧端口不放。

DSH 数据与配置排查

怀疑配置或数据有问题，先用命令看，再动文件。 执行 dsh --dump-config 看组合后的配置树、dsh --dump-default-config 看默认值——这两个命令不用启动 DSH 就能直接查看组合树（来源）。会话数据在 ~/.dsh/sessions/<项目>/<会话>/session.jsonl，排查前先备份。这些命令都正常的话，问题多半出在工作区或权限上，留意 Web UI 的权限提示再动手。

Web UI 一直打不开、任务又急着跑，可以直接走 headless 模式：执行 dsh --profile headless "你的任务"，DSH 会新建一个会话、跑完把最终答案打印到终端然后退出，全程不依赖浏览器（来源）。还搞不定，回看《DSH plugin 怎么安装》确认装法，或到 dsh-plugin.org 找对应插件的说明。

来源：官方 Quickstart、dsh CLI README