1. 零基础第一次跑 dsh：从安装到 Agent 出结果
DeepSeek Harness（简称 dsh）是 DeepSeek 推出的开源 Agent 框架，它和普通聊天工具最大的区别在于：每个会话里都有一个能读写文件、执行命令、搜索代码、委派子代理的智能体在替你干活。如果你之前只用过网页版对话，第一次接触 dsh 可能会被 Agent、Session、Skills、Subagents 这些词绕晕。这篇内容面向零基础读者，把首次上手的完整路径拆成可跟做的步骤，并且用 TaoToken 作为统一的 Key/API 通道接入 dsh，避免你在多个厂商之间来回切换密钥。
适合谁看：会用命令行、装过 Node.js、想跑通第一个 Agent 任务但还没动手的人。读完你能做到三件事——把 dsh Web UI 跑起来、用 TaoToken 配好模型通道、发起一次真实调用并确认返回正常。
我试过在全新目录里从零走一遍，最容易卡住的不是安装，而是模型配置那一步：很多人填了 Key 却不知道 Base URL 该写什么，或者协议选错导致请求 401。下面把每一步都写清楚，包括可复制的配置骨架。
先明确 dsh 的几个核心概念，后面配置时你会反复用到。Agent 是会话里正在工作的智能体实例；Session 是 Agent 的全部工作记录，以只追加的事件日志形式存在，所以刷新页面甚至重启进程后都能恢复；Turn 是一次完整问答，Step 是一轮里的一次模型请求加工具调用批次；Tools 是 Agent 的手脚，读文件、跑 bash、搜代码都算；Skills 是可复用的操作手册；Subagents 是 Agent 开的分身，独立上下文干活；Jobs 是后台任务。这些概念不用背，跑通一次自然就懂了。
安装前确认 Node.js 版本，dsh 要求 ^22.19 或 >=24。用node -v看一眼，版本不够就先升级。然后最省事的方式是直接用 npx 启动：
npx @deepseek-ai/dsh web如果你习惯从源码跑，也可以克隆仓库后本地构建：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web启动成功后终端会打印一个地址，默认是http://127.0.0.1:3080，浏览器打开就能看到会话列表和新建会话的界面。端口被占用时换一个：
dsh --profile web --port 8080不想开浏览器、只想让 Agent 干一件事的场景，用 headless 模式：
dsh --profile headless "run the tests"它会新建一个持久化会话、提交任务、等完成，然后把最后一条非空回复打印到 stdout，任务成功退出码为 0，否则为 1。这个模式在 CI 里很好用。
到这里 dsh 本身已经跑起来了，但还没有模型可用，Agent 没法思考。下一步就是接入模型通道，这也是本篇的重点：用 TaoToken 统一管理 Key，后面无论换哪个模型都不用改一堆配置。
2. 用 TaoToken 统一 Key 接入 dsh 的前置准备
dsh 支持多种模型厂商，官方预置了 DeepSeek、Anthropic、OpenAI 等目录，也支持自定义厂商。对普通用户来说，最省心的做法是准备一个统一的 API 通道，把 Key 和 Base URL 集中管理，这样在 dsh 里只需要配一次自定义厂商，之后换模型只改 Model ID 就行。TaoToken 就是干这个的：它提供一个兼容 OpenAI 协议的接口地址，你拿到一个 Key 就能调用多种模型。
前置准备分三步。第一步，注册并拿到 API Key。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，完成注册后在控制台创建 Key。控制台地址是 https://taotoken.net/console ，创建 Key 的页面在 https://taotoken.net/api-keys 。Key 只在创建时显示一次，复制下来存好，后面配置要用。
第二步，确认你要用的模型 ID。dsh 里配置自定义厂商时需要至少填一个模型，Model ID 要和通道支持的名称一致。你可以在模型对话页面先试一下通道是否正常，地址是 https://taotoken.net/chat ，发一条消息看有没有返回。这一步能提前排除 Key 无效或余额不足的问题，省得在 dsh 里排查。
第三步，想清楚 Base URL 和协议。TaoToken 的 API 地址是 https://taotoken.net/api ，协议选 OpenAI 兼容的openai-completions。注意这里不要加 UTM 参数，API 地址就是干净的https://taotoken.net/api。dsh 里填 Base URL 时通常要带上版本路径，具体以你安装版本的界面提示为准，如果界面要求填到/v1，就写https://taotoken.net/api/v1。
为什么推荐用统一通道而不是每个厂商单独配？因为 dsh 的凭据是只写存储的，存在$DSH_HOME/.credentials.yaml里，配置项存在$DSH_HOME/settings.yaml。如果你给五个厂商各配一个 Key，管理起来很乱；用一个通道，只需要维护一个 Key，换模型时改 Model ID 即可。而且 dsh 的会话会记录自己日志里的模型，切换模型不影响已发过请求的旧会话，这对做对比测试很友好。
还有一个细节：dsh 的密钥字段是只写的，保存后界面只显示脱敏的凭据引用，不会再回显明文。所以配置时一定要确认 Key 复制正确，填错了只能重新填。如果你打算长期做编码类任务或跑 Agent，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan ，它更适合高频调用场景。接入文档在 https://taotoken.net/doc ，遇到协议细节可以对照看。
前置准备好之后，就可以进 dsh 的配置界面动手了。下面给出可复制的配置骨架，包括 UI 操作路径和手工配置文件两种方式。
3. 可复制配置：settings.json 与 config.toml 骨架
dsh 的配置有两种方式：UI 图形化配置和手工编辑配置文件。对零基础用户，我建议先用 UI 配一遍，确认能跑通，再了解配置文件结构，方便以后批量管理或迁移。这一节给出两种方式的完整骨架。
先说 UI 路径。打开 dsh Web UI，进入 Settings → Models（设置 → 模型）。找到 Add a custom provider（添加自定义厂商），填写以下字段：
Provider ID 填一个小写标识，比如taotoken。注意这个 ID 创建后永久不可改，因为请求、已保存会话、模型默认值、凭据引用都依赖它。想改名就先新建再删除旧的。Base URL 填https://taotoken.net/api，如果界面要求带版本路径就填https://taotoken.net/api/v1。API 协议选openai-completions。凭据填你从 https://taotoken.net/api-keys 拿到的 Key。模型至少填一个，Model ID 写你要用的模型名称。填完保存，然后在模型选择器里选中它，成为新会话的默认模型。
如果你要手工管理配置，dsh 的用户级配置文件在$DSH_HOME/settings.yaml。下面是一个自定义厂商的骨架，字段名和结构以你安装版本的文档为准，这里演示结构：
llm-pi-ai: providers: taotoken: apiKeyEnv: TAOTOKEN_API_KEY api: openai-completions baseURL: https://taotoken.net/api/v1 models: - id: your-model-id - id: another-model-id input: [text, image]这里apiKeyEnv表示从环境变量读取 Key，你也可以在 UI 里直接存凭据。input字段只作用于该模型，声明它支持文本和图片输入，需要模型本身支持才行。
有些部署或工具链习惯用 TOML 格式，下面给一个等价的config.toml骨架，方便你在支持 TOML 的场景里对照：
[providers.taotoken] api_key_env = "TAOTOKEN_API_KEY" api = "openai-completions" base_url = "https://taotoken.net/api/v1" [[providers.taotoken.models]] id = "your-model-id" [[providers.taotoken.models]] id = "another-model-id" input = ["text", "image"]如果你用的是 Claude Code 这类工具，配置思路类似，Base URL、Key、Model ID 三件套要写全。Claude Code 的接入文档在 https://taotoken.net/doc ，里面有对应的配置示例。dsh 这边如果你用 CC Switch 或 Cline MCP 做辅助管理，同样要保证这三件套一致：Base URL 指向https://taotoken.net/api，Key 用同一个，Model ID 和通道支持的名称对齐。
配置完成后不需要重启服务，下一次请求立即生效。但要注意：已经发过请求的会话会继续用自己日志里记录的模型，不受切换影响。所以验证新配置时，最好新建一个会话。
环境变量方式适合不想把 Key 写进配置文件的场景。在启动 dsh 前设置：
export TAOTOKEN_API_KEY="你的Key"Windows PowerShell 下用：
$env:TAOTOKEN_API_KEY="你的Key"这样配置文件里只写apiKeyEnv: TAOTOKEN_API_KEY，实际值从环境变量读，凭据不落盘到 settings 文件里。dsh 的凭据实际存在$DSH_HOME/.credentials.yaml，UI 里密钥字段是只写的，推荐一切通过 UI 配置，只有高级项才手改 YAML。
配置骨架给完了，下一步是发起一次真实调用，确认通道生效。
4. 验证请求：发起一次调用并确认通道生效
配置写完不代表通道通了，必须发一次真实请求看返回。这一节给出完整的验证动作，包括新建会话、选择工作区、发消息、看工具调用卡片，以及怎么判断返回是来自你配的通道。
第一步，新建会话。在 dsh Web UI 里点新建会话。注意：选择工作区之前，会话编辑区是不可用的，所以先点 Choose workspace，把你启动 dsh 时所在的项目目录加进去并选中。Agent 的 cwd 默认就是会话的工作区根目录，多数路径参数都相对于它解析。
第二步，确认模型。在模型选择器里选中你刚配的taotoken厂商下的模型。选中后它成为新会话的默认模型。
第三步，发一条最简单的消息，比如"你好"。如果 Agent 正常回复，说明通道基本通了。但这一步还不够，因为简单对话可能走的是缓存或默认模型，我们要确认请求确实经过了你配的 Base URL。
更可靠的验证方式是让 Agent 调用一个工具，观察工具调用卡片。比如输入：
列一下当前目录结构，然后读一下 package.json 的前 20 行。Agent 会调用 glob 或 bash 列目录，再调用 read 读文件。界面上会出现每次工具调用的卡片，包括读文件、命令输出、退出码。如果这些卡片正常出现，且 Agent 基于真实文件内容给出回答，说明模型通道和工作区都正常。
想进一步确认请求走的是 TaoToken 通道，可以看 dsh 的日志或凭据引用。在 Settings → Models 里，你配的厂商会显示脱敏的凭据引用。如果请求出错，错误信息会给出线索：MISSING_CREDENTIAL表示没存密钥；UNKNOWN_MODEL表示模型未配置；拉取模型返回 401 表示 Key 不对。这三个错误覆盖了大部分首次配置问题。
如果你想让验证更彻底，可以发起一次带工具调用的 Agent 任务，比如：
跑一下 pnpm run test，看看有没有失败的用例，有的话定位原因。Agent 会执行 bash 跑测试，看到失败用例后用 grep 或 read 定位源码，再用 edit 修改，最后再跑一次测试确认通过。整个过程你能在界面上看到每个工具调用。最终 Agent 会给出结论：修复了哪一行、为什么、测试现在通过。你可以自己跑一遍pnpm run test复核。
验证成功的标志有三个：模型选择器里能看到你配的模型；新建会话发消息能正常回复；工具调用卡片正常出现且基于真实文件内容。三个都满足，说明 TaoToken 通道在 dsh 里生效了。
如果你还想验证 Skills 和 Subagents 是否可用，可以接着做两个最小示例。Skills 的验证：在项目根目录创建.agents/skills/code-review/SKILL.md，内容写一段代码审查流程，然后新建会话问 Agent"你现在有哪些可用技能？"，它应该能列出 code-review 及描述。Subagents 的验证：让 Agent"派两个子代理并行调研两个库的 API，最后汇总对比"，观察界面是否出现子代理的创建与结束事件。
验证通过后，日常使用中还会遇到一些报错，下面把最常见的几个列出来对照排查。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
首次接入最容易撞上的就是认证和协议类报错。这一节按真实报错信息对照排查，每条给出原因和动作。注意：dsh 处于开发者预览阶段，界面与行为仍在快速迭代，遇到出入以你安装版本的界面和官方文档为准。
401 Unauthorized。最常见的原因是 Key 填错或没生效。先确认你在 https://taotoken.net/api-keys 创建的 Key 复制完整，没有多余空格。然后确认 dsh 里凭据字段保存成功，UI 显示脱敏引用。如果你用环境变量方式，确认启动 dsh 的 shell 里TAOTOKEN_API_KEY已设置，且配置里apiKeyEnv的名字和它一致。还有一种情况是 Base URL 写错，比如漏了/v1或多了斜杠，导致请求打到错误路径返回 401。对照https://taotoken.net/api检查。
local proxy failed。这个报错通常出现在网络层，表示 dsh 尝试连接 Base URL 时失败。先确认你的网络能正常访问https://taotoken.net/api，可以在浏览器或 curl 里试一下。如果公司网络有出口限制，需要联系网络管理员放行。注意不要使用任何非正规的网络工具，这类工具本身有安全风险。dsh 的请求是标准的 HTTPS 调用，只要网络通就能连上。
reading choices 相关报错。这类报错一般出现在解析模型返回时，表示返回结构不符合预期。常见原因是协议选错，比如通道是 OpenAI 兼容协议，你却在 dsh 里选了 Anthropic 协议。回到 Settings → Models，确认你配的厂商 API 协议是openai-completions。另一个原因是 Model ID 写错，通道返回了错误结构。确认 Model ID 和通道支持的名称一致，可以在模型对话页面先试一次。
OAuth 相关报错。dsh 预置目录里有些厂商使用原生鉴权，比如 Bedrock、Vertex、Azure、Codex 这类，需要填各自的原生凭据，只填 API Key 是不生效的。如果你用 TaoToken 这类 API Key 通道，就不要选这些原生鉴权厂商，而是用 Add a custom provider 配 OpenAI 兼容协议。如果你确实要用 Codex 的 OAuth，那属于另一套配置，和本篇的统一 Key 通道不是一回事。Codex 的 auth.json 配置需要 Base URL、Key、Model ID 三件套写全，具体见接入文档 https://taotoken.net/doc 。
MISSING_CREDENTIAL。表示没存密钥。去 Settings → Models 里为该厂商存好 API Key，或确认它引用的环境变量已设置。
UNKNOWN_MODEL。当前会话记录的模型对应的厂商或模型被删了。在模型选择器里重新选一个可用模型，新会话立即可用，老会话选好模型后即可继续。
沙箱拒绝[sandbox: file access denied under <mode> mode]。这是权限策略拦截，不是命令本身出错。先想清楚该操作是否必要、能否换路径；确有必要就调整权限预设后重试一次，不要盲目反复重试。日常用 workspace-write 预设，Agent 能在项目里自由读写，高风险操作会先问你。
后台任务找不到。job_list 只列当前 Agent 的任务，归属隔离。跨会话、跨 Agent 的任务不可见。如果你在另一个会话里启动的后台任务，当前会话看不到是正常的。
Workflow 报错说脚本里不能用 fs 或网络。这是设计约束，工作流脚本只是编排器，真正的文件与网络操作必须由子代理完成。把"读文件然后汇总"改成"派子代理去读，子代理返回结果"。
排查时记住一个原则：先看错误信息里的关键词，再对照配置三件套（Base URL、Key、Model ID）。大部分首次接入问题都出在这三样里的一样的。如果三件套都对还是报错，去接入文档 https://taotoken.net/doc 对照协议细节，或者在模型对话页面单独测一次通道，把 dsh 和通道的问题隔离开。
6. 把 TaoToken 用顺：日常技巧与下一步
跑通第一次调用之后，日常使用中有几个习惯能让 TaoToken 通道更顺。第一，把 Key 和 Base URL 集中管理，不要在每个工具里各配一份。dsh 里配一次自定义厂商，Claude Code 里配一次，其他工具如果支持 OpenAI 兼容协议也指向同一个地址。这样换 Key 时只改一处。
第二，善用模型选择器的会话隔离特性。dsh 的会话会记录自己日志里的模型，已发过请求的旧会话不受切换影响。这意味着你可以用同一个会话固定一个模型做对比测试，新建会话试新模型，互不干扰。做模型选型时这个特性很实用。
第三，长任务用后台任务和 Goals。跑长测试用run_in_background: true，立即拿到 job id，之后用 job_output 收结果。长期目标用 create_goal 创建，Agent 会自动多轮延续直到完成。这些能力配合统一 Key 通道，能让 Agent 真正干完一件大事，而不是每轮都要你手动催。
第四，Skills 和 Subagents 按需沉淀。团队里有一类经常出现、流程固定的任务，就写成 SKILL.md 放进.agents/skills/，跟代码一起进仓库，团队共享。独立的小任务派给子代理，不占主对话上下文。这两样用好了，Agent 的效率会有明显提升。
如果你打算长期做编码类任务或跑 Agent，Coding Plan 比按量调用更适合高频场景，地址是 https://taotoken.net/coding-plan 。需要管理多个 Key 或查看用量，去控制台 https://taotoken.net/console 。创建新 Key 在 https://taotoken.net/api-keys 。想先试试模型效果，模型对话页面在 https://taotoken.net/chat 。接入细节和协议说明在 https://taotoken.net/doc 。
最后给一个实用技巧：把 dsh 的 headless 模式和 TaoToken 通道结合，可以写一个简单的脚本，在 CI 里跑一次性 Agent 任务。比如：
export TAOTOKEN_API_KEY="你的Key" dsh --profile headless "检查代码里有没有 TODO 注释，列出来"任务成功退出码为 0，失败为 1，可以直接接进流水线。这样你不在电脑前的时候，Agent 也能替你干一些固定的检查活。跑通这一步，你就算真正把 dsh 和 TaoToken 用起来了。
