在把 DeepSeek Harness 真正用起来之前，安装这一步看似简单，实则藏着不少岔路口：你是想三分钟内看到 Web 界面，还是准备读源码写插件，抑或想在自己的 Python 程序里调用 Agent？三条路径对应三套完全不同的前置条件与产出物，选错方向往往会卡在 Node 版本、pnpm 缺失或者找不到入口命令上。这篇文章会用一张表、若干条自检命令和可粘贴的实操代码，把 npx 即用、全局安装与源码构建这三种方式讲透，并顺带把 Python SDK 的安装链路收进视野。读完上半段，你应该能明确自己该走哪条路，并且知道第一步敲下什么命令。
安装前先跑通三条自检命令：node -v、git --version 与 Python 3.10+
DeepSeek Harness 的运行时是建立在 Node.js 之上的，这一点决定了绝大多数安装路径都绕不开 Node 环境。但三种方式对前置依赖的要求并不一致：npm 一键安装只需要 Node 本身，属于官方推荐的开箱即用路径；源码方式额外要求 Git 与 pnpm；Python SDK 则完全不需要系统提供 Node，因为它自带运行时。这些差异如果不在动手前搞清楚，很容易出现“命令敲了但报错，不知道缺什么”的困境。
所以第一步不是急着安装，而是做环境自检。第一件事是确认 Node 存在且版本够新。在终端执行 node -v，如果输出类似 v22.23.1 这样的版本号，说明 Node 已就绪；如果提示 command not found，就需要先去 Node 官网安装。素材中给出的经验值是 v20+，也就是 Node 大版本至少到 20，仓库的 package.json 里还会有自己的 engines 声明，构建阶段对版本的要求往往更严格，所以版本越高越稳妥。
第二件事是检查 Git。源码安装时这一步是硬性要求，因为克隆仓库本身就要靠 Git。执行 git --version，能打印出 git version 2.x 这样的信息即可。Git 在 npm 一键安装路径里是可选的，但有它在手，后续想切换成源码方式会顺畅很多。第三件事是确认 Python 版本，只有走 Python SDK 这条路时才需要，底线是 Python 3.10 及以上。可以用 python -m venv --help 试探 venv 模块是否存在，或者直接 python --version 看版本号，低于 3.10 的版本在后续创建虚拟环境或安装 SDK 时都可能出问题。
除了工具链，还有一项三种方式都需要的共同前置：DeepSeek API 密钥。它用于在启动后配置模型路由，同时也支持 OpenAI 兼容的端点。密钥本身不参与安装过程，但缺少它，即便安装成功、Web UI 打开，也无法真正让 Agent 跑起来。操作系统方面，Linux、macOS 与 Windows 都可以覆盖；Python SDK 对平台的要求更窄一些，支持 Linux x64 / arm64 与 macOS 14+（arm64）。
把这些前置条件整理成一张对照清单，能帮助你在动手前判断自己缺什么：
- npm 一键安装：必须有 Node.js；Git 可选；不需要 pnpm；不需要 Python；需要 API 密钥。
- 源码安装：必须有 Node.js；必须有 Git；必须有 pnpm；不需要 Python；需要 API 密钥。
- Python SDK：不需要系统 Node（SDK 自带运行时）；必须有 Git；不需要 pnpm；必须有 Python 3.10+；需要 API 密钥。
这里有一个容易被忽略的工程细节：pnpm 如果没有预装，可以用 npm install -g pnpm 一条命令补上，因为 npm 本身随 Node 一起安装，所以从“只有 Node”到“具备源码构建能力”，中间只差这一步。另一个细节是网络受限环境下的镜像配置，npm 与 pnpm 都可以通过镜像源解决拉包慢的问题，这在后面的排错部分还会再提到。
一张表看懂三种安装方式的产出差异：Web UI、构建产物与 deepseek_harness 包
选安装方式，本质上是在选“你最终想拿到什么”。同样是安装 DeepSeek Harness，npm 一键安装的终点是一个跑在浏览器里的 Web UI；源码安装的终点是一份本地仓库加完整构建产物；Python SDK 的终点则是一个可以在程序里 import 的 deepseek_harness 包。三者不是竞争关系，而是面向三种完全不同的使用目标。
先看 npm 一键安装。它面向的是绝大多数只是想快速体验 Web UI 的用户。安装完成后的产出很直接：启动一个 Web 界面，默认地址是 http://127.0.0.1:3080。你不需要关心 TypeScript 入口在哪、前端产物怎么打包，dsh 会把这些都藏在幕后。对于第一次接触 DeepSeek Harness、只想看看它能做什么的人，这是阻力最小的路径。
再看源码安装。它的适用人群是明确的开发者：想开发插件、想阅读源码、想参与贡献。产出物是一份克隆下来的本地仓库，加上 pnpm run build 生成的完整构建产物。源码方式还有一个别处没有的能力——可以直接用 pnpm dsh 运行 TypeScript 入口，不需要先编译成 JavaScript 再执行。这意味着你改完源码可以立刻验证行为，对插件调试尤其关键。
最后是 Python SDK。它服务的是想在自己的 Python 程序里调用 Agent 的场景。产出一个 deepseek_harness 包，并且自带运行时，不依赖系统安装的 Node。这一点对很多数据科学或后端团队的机器很重要：他们未必愿意为了一个 Agent 去维护 Node 环境，而 SDK 把运行时打包进来，等于把依赖问题内部消化了。代价是平台支持范围收窄，需要用 Linux x64 / arm64 或 macOS 14+（arm64）。
把这三条路径放在同一张表里对比，选择就一目了然了：
| 对比维度 | npm 一键安装（推荐） | 源码安装（开发） | Python SDK（程序化） |
|---|---|---|---|
| 适合谁 | 绝大多数用户，想最快体验 Web UI | 想开发插件、阅读源码、参与贡献 | 想在自己的 Python 程序中调用 Agent |
| 核心前置依赖 | Node.js（Git 可选） | Node.js + Git + pnpm | Python 3.10+、Git |
| 是否需要系统 Node | 需要 | 需要 | 不需要，SDK 自带运行时 |
| 最终产出 | 启动 Web UI，默认 http://127.0.0.1:3080 | 本地仓库 + 完整构建产物，可用 pnpm dsh 直接运行 TypeScript 入口 | deepseek_harness 包 + 内置运行时 |
| 典型命令 | npx @deepseek-ai/dsh web 或 dsh web | pnpm dsh web | python -m pip install deepseek-harness-sdk |
| 后续可扩展方向 | 配置模型、选择工作区、跑任务 | 写插件、看完整配置树、参与开发 | 在 Python 代码中 import 调用 |
读这张表时可以抓住一个判断标准：你是否需要修改 DeepSeek Harness 本身。如果答案是不需要，只想要一个能用的界面，那 npm 一键安装就够了；如果你需要改代码、写插件、看配置细节，那就必须走源码；如果你的宿主环境是 Python 程序且不想引入 Node，那就选 SDK。三条路径之间也不是割裂的——先通过 npm 方式建立对产品的直觉，之后按需切换到源码方式，是很多开发者的实际路径。
npx @deepseek-ai/dsh web 快速体验：首次运行如何自动初始化 web 配置模板
如果你想在不污染全局环境的前提下先看一眼 DeepSeek Harness，npx 是最省事的入口。它本质上是“临时下载并执行”，不需要事先全局安装任何包。整条命令只有一段：
npx @deepseek-ai/dsh web
执行这条命令后，npx 会解析 @deepseek-ai/dsh 这个包，把它拉取到本地缓存并运行，参数 web 指定启动 Web 界面。这里第一个关键行为是：首次运行会自动初始化 web 配置模板。也就是说，你不需要提前手工创建任何配置文件，dsh 会替你把 web profile 需要的配置骨架准备好，后续的模型设置、工作区选择才有地方落。
第二个关键行为是它会在终端打印访问地址，默认是 http://127.0.0.1:3080。注意这个地址绑定在 127.0.0.1 上，也就是只有本机可访问，这对开发期的安全是合理的默认值。如果你看到端口 3080 被别的程序占用了，可以换一个端口启动，例如把参数改成 --port 8080，前提是启动参数要放在应用参数之前，这点在后面的 profile 说明里会再展开。
验证是否成功的方法很直观：打开终端里打印出来的地址，能看到 DeepSeek Harness 的 Web 界面，就说明安装启动这条链路已经打通。不过这里有一个新手常踩的坑——新的 Web UI 在添加工作区之前，不会选中任何工作区，界面看起来像是“不可用”的状态。这并不是安装失败，而是正常现象，下一步配置工作区之后它就会恢复可用。
还有一个小贴士值得提前记住：dsh 会把调用目录作为默认文件系统位置。这意味着你执行 npx 命令时所在的目录，会被当作默认的文件系统位置。所以更聪明的做法是先 cd 到你的项目目录，再执行 npx @deepseek-ai/dsh web，这样后面选择工作区时会最方便，不用再手工去添加一个离得很远的路径。
下面把 npx 快速体验的完整流程压缩成一段可直接复制的操作序列，包含切换目录、启动、以及在端口冲突时的替代写法：
# 1. 先确认 Node 环境
node -v
# 期望看到类似 v22.23.1 的输出
# 2. 进入你的项目目录（这一步会让 dsh 把当前目录当作默认文件系统位置）
cd ~/projects/my-app
# 3. 免安装快速体验，首次运行会自动初始化 web 配置模板
npx @deepseek-ai/dsh web
# 终端会打印默认访问地址：http://127.0.0.1:3080
# 4. 如果 3080 端口被占用，换端口启动
npx @deepseek-ai/dsh web --port 8080
需要说明的是，npx 方式虽然方便，但它是临时性的：每次执行都可能去解析并拉取包，对于需要频繁启动的人来说不如全局安装来得稳定。它最适合的场景是“我还没决定要不要长期用，先跑起来看看”。一旦你确认会持续使用，就应该考虑下面要讲的全局安装。
npm install -g @deepseek-ai/dsh 全局安装后，dsh web 与 npx 方式的取舍
如果你已经决定长期使用 DeepSeek Harness，全局安装会带来一个 npx 给不了的东西：一个稳定可用的 dsh 命令。安装命令只有一行：
npm install -g @deepseek-ai/dsh
这里的 -g 表示全局安装，包会被放进全局的 node_modules 目录，对应的可执行文件会被链接到系统的 PATH 里。安装完成后，你不再需要 npx 前缀，直接输入 dsh web 就能启动 Web 界面。从行为上看，dsh web 与 npx @deepseek-ai/dsh web 是等价的，二者都会启动 Web UI，区别在于前者复用了本地已安装的版本，后者每次都可能去解析远程包。
这种等价关系意味着迁移成本几乎为零：你之前用 npx 试过的所有参数，换成 dsh 前缀后依然适用，例如 dsh --profile web --port 8080 就是换端口启动的写法。理解命令结构对排错很有帮助——dsh 自身的启动参数放在前面，应用侧的参数放在后面。--profile web 属于 dsh 的 profile 选择，--port 8080 才是 Web 应用自己的参数。如果把顺序写反，参数可能被解释到错误的层级，出现“看起来设置了却没生效”的困惑。
那么什么场景下应该继续用 npx，什么场景下应该全局安装？可以这样划分：
- 用 npx 的场景：初次尝鲜、临时在别人的机器上跑一下、不想在全局留下任何安装痕迹、只是想验证某个参数的效果。
- 用全局安装的场景：日常开发主力使用、需要写脚本或 CI 中反复调用、希望锁定某个已经验证过的版本、想用 dsh 的子命令体系（例如查看配置、管理插件）。
全局安装还有一个隐性优势：命令名从一长串包名缩短成了 dsh，这在需要组合多个子命令时会显著降低输入负担。常见子命令包括用 headless profile 一次性跑任务、用 --dump-config 查看完整配置树、用 plugin 子命令管理某个 profile 的插件等。这些都在下面源码方式的小节里会具体展开，但即便你走的是 npm 一键安装路径，只要记熟了 dsh 这个前缀，也能随时调用它们。
启动目录即默认文件系统位置：为什么建议先 cd 到项目目录再执行命令
这是整个安装环节里最容易被轻视、却在后续使用中反复被感知的一条规则：dsh 会把调用目录作为默认文件系统位置。换句话说，你在哪个目录下敲下启动命令，那个目录就会成为后续工作区的默认候选。它不是随机选的，也不是固定选用户主目录，而是严格跟随你执行命令时的当前工作目录。
理解这条规则之后，很多“为什么我的 Agent 看不到我的文件”的问题就迎刃而解了。假设你在用户主目录下直接执行 npx @deepseek-ai/dsh web，那么默认文件系统位置就是主目录；等你进到 Web UI 里要选择工作区时，需要添加的其实是你的项目目录。反过来，如果你先执行 cd ~/projects/my-app，再启动 dsh，那么调用目录就是 my-app，后续选择工作区时它会出现在最顺手的位置，几乎不需要额外操作。
这条规则的工程价值在于“减少一次配置动作并降低出错概率”。工作区这个概念在 DeepSeek Harness 里是有实际权限含义的，权限策略会围绕工作区来划定 Agent 能访问的文件范围。如果你一开始就把工作区选对，后续的读写、执行命令都会落在预期范围内；如果选错，可能会遇到 agent 试图访问工作区之外文件而被拦下的情况。因此建议把“先 cd，再启动”当成一条习惯性动作。
还有一点值得提前布局：尽早创建一个专门用来放项目的目录。素材里给出的做法是新建一个 DeepSeekProjects 目录作为工作区。这不是强制要求，但它让“哪个目录是给 Agent 用的”这件事在文件系统层面就变得清晰，避免 Agent 在你的主目录里到处翻。你可以先建好它，再 cd 进去启动：
# 创建一个专门给 Agent 用的项目目录
mkdir -p ~/DeepSeekProjects
# 进入它，让 dsh 把它当作默认文件系统位置
cd ~/DeepSeekProjects
# 之后无论用 npx 还是全局 dsh，启动目录都已经正确
npx @deepseek-ai/dsh web
# 或者：dsh web
到这里可以小结一下“目录决定默认位置”的连锁影响：启动目录决定了默认文件系统位置，默认文件系统位置决定了工作区选择的便利程度，工作区又决定了权限边界内 Agent 能做什么。三步环环相扣，所以把 cd 这一步提前，是最省成本的优化。
源码安装四步走：git clone、pnpm install、pnpm run build、pnpm dsh web
当你从“使用者”转向“开发者”角色，源码安装就是必经之路。它适合想开发插件、阅读源码或参与贡献的人。整个流程可以概括为四个按顺序执行的步骤：克隆仓库、安装依赖、构建产物、以源码方式启动。顺序不能乱，尤其是构建必须发生在启动之前，否则会缺生产运行所需的包与前端产物。
第一步是克隆仓库，目标地址是 https://github.com/deepseek-ai/deepseek-harness.git。克隆完成后进入仓库目录，此时你拿到的是完整的源码树。第二步是安装依赖，命令是 pnpm install。这一步依赖 pnpm，如果你机器上还没有它，可以先执行 npm install -g pnpm 把它装上。pnpm 在这个项目里的角色不只是“更快的包管理器”，它还承担了 profile 目录下的插件管理工作，所以源码路径几乎离不开它。
第三步是构建，命令是 pnpm run build。这一步负责把包与前端产物都构建出来，官方注释明确写着“生产运行需要”。也就是说，如果你跳过构建直接启动，可能拿不到完整的运行产物，前端页面可能加载不出来，或者某些包未被正确编译。把构建理解为“把源码翻译成可以生产运行的形态”，就不会觉得多此一举了。第四步是启动，命令是 pnpm dsh web。注意这里用的是 pnpm dsh 而不是全局 dsh，它走的是仓库内的 TypeScript 入口，不需要你先把源码编译成全局命令，这正是源码方式的便利所在。
把四步合并成一段可复制的命令序列，就是：
# 1. 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# 2. 安装依赖（需要 pnpm，可用 npm install -g pnpm 安装）
pnpm install
# 3. 构建包与前端产物（生产运行需要）
pnpm run build
# 4. 以源码方式启动 Web UI
pnpm dsh web
源码安装过程中最常见的失败点是构建阶段。素材给出的排错方向有三条：确认 pnpm 已安装；网络受限时为 npm / pnpm 配置镜像源；以及确认 Node.js 版本满足仓库 package.json 中 engines 声明的要求。第三条尤其值得注意——很多构建报错的根因不是代码问题，而是 Node 版本过低，导致某些语法或工具链无法运行。因此哪怕前面的 node -v 显示有版本号，也要对照 engines 声明确认它够不够新。
另外要区分“源码安装”和“源码运行”这两个概念。安装阶段产出的是本地仓库与构建产物；运行阶段则可以选择不同的 profile，比如用 pnpm dsh web 起一个 Web UI，或者用后面的 headless profile 跑一次性任务。同一份源码，可以支撑多种启动形态，这也是源码方式比 npm 一键安装更灵活的地方。
源码方式的两个隐藏入口：pnpm dsh --profile headless 与 --dump-config
源码运行时，除了 pnpm dsh web 这条主入口，还有两个常被忽略但非常好用的入口。它们分别解决两类问题：一类是“我想让 Agent 跑一次任务然后直接拿到答案”，另一类是“我想知道这次启动到底加载了哪些配置”。对插件开发者来说，后者几乎是日常必备。
第一个入口是 pnpm dsh --profile headless "run the tests"。这个 profile 的行为是：一次性运行一个任务，打印最终答案后退出。它不启动常驻的 Web 服务器，适合放进脚本或 CI 流程里。引号里的内容就是任务描述，你可以替换成任意指令。相比 Web UI 的交互式会话，headless 模式更接近“命令行里的 Agent”，输出干净、退出明确，不会留下一个需要手工关闭的服务进程。
第二个入口是 pnpm dsh --profile web --dump-config。它的作用是查看实际启动的完整配置树，而且不启动服务器。这对开发插件的意义在于：插件最终会被配置树里的插件条目加载，搞清楚配置树长什么样，才知道自己的插件被挂在哪一层、拿到了哪些参数。与之配套的还有一个 --dump-default-config，用来查看默认配置树，也就是不包含用户 patch 的版本。两者对比，就能看出用户的覆盖动作具体改了什么。
把这两个入口放到一个命令清单里，方便对照使用：
# 一次性运行任务并打印最终答案（适合脚本 / CI）
pnpm dsh --profile headless "run the tests"
# 查看实际启动的完整配置树（不启动服务器，插件开发常用）
pnpm dsh --profile web --dump-config
# 查看默认配置树（不含用户 patch），与上面一条形成对照
dsh --profile web --dump-default-config
这里需要补充 profile 的初始化规则：web 与 headless 这两个 profile 会在首次使用时从内置模板自动初始化，也就是说你不需要手工创建它们就能直接用；其余 profile 则需要通过 dsh plugin 子命令来创建。这条规则解释了为什么上面两条命令可以开箱即用，而如果你尝试一个自定义的 profile 名，可能会先被要求创建它。
再强调一次参数顺序问题：dsh 的启动参数在前，应用参数在后。在 pnpm dsh --profile web --port 8080 中，--profile web 是给 dsh 的，--port 是给 Web 应用的。同理，--dump-config 属于 dsh 层面的开关，放在 profile 之后、应用参数之前的位置最稳妥。理解了这个分层，命令怎么写就不容易出错了。
Python SDK 安装链路：venv 隔离 + pip install deepseek-harness-sdk 自带运行时
如果你想让 DeepSeek Harness 跑在自己的 Python 程序里，而不是通过浏览器操作，Python SDK 就是目标路径。它的前置条件与前面两条明显不同：需要 Python 3.10+、需要 Git，还需要一个 DeepSeek 兼容的 API 端点与凭据，以及一个 agent 可以修改的隔离 workspace。注意最后这一条——因为 Agent 会在工作区里读写文件、执行命令，给它一个隔离的目录是良好的安全习惯。
安装链路的第一步是创建并激活虚拟环境。虚拟环境的意义在于把 SDK 及其依赖与系统 Python 隔离开，避免版本冲突。创建命令是 python -m venv .venv，激活命令在类 Unix 系统下是 . .venv/bin/activate。激活之后，后续的 pip 安装就会落在这个隔离环境里。第二步是安装 SDK 本身，命令是 python -m pip install deepseek-harness-sdk。这个包的特殊之处在于自带运行时，正常情况下不需要系统提供 Node；如果运行时报运行时缺失，通常意味着安装的包不完整，重新执行一次安装命令即可。
安装与配置凭据的完整流程可以直接复制下面这段：
# 1. 克隆仓库（SDK 相关示例也随仓库提供）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# 2. 创建并激活虚拟环境（需要 Python 3.10+）
python -m venv .venv
. .venv/bin/activate
# 3. 安装 SDK（自带运行时，不需要系统 Node）
python -m pip install deepseek-harness-sdk
# 4. 配置凭据
export DEEPSEEK_API_KEY=sk-your-key-here
# 如果模型不是默认 DeepSeek 端点，而是 OpenAI 兼容代理，还需设置：
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
凭据部分有三层信息值得拆开看。第一层是 DEEPSEEK_API_KEY，这是必填项，格式上以 sk- 开头。第二层是 DEEPSEEK_BASE_URL，它只在你不走默认 DeepSeek 端点、而是走 OpenAI 兼容代理时才需要，示例值是 http://127.0.0.1:8000/v1。第三层是 DSH_MODEL，用来指定模型名，示例值是 deepseek-v4-flash。这三者的关系是：API Key 决定你有没有资格调用，Base URL 决定调用发往哪里，模型名决定实际用哪个模型。
调用起点是 from deepseek_harness import DeepSeekHarness。这一行 import 就是整个 SDK 的入口。素材里提到，仓库内置的 examples/jsonrpc-agent/minimal.py 是 SDK 调用的轻量包装，可以直接参考；运行后会打印 assistant 的最终回复，同时会话目录会收到包含模型请求与工具调用的 JSONL 日志。JSONL 日志这一点很重要——它意味着每次调用都有结构化记录可查，调试 Agent 行为时不必靠猜。
把 SDK 路径与前面两条路径做个快速对照，可以更清楚它的定位：
- 与 npm 路径的共同点：都能驱动同一套 Agent 能力，都需要 API 密钥。
- 与 npm 路径的差异：SDK 不提供 Web UI，入口是 Python 代码而不是浏览器。
- 与源码路径的共同点：都需要 Git 来获取仓库，都可以参考仓库里的示例代码。
- 与源码路径的差异：SDK 自带运行时、不需要系统 Node，而源码方式强依赖 Node 与 pnpm。
平台限制需要再提醒一次：Python SDK 支持 Linux x64 / arm64 与 macOS 14+（arm64）。如果你的目标机器是别的平台组合，可能需要改走 npm 或源码路径，再通过其他方式对接。这个限制来自 SDK 自带的运行时，而不是 Python 语言本身，所以并不能通过升级 Python 版本绕过。
走到这里，三条安装路径的地图已经铺开：npx 负责零成本尝鲜，全局安装换来长期可用的 dsh 命令，源码构建打开插件与调试的大门，Python SDK 则把 Agent 能力嵌进你的程序。每一节都给了可执行的命令与判断依据，你可以先按自己的目标选一条落地，把第一个 Web UI 或第一次 import 跑通。环境确认、产出物选择、启动目录这些前置动作完成之后，真正的工作才刚刚开始——下一部分我们会进入安装后的第一次启动与配置：模型路由怎么填、工作区怎么选、四种运行模式与三档权限分别在什么场景下使用，以及遇到浏览器打不开、会话输入框不可用这类典型问题该怎么排查。
上一段我们把三条安装路径——npx 临时体验、npm 全局安装和源码构建——的取舍与操作讲清楚了，也确认了 Node.js、pnpm、Git、Python 这些前置条件各自服务于哪一种方式。现在进程已经能跑起来，接下来真正决定体验好坏的，是凭据怎么给、模型怎么配、权限怎么收这三件事。这一段就沿着首次启动的完整闭环往下走，把环境变量、Web UI 三步配置、运行模式、权限档位、提供方添加，一直到 2026 年 9 月最新的 settings.yaml 视觉模态声明，全部落到可复制的操作上。
凭据三件套：DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL 与 DSH_MODEL 的配置顺序
DeepSeek Harness 的模型路由插件在启动时要做一件事：知道“去哪问、用什么身份问、问哪个模型”。这三个问题的答案，分别对应三个环境变量。DEEPSEEK_API_KEY 是身份凭据，必填；DEEPSEEK_BASE_URL 是端点地址，只有当你用的不是 DeepSeek 官方端点时才需要补；DSH_MODEL 是默认模型名，同样只在走自建网关或代理、需要指定非默认模型时才涉及。
所以配置顺序上有一条很实用的原则：先只填 API 密钥，跑不通再加后两项。如果你直接使用 DeepSeek 官方端点，那么密钥之外的东西一概不用管，dsh 内置的目录已经知道端点地址与可用模型，路由开箱可用。只有当你把请求指向公司网关、本地 vLLM、One-API 之类的 OpenAI 兼容代理时，才需要把 baseURL 与模型名显式补上——因为这时 dsh 无法替你猜出端点在哪、模型叫什么。
环境变量的写法在 Linux/macOS 与 Windows 上略有差别，但语义一致：它们都是进程级的环境变量，dsh 启动时读取。下面是一段可以直接粘贴到终端运行的示例，同时演示了“只给密钥”和“用兼容代理”两种形态：
# ---- 形态一：走 DeepSeek 官方端点，只需要密钥 ----
export DEEPSEEK_API_KEY=sk-your-key-here
npx @deepseek-ai/dsh web
# ---- 形态二：走本地或自建的 OpenAI 兼容代理 ----
export DEEPSEEK_API_KEY=sk-your-key-here
export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
export DSH_MODEL=deepseek-v4-flash
npx @deepseek-ai/dsh web
# Windows PowerShell 下等价写法（仅形态一为例）
# $env:DEEPSEEK_API_KEY = "sk-your-key-here"
# npx @deepseek-ai/dsh web
这里有几个容易被忽略的工程细节。第一，baseURL 必须带协议与路径前缀，例如 http://127.0.0.1:8000/v1，而不是裸的 127.0.0.1:8000，否则协议层会先失败。第二，@deepseek-ai/dsh web 会以你执行命令时所在的目录作为默认文件系统位置，这也是为什么建议先 cd 到项目目录再启动——后面“选择工作区”时你会省很多事。第三，环境变量的命名是固定的三件套，如果你把密钥写成了别的名字（比如 DEEPSEEK_KEY），路由会直接报 MISSING_CREDENTIAL，而不会去猜你想表达什么。
还有一点值得提前说明：环境变量与 Web UI 里的“设置 → 模型”面板不是互斥的。环境变量适合脚本、CI、无头运行；Web UI 的输入框适合日常交互，且保存后是持久化的。两者同时存在时以实际保存的配置为准，所以如果你改了环境变量却发现行为没变，先回去看一眼设置页里是不是已经存了一份旧密钥。下面这张表把三件套的职责与必填性对齐一下，便于排查：
| 环境变量 | 作用 | 是否必填 | 典型取值 | 缺失时的表现 |
|---|---|---|---|---|
| DEEPSEEK_API_KEY | 提供方身份凭据 | 必填 | sk- 开头的密钥串 | MISSING_CREDENTIAL |
| DEEPSEEK_BASE_URL | 覆盖端点地址，指向 OpenAI 兼容代理 | 仅代理场景必填 | http://127.0.0.1:8000/v1 | 请求打到官方端点，代理不生效 |
| DSH_MODEL | 指定默认模型名 | 仅非默认模型需填 | deepseek-v4-flash | 可能命中 UNKNOWN_MODEL |
总结成一句可执行的顺序：先装密钥 → 启动 → 打开页面填一次密钥（持久化）→ 需要代理时再补 baseURL 与模型名。不要一上来就把三个变量全填满，那样一旦出错你很难判断是哪一层的问题。
首次启动三步走：设置 → 模型填密钥、选择工作区、发出第一个任务指令
浏览器打开终端打印的地址（默认是 http://127.0.0.1:3080）之后，整个首次使用其实就是一个三步闭环：配模型、选工作区、发指令。这三步有严格的先后依赖，跳步就会卡住，所以下面按顺序拆开讲。
第一步，设置 → 模型，输入 API 密钥并保存。注意这里保存之后，模型路由是立即生效的，不需要重启服务器，这是很多人第一次用时会误判的地方——他们习惯性地关掉终端再重开，其实没必要。如果你还没有密钥，可以到 DeepSeek 平台申请。当前项目处于内测阶段，打开页面时可能先看到一份内测声明，点击继续即可进入主界面。除了 DeepSeek 官方卡片，这个页面还支持目录提供方与自定义提供方，后面两个小节会分别展开。
第二步，选择工作区。点击「选择工作区」，把你启动 dsh 时所在的项目目录添加进来并选中。这里有一个非常关键的行为：在选中工作区之前，会话输入框是不可用的。新手最容易遇到的“输入框点不动”“输入了没反应”，九成以上都是没选工作区导致的，而不是软件坏了。所以建议在启动 dsh 之前先 cd 到目标项目目录，这样“选择工作区”的候选项里第一个就是你要的目录。
如果你手上还没有现成的项目目录，可以像教程里那样先建一个：mkdir DeepSeekProjects，然后把这个空目录选为工作区，用来做第一次的探索性任务。空目录同样可以选，agent 会在其中创建文件、运行命令。
第三步，在会话里发出第一个任务指令。官方快速入门指南给的建议很克制：不要一上来就交付真实的重活，先让 agent 熟悉工作区。第一个任务推荐用一条轻量指令：Summarize this repository and identify its main packages. 这条指令的好处是——agent 需要去读文件、识别目录结构、归纳包信息，会实际走一遍“读写工作区文件、运行命令、委派子代理、维护计划”的完整链路，你又不会因为一次误操作损失什么。
运行过程中，agent 会做需求分析，然后把计划拆开执行。当某个操作超出了你设置的权限策略，它会先停下来征求你的审批，而不是硬闯。这套“先声明、再审批”的机制，正是下面权限档位那一节要讲的核心。
把三步闭环再压缩一遍，方便你对照排查：
- 配置模型：设置 → 模型，填入 DeepSeek API 密钥并保存，路由立即生效、无需重启；也支持其他提供方与自定义 OpenAI 兼容端点。
- 选择工作区：点击「选择工作区」，添加并选中启动 dsh 时所在的项目目录；未选中前会话输入框不可用。
- 运行任务：在会话中输入指令，例如 Summarize this repository and identify its main packages.；agent 会读写工作区文件、运行命令、委派子代理并维护计划，越权操作先征求审批。
顺带提醒一个“看着像故障、其实正常”的现象：新 Web UI 在添加工作区之前不会选中任何工作区，这是设计如此，不是安装失败。把这条记在心里，能省掉一次无谓的重装。
四种运行模式怎么选：标准模式、PTC 模式、极简模式与创造模式的适用边界
DeepSeek Harness 提供四种运行模式，它们并不是“功能多少”的简单递进，而是面向不同使用场景做的能力取舍。选错模式的代价通常是两类：一类是多花了 token 却没用上能力，另一类是关掉了自己要用的能力还不知道为什么不好用。下面逐个说清边界。
标准模式是新手首选。它内置完整的代码 Agent 能力，文件操作、Shell、检索、任务规划、子 Agent 等插件都是预装的，开箱即用。如果你只是想让 agent 帮你读仓库、改文件、跑测试，不要犹豫，就用它。
PTC 模式能力与标准模式相同，但额外支持用 TypeScript 批量编排工具调用，把多轮交互合并到一次编排里，从而减少对话次数、节约 Token。它的门槛在于依赖较强的代码规划能力，调试难度也更高。所以它的适用边界很清楚：当你明确处于大量重复调用的场景——比如需要对一批文件做同构处理、对一组接口跑同样的检查——再切换过去，收益才明显；零星任务切过去反而增加心智负担。
极简模式只保留持久 Bash 与文件编辑器，移除附加功能。它的定位是模型基准性能测试——把外层插件带来的“脚手架红利”剥掉，看看模型本身在裸工具条件下表现如何。它不适合日常开发，因为你会失去检索、规划、子 Agent 这些真正提升效率的东西。
创造模式具备标准模式的全部能力，另外可以探查 Cordis 运行环境、在线调试插件、创建新 Agent，实现功能的自主扩展。它适合你在做插件开发、想搞清楚运行时到底加载了什么、想现场造一个新 Agent 验证想法的时候。对只想“用”而不是“造”的读者，标准模式就够了。
| 模式 | 核心能力 | 额外特性 | 适用场景 | 不适用 |
|---|---|---|---|---|
| 标准模式 | 完整代码 Agent，插件预装 | 文件、Shell、检索、任务规划、子 Agent | 新手首选、日常开发 | — |
| PTC 模式 | 同标准模式 | TypeScript 批量编排，合并多轮、省 Token | 大量重复调用场景 | 零星任务、调试能力弱的人 |
| 极简模式 | 持久 Bash + 文件编辑器 | 移除附加功能 | 模型基准性能测试 | 日常开发 |
| 创造模式 | 同标准模式 | 探查 Cordis 环境、在线调试、创建 Agent | 插件开发、功能自主扩展 | 只想开箱即用的用户 |
操作上，模式是选定之后再点击新会话、输入需求，然后开启对话。也就是说，模式是会话级的选择，切换模式通常意味着开一个新会话，而不会把旧会话“改造”成新模式——这一点和权限档位类似，后面会看到权限变更也建议配合新会话来生效。
权限三档位：Read Only、Workspace Write 与 Full access 的安全取舍
DeepSeek Harness 的权限机制用于控制智能体（Agent）访问本机文件、执行命令的范围。安全等级从高到低依次是：Read Only > Workspace Write > Full access。注意这里的“从高到低”说的是安全等级，不是能力大小——能力方向恰好相反，安全越高的档位能做的事越少。
Read Only 只允许读取工作区文件，既不能修改文件，也不能执行终端命令，安全性最高。它适合“只想让 agent 帮我理解代码、总结文档、做代码审查前的初步扫读”这类场景——你根本不希望它落盘任何东西。代价是，一旦任务需要跑一条命令来验证结论，它就会卡在权限上。
Workspace Write 允许读写当前工作目录内的文件，也可以在工作目录内执行命令，但无法访问工作目录以外的文件。这是日常开发推荐使用的档位：绝大多数编码任务只需要在项目目录里折腾，这个边界既够用，又把风险圈在了一个可回收的范围内。你的项目目录即使被改乱，最坏情况也只是这个仓库，回滚即可。
Full access 拥有完整文件系统访问权限，可以读写任意路径文件、执行各类终端指令，存在较高安全风险。它不是不能开，而是要想清楚为什么开：比如任务确实需要动到工作区之外的配置文件、需要访问系统级工具链。一旦开启，agent 的失误就不再被目录边界兜住。建议只在明确知道自己在做什么、并且有版本控制或备份保护的情况下临时使用。
| 档位 | 文件读取 | 文件写入 | 命令执行 | 安全等级 | 推荐场景 |
|---|---|---|---|---|---|
| Read Only | 仅工作区 | 不可 | 不可 | 最高 | 理解、总结、审查类只读任务 |
| Workspace Write | 工作区 | 仅工作目录内 | 可在工作目录执行 | 中 | 日常开发（推荐） |
| Full access | 任意路径 | 任意路径 | 任意指令 | 最低 | 确需越界的特殊任务，谨慎 |
还有一个行为上的细节值得在这里补上：即便在较低安全等级的档位下，超出权限策略的操作也会先征求你的审批。这意味着权限档位并不是“要么全放要么全拦”的开关，而是一条默认边界加一层审批确认的组合。实践中的建议是：从 Workspace Write 起步，遇到确实需要越界的任务，再临时提权处理并尽快降回；任务跑完如果改过权限，开一个新会话让设置干净生效。
把安全这件事再强调一次：权限档位的意义不是防“恶意 AI”，而是防“误解指令的人类 + 执行过度的 Agent”这个组合。一条措辞模糊的指令，在 Full access 下可能删掉你不该删的东西，在 Workspace Write 下最多搞乱当前仓库。这也是为什么官方把 Workspace Write 列为日常开发的推荐值。
添加目录提供方：选 Anthropic 或 OpenAI 后只需填 API 密钥，端点协议模型自动带出
如果你不想只用 DeepSeek 官方端点，DeepSeek Harness 还支持第三方模型，路径分两条：目录提供方与自定义提供方。先讲目录提供方，因为它更省事。
所谓目录提供方，就是 dsh 的已安装目录里已经收录的提供方，例如 Anthropic、OpenAI。它的价值在于：端点、协议和模型列表都由目录自动提供，不需要你手填。你的操作被简化成“选择添加提供方 → 选取具体提供方 → 输入其 API 密钥 → 保存”。保存完成后，你就能在对话框的模型列表里看到刚刚添加好的模型。比如接入智谱的 coding plan 套餐，就是走这条路径：选提供方、填密钥、保存，然后在模型列表里选它。
但这里有一个必须提醒的坑：使用原生认证的提供方需要各自的原生凭据，只填 API 密钥字段是无法完成配置的。这不是 bug，而是这些厂商的认证机制本身就不走“一个 Bearer 密钥”的模型。下面把素材里明确给出的四类列清楚：
| 提供方 | 需要的原生凭据 |
|---|---|
| Bedrock | AWS 凭据与区域 |
| Vertex | ADC 项目 |
| Azure | api-version |
| Codex | OAuth |
从适用场景上看，目录提供方的定位是“接入已收录的主流厂商”。如果目标厂商在目录里，就用它，别费劲去写自定义；如果目录里没有——比如你公司的内部网关、自建推理服务器——才走下一节的自定义提供方。另外要记住一句原文给出的重要区分：目录提供方使用已安装目录，不发起网络请求。也就是说，在选择提供方这一步不需要联网探测，端点与模型清单是本地目录直接给出的。
添加自定义提供方：Provider ID、baseURL、API 协议、凭据、模型五个字段的填写要点
公司网关、自建服务器等目录中不存在的端点，用自定义提供方接入。选择“添加自定义提供方”后，表单要求你填写下列字段。这一节逐字段讲清要点，因为这里的每个字段填错都会在运行时以错误码的形式还给你。
| 字段 | 说明 | 是否必填 |
|---|---|---|
| Provider ID | 小写，永久标识 | 必填 |
| 显示名称 | 在界面里显示的名字 | 可选 |
| 基础 URL | 端点的 baseURL | 必填 |
| API 协议 | 如 openai-completions | 必填 |
| 凭据 | API 密钥或环境变量引用 | 必填 |
| 模型 | 至少一个模型 | 必填 |
Provider ID 是这里面最需要慎重的一个字段：它是小写、也是永久的。之所以永久，是因为请求、已保存的会话、模型默认值和凭据引用都会使用它。Provider ID 不可改名——如果你确实需要重命名提供方，正确做法是添加新提供方并删除旧提供方，而不是去改 ID。相对而言，显示名称、基础 URL、协议、凭据和模型仍可编辑，所以“名字打错了”不用慌，改显示名称就好；“ID 打错了”才需要走新建 + 删除的流程。
基础 URL 填端点的 baseURL，通常是带 /v1 这样版本前缀的根地址。API 协议决定请求怎么发，素材给出的典型值是 openai-completions，也就是 OpenAI 兼容的补全协议。凭据可以填 API 密钥，也可以填环境变量引用——后者更安全，避免把密钥存进可分享的配置里。模型至少填一个，可以填多个。
表单还有一个很好用的辅助功能：在模型目录中选择获取可用模型，可以查询表单当前显示的基础 URL 和凭据，列出候选项。这里要理解它的边界：选择候选项只会更新草稿，保存前不会存储提供方。换句话说，你可以放心地点来点去试查询，不点保存就不会留下半成品配置。另一个边界是：模型发现调用的是 OpenAI 兼容的 GET /models，不提供该端点的服务请手动输入模型——这也是后面排错表里“获取可用模型返回 401”那条要区分密钥无效与端点不支持模型发现的原因。
把自定义提供方的完整配置思路落成一段可直接参考的 YAML（写进 $DSH_HOME/settings.yaml），能更直观地看到字段之间的对应关系：
# 文件路径：$DSH_HOME/settings.yaml
# 顶层键 llm-pi-ai 是模型路由插件的 id，providers 下按提供方 id 组织
llm-pi-ai:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY # 凭据引用：从 GATEWAY_API_KEY 环境变量读取
api: openai-completions # API 协议：OpenAI 兼容的补全协议
baseURL: https://gateway.runoob.example/v1 # 你的网关端点
models:
- id: legacy-chat # 纯文本模型，不写 input 即按纯文本对待
- id: vision-preview # 视觉模型
input: [text, image] # 声明同时接受文本与图片
这段配置里，apiKeyEnv 就是“凭据用环境变量引用”的写法，api 对应表单里的 API 协议，baseURL 对应基础 URL，models 就是模型清单。自定义提供方在表单里没有“模型模态”的字段，所以视觉能力要在 YAML 里声明——这正是下一节的主题。
2026 年 9 月最新实践：settings.yaml 里用 input 与 defaultInput 声明视觉模型模态
到这里要讲一个当前版本里最容易踩的坑：手动录入的模型默认按纯文本对待。想要支持图片，必须显式声明模态。这不是设计疏漏，而是 dsh 采取的一种明确策略——因为没有任何环节能去询问端点接受哪些模态，所以只能“先声明后使用”。你的声明被当作对端点的断言，而不是对它的检查：声明了端点并不提供的图片能力，不会在配置阶段被拦下，而是改由提供方在请求时拒绝。
具体做法是：在 $DSH_HOME/settings.yaml 中给该模型加上 input。这个字段接受 text 和 image，而且只作用于该模型，因此一条路由可以同时服务纯文本模型与视觉模型。如果你给一个没有声明图片模态的模型附加图片，请求会在发送前就被拒绝，并点名该模型——这比发出去被对方 400 更友好，至少你知道问题出在本地配置。
三个字段的作用范围要分清楚，这也是本节最核心的知识点：
- input：写在具体模型下，只作用于该模型。省略它、或写成空列表，两者同义；此时保留已安装目录为该模型记录的模态，目录未描述的模型则回退到该路由的
defaultInput。 - defaultInput：是回退值而不是覆盖值，默认是
[text]，写在本路由下，对本路由中目录未描述的模型生效。如果你手动录入的模型全都接受图片，就设置一次这个回退值，不必逐个模型写。 - modelOverrides：用于收窄目录提供方中某个模型的模态，以模型 id 为键。目录提供方没有可填写的 models 列表，所以覆盖只能走这里。
举两个典型例子。第一个是“路由级回退 + 个别模型不写 input”的写法，适合手动录入的模型全都能看图：
# 文件路径：$DSH_HOME/settings.yaml
# defaultInput 是回退值而不是覆盖值，默认为 [text]
llm-pi-ai:
providers:
vision-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://vision.runoob.example/v1
defaultInput: [text, image] # 对本路由下目录未描述的模型生效
models:
- id: first-model
- id: second-model
第二个是“反向收窄”的写法。注意目录提供方没有可写的 models 列表，所以要覆盖目录里的模态，必须用 modelOverrides：
# 文件路径：$DSH_HOME/settings.yaml
# 目录提供方没有可填写的 models 列表，覆盖走 modelOverrides
llm-pi-ai:
providers:
anthropic:
modelOverrides:
claude-sonnet-4-5:
input: [text] # 把该模型的图片能力去掉
要记住的关键约束是：input 与 defaultInput 都是对你端点的断言，而不是对它的检查。所以你声明了图片能力，但端点实际不提供，dsh 不会在配置阶段拦你，最后是提供方拒绝该请求；反过来，你把某个模型的能力收窄成 [text]，也只是本地策略，不代表模型本身不能看图。配置层面与能力层面是分离的，理解这一点，排错时就不会把两边混淆。
最后把模型配置的常见错误汇总成排错表，出错时先来这里对号，能省掉大量猜测：
| 错误 | 含义 | 解决 |
|---|---|---|
| MISSING_CREDENTIAL | 缺少提供方密钥 | 通过模型页存储提供方密钥，或提供被引用的环境变量 |
| UNKNOWN_MODEL | 请求的模型未配置 | 选择已配置的模型，或向自定义提供方添加缺失的模型 |
| 获取可用模型返回 401 | 密钥无效，或端点不支持模型发现 | 检查密钥；模型发现调用 OpenAI 兼容的 GET /models，不提供该端点的服务请手动输入模型 |
| 图片在发送前被拒绝 | 模型未声明图片模态 | 给自定义提供方的模型加 input: [text, image]；DeepSeek 自身路由纯文本，无法通过配置改变 |
| 提供方拒绝了带图片的请求 | 模型声明了端点实际并不提供的图片能力 | 从授予它图片能力的列表中移除 image，并开启新会话 |
注意最后两条的区别：“发送前被拒绝”是本地模态没声明，“提供方拒绝”是本地声明过头。两个方向的修正动作完全不同，一个是加 image，一个是删 image，后者还需要开一个新会话让设置生效。另外要特别标注一句：DeepSeek 自身路由是纯文本的，无法通过配置改变——想看图就换到支持视觉的提供方。
常用命令速查
把这一段与上一段涉及的入口命令集中列一遍，方便你在实际操作中随手对照。这些命令的共同点是都可以直接在项目目录下执行，无需额外切目录：
| 命令 | 作用 |
|---|---|
| npx @deepseek-ai/dsh web | 启动 Web UI（等价于 --profile web） |
| dsh --profile headless "任务描述" | 一次性运行一个任务，打印最终答案后退出（适合脚本/CI） |
| dsh plugin --profile <name> <pnpm 参数> | 管理某个 profile 的插件（转发给 pnpm 在 profile 目录执行） |
| dsh --profile web --dump-config | 查看实际启动的完整配置树（不启动服务器） |
| dsh --profile web --dump-default-config | 查看默认配置树（不含用户 patch） |
| pip install deepseek-harness-sdk | 安装 Python SDK（自带运行时） |
关于 Profile 还有一条要记住：web 与 headless 两个 profile 会在首次使用时从内置模板自动初始化，其余 profile 需要通过 dsh plugin 创建。另外，dsh 的启动参数在前、应用参数在后，例如 dsh --profile web --port 8080 中 --port 属于 Web 应用，而不是 dsh 本身。这个顺序搞反会直接报参数错误。
排错时，--dump-config 与 --dump-default-config 这一对特别值得记住：前者告诉你“实际生效了什么”（含你写的 patch），后者告诉你“模板本来是什么”。两者一对比，就能确认你的 settings.yaml 到底有没有被读进去——比如模态声明没生效，先跑一次前者看看配置树里有没有 input。
最后把前面几节提到的常见问题也归拢一下，方便快速定位：
- 浏览器打不开 http://127.0.0.1:3080：确认终端里 dsh 进程仍在运行且没有报错；端口被占用时用
dsh --profile web --port 8080换端口；检查防火墙是否放行本地端口。 - npx 找不到 @deepseek-ai/dsh 或版本过旧：确认 Node.js 已安装且版本较新（
node -v）；项目处于开发者预览阶段、迭代很快，必要时清空 npx 缓存后重试，或改用源码安装。 - 源码安装时 pnpm install / build 失败：确认已安装 pnpm（
npm install -g pnpm）；网络受限时为 npm/pnpm 配置镜像源；构建要求 Node.js 版本满足仓库 package.json 的 engines 声明。 - 会话输入框不可用 / agent 无法读写文件：最常见原因是没有选择工作区，回到「选择工作区」添加并选中项目目录；确认已在「设置 → 模型」中保存有效 API 密钥，模型路由无需重启即可生效。
- Python SDK 运行时找不到 Node.js：SDK 自带运行时、正常情况下不需要系统 Node.js；若报运行时缺失，确认安装的是与 SDK 同版本的完整包（
python -m pip install deepseek-harness-sdk），并按官方前置要求使用 Linux x64 / arm64 或 macOS 14+（arm64）。
总结与最佳实践
把这一整篇的内容压成一份可以照着做的清单。安装部分（上一段）解决“把进程跑起来”，配置部分（这一段）解决“让它按你的预期干活”，两者合起来才算完成一次真正的首次启动。
- 先确认环境再动手：万能前置是 Node.js（
node -v建议 v20+）；源码安装额外要 Git 与 pnpm；Python SDK 要 Python 3.10+，且官方支持的平台是 Linux x64 / arm64 与 macOS 14+（arm64）。 - 按需求选安装路径：只想最快体验 Web UI 用
npm install -g @deepseek-ai/dsh再dsh web，或直接npx @deepseek-ai/dsh web；要开发插件、读源码、参与贡献走源码安装（clone →pnpm install→pnpm run build→pnpm dsh web）；要在自己的 Python 程序里调用 Agent 用 SDK。 - 启动前先 cd 到项目目录：dsh 会把调用目录作为默认文件系统位置，先
cd再启动，后续选择工作区最省事。 - 凭据按顺序给：默认走 DeepSeek 官方端点时只需
DEEPSEEK_API_KEY；接入 OpenAI 兼容代理时再补DEEPSEEK_BASE_URL（带协议与/v1前缀）与DSH_MODEL。别一次填满三个，出错了不好定位。 - 完成首次三步闭环：设置 → 模型填密钥（保存即生效，无需重启）→ 选择工作区（未选中前会话输入框不可用）→ 发出第一个任务。第一个任务建议用
Summarize this repository and identify its main packages.这类轻量指令，先让 agent 熟悉工作区。 - 模式按场景选：新手与日常开发用标准模式；大量重复调用、愿意承担调试成本时用 PTC 模式省 Token；只做模型基准测试才用极简模式；要在线调试插件、创建新 Agent 用创造模式。
- 权限从 Workspace Write 起步：只读任务用 Read Only，日常开发用 Workspace Write（读写限工作目录内），Full access 风险最高、非必要不开；越权操作会先征求审批，改过权限后建议开新会话。
- 第三方模型优先用目录提供方：Anthropic、OpenAI 等已收录厂商，选好提供方后只需填 API 密钥，端点、协议、模型列表自动带出，且不发起网络请求；Bedrock、Vertex、Azure、Codex 需各自原生凭据（AWS 凭据与区域 / ADC 项目 / api-version / OAuth）。
- 目录里没有的端点用自定义提供方：必填 Provider ID（小写、永久、不可改名，要改名就新建再删旧）、基础 URL、API 协议（如 openai-completions）、凭据（可用环境变量引用）、至少一个模型；显示名称、baseURL、协议、凭据、模型后续仍可编辑；“获取可用模型”只更新草稿，不保存就不落盘。
- 视觉模态必须显式声明：手动录入的模型默认按纯文本处理，在
$DSH_HOME/settings.yaml的llm-pi-ai路由下为模型写input: [text, image]；全路由默认看图用defaultInput（回退值，默认[text]）；收窄目录提供方模型用modelOverrides。记住 input 与 defaultInput 是断言而非检查，DeepSeek 自身路由纯文本、无法通过配置改变。 - 排错先查表再猜：MISSING_CREDENTIAL 查密钥或环境变量引用；UNKNOWN_MODEL 检查模型是否配置；模型发现 401 区分密钥无效与端点不支持
GET /models；“发送前被拒绝”是本地没声明 image，“提供方拒绝”是声明过头要删 image 并开新会话。 - 善用配置自检命令：用
dsh --profile web --dump-config看实际生效的配置树，用--dump-default-config看默认模板，两者对比即可确认settings.yaml是否真的被读到；启动参数在前、应用参数在后，例如dsh --profile web --port 8080。
如果只记一句话：先把密钥配好、把工作区选对，再用最小权限（Workspace Write）跑一条轻量指令验证闭环。这三件事做对了，后面无论是换提供方、调模态还是开子 Agent，都只是在这条已经跑通的链路上做增量微调，而不是从头排查。