本文基于 deepseek-harness 官方仓库 及其相关文档整理涵盖安装、模型配置、Web UI 使用与常见问题排查适合第一次接触该项目的开发者。一、什么是 DeepSeek HarnessDeepSeek Harness命令行简称dsh是 DeepSeek AI 开源的一个 Agent Harness智能体运行框架。它采用一切皆插件Everything is a Plugin的架构理念底层由 Cordis 驱动相关设计思想可参考论文《A Programming Paradigm for Spatiotemporal Composability》。需要注意的是该项目目前处于开发者预览Developer Preview阶段仍在快速迭代中官方明确提示后续版本可能出现不兼容改动生产环境使用需谨慎。二、安装方式官方 README 提供了两种运行方式通过 npm 直接运行或者从源码克隆构建。方式一通过 npm 运行推荐新手只需要先安装好Node.js然后执行一条命令即可npx deepseek-ai/dsh web该命令会启动 Web UI默认监听地址为http://127.0.0.1:3080启动后浏览器打开这个地址就能看到管理界面了。这是最简单的体验方式不需要克隆仓库、不需要本地构建。方式二从源码运行如果你想参与开发、调试插件或者需要使用最新的 master 分支代码可以从源码运行git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web这里需要注意项目使用pnpm作为包管理器如果本地没有安装需要先执行npm install -g pnpm进行全局安装。构建pnpm run build这一步不能省略否则pnpm dsh web可能无法正常启动。两种方式最终效果一致都会启动本地 Web UI 服务。三、配置模型Web UI 启动之后一个全新的实例其实还不能直接使用——因为它既没有配置任何模型也没有选定工作区。这一步是很多新手容易卡住的地方下面分别说明。3.1 配置 DeepSeek 官方模型打开Settings → Models设置 → 模型你会看到一个 DeepSeek 卡片里面只有一个 API Key 输入框。填入你的 DeepSeek API Key 并保存即可保存后立即生效无需重启服务。需要特别说明的是安全机制Key 是只写的页面保存后只会返回一个脱敏后的描述符永远不会把明文密钥再显示出来。密钥实际存储在$DSH_HOME/.credentials.yaml文件中而settings.yaml里只保留对这个凭证的引用不会明文落盘在配置文件里。3.2 添加目录内其他厂商模型如 Anthropic、OpenAI点击Add provider添加提供商选择目录中已内置的厂商比如 Anthropic、OpenAI填入对应 API Key 并保存。这类目录内厂商会自动带出预置的接口地址、协议和模型列表不需要手动填写。但要注意像 Bedrock、Vertex、Azure、Codex 这几类提供商用的是原生认证方式分别对应 AWS 凭证 region、ADC 项目、api-version、OAuth只填 API Key 字段是配置不好的需要按各自的原生凭证要求填写。3.3 添加自定义提供商企业网关 / 自建服务如果你用的是公司内部网关、自建的模型服务或者是目录里没有收录的提供商选择Add a custom provider添加自定义提供商需要填写小写的 Provider ID永久不可更改因为请求记录、已保存会话、模型默认值、凭证引用都会用到它如果要改名只能新建一个再删除旧的Base URLAPI 协议凭证至少一个模型也可以点击Fetch available models获取可用模型系统会用当前表单里的 Base URL 和凭证去请求该服务的模型列表注意选中的候选模型只是更新了草稿必须点击保存才会真正生效。3.4 关于图片输入视觉模型配置这是一个容易踩坑的细节手动录入的模型默认会被当作纯文本模型因为系统本身无法探测某个接口到底支持哪些模态。如果你给这种模型发送图片请求会在发出前就被拒绝并明确提示是哪个模型不支持。如果你的自定义提供商里有支持视觉的模型需要手动在$DSH_HOME/settings.yaml里给该模型加一行input配置llm-pi-ai: providers: my-gateway: apiKeyEnv: GATEWAY_API_KEY api: openai-completions baseURL: https://gateway.example/v1 models: - id: legacy-chat - id: vision-preview input: [text, image]input只能填text和image且只对当前这一个模型生效方便同一个 provider 下不同模型区别对待。[这部分还没测后续更新]如果不写或写成空列表则会沿用目录内该模型的默认记录若目录里也没有描述,再退回使用 provider 级别的defaultInput。如果某个网关下所有手动录入的模型都支持图片可以直接在 provider 级别统一设置defaultInput就不用逐个模型加llm-pi-ai: providers: vision-gateway: apiKeyEnv: GATEWAY_API_KEY api: openai-completions baseURL: https://vision.example/v1 defaultInput: [text, image] models: - id: first-model - id: second-model要注意defaultInput只是兜底值不是强制覆盖默认值本身是[text]。对于目录厂商如 Anthropic它只对目录没有描述的模型生效不会把目录里本来支持图片的模型改成不支持。如果确实要收窄某个目录模型的模态需要写在modelOverrides里llm-pi-ai: providers: anthropic: modelOverrides: claude-sonnet-4-5: input: [text]另外这两个字段input/defaultInput只是声明系统并不会替你去验证接口真实能力——如果你声明了图片支持,但接口其实不支持,请求依然会被下游服务拒绝而不是在本地拦截。3.5 选择模型配置好的提供商会出现在模型选择器里。选中某个模型后它会成为新会话的默认模型已经发过请求的旧会话则会继续沿用当时记录在日志里的模型不会被新的默认值影响。如果之前设置的默认模型所属的提供商被删除了会话输入框会显示Select model请选择模型并锁定输入直到你重新选一个可用模型。四、开始使用 Web UI模型配置完成后就可以正式进入使用流程了。4.1 选择工作区点击Choose workspace选择工作区添加你启动dsh时所在的项目目录并选中它。这一步不能跳过——没有选定工作区之前会话输入框是不可用的。这里有个细节dsh进程默认会以它被调用时所在的目录作为文件系统的默认位置但即便如此全新启动的 Web UI 仍然不会自动带出这个工作区需要你手动添加、选中。4.2 发起一个任务工作区选好之后就可以开启一个会话直接对话即可比如输入Summarize this repository and identify its main packages. 总结一下这个仓库并指出它的主要模块。Agent 具备的能力包括读写工作区文件、执行命令、任务委派、维护执行计划。在当前权限策略下如果某个操作需要审批Web UI 会先弹出确认再执行避免未经允许的高风险操作。五、常见问题排查官方文档给出的几个高频报错和解决办法报错/现象原因与解决办法MISSING_CREDENTIAL缺少凭证。到 Models 页面配置对应厂商的 Key或提供文档中引用的环境变量。UNKNOWN_MODEL选择了未配置的模型。请在模型选择器中选一个已配置的模型或在自定义提供商里补上这个模型。Fetch available models 返回 401Key 不对。另外注意模型发现功能调用的是 OpenAI 兼容的GET /models接口如果对方接口没有这个端点只能手动填写模型列表。图片在发送前就被拒绝该模型没有声明图片模态。给自定义提供商的模型加上input: [text, image]注意 DeepSeek 官方 chat-completions 接口本身是纯文本的无法通过配置开启图片支持。服务端拒绝携带图片的请求说明模型声明了图片能力但实际接口不支持。需要去掉相应input或defaultInput里的image并开一个新会话——因为已经发出的图片会留在会话日志里同一会话继续沿用旧配置会反复报错。六、进阶与延伸阅读如果基础使用已经跑通想进一步深入可以参考以下几个方向多提供商 / 高级配置完整字段和默认值可查阅插件配置目录文档以及dsh-llm-pi-ai、dsh-llm-deepseek两个包各自的 README里面有更细的凭证、推理控制、适配器报错说明。Python SDK如果想用代码而非 Web UI 驱动 Agent可参考官方的 Python SDK 使用文档。其他 CLI 模式除了dsh web启动网页端CLI 还有别的运行模式可参考apps/cli下的 README。插件开发项目的核心卖点就是一切皆插件如果想自己写插件扩展能力可以从开发指南入手。参与社区可以通过 GitHub Discussions 提反馈或报 Bug如果自己写了插件给仓库打上dsh-plugin这个 topic 标签方便别人发现官方也有 Discord 社区可以加入交流。七、小结总体来看DeepSeek Harness 的上手路径是这样一条主线装环境npx deepseek-ai/dsh web或源码构建启动 Web UI配模型在 Settings → Models 里填 DeepSeek Key或接入其他厂商/自定义网关选工作区把项目目录添加为工作区发消息像聊天一样直接把任务交给 Agent。由于项目仍处于开发者预览阶段建议关注官方仓库的更新动态遇到接口或配置字段变化属于正常现象以 官方 README 为准即可。参考链接项目主页https://github.com/deepseek-ai/deepseek-harnessWeb UI 使用指南https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.md模型配置指南https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md