DeepSeek Harness 接入 B.AI API 官方配置指南
- 核心观点：本文提供了一份技术教程，详细介绍了如何在Windows、macOS和Linux系统中启动开源AI工作区应用DeepSeek Harness，并通过自定义Provider机制将其与B.AI大模型服务平台集成，实现本地工作区到大模型的调用闭环。
- 关键要素：
- 环境准备要求Node.js LTS版本，通过`node -v`、`npm -v`、`npx -v`命令验证安装是否完成，三系统安装方式略有差异。
- 推荐使用`npx @deepseek-ai/dsh web`快速启动，首次运行需确认下载依赖，成功启动后本地访问地址为http://127.0.0.1:3080。
- 进阶开发可通过GitHub仓库获取源码，提供ZIP下载和Git克隆两种方式，均需安装pnpm并执行构建命令。
- B.AI Provider配置需跳过官方默认API Key弹窗，在设置页添加自定义提供方，填写Provider ID为bai、API地址https://api.b.ai/v1、协议选择openai-completions。
- 模型目录建议通过"获取可用模型"自动拉取，模型ID必须与B.AI返回结果完全一致，避免手动修改导致model not found错误。
- 链路验证包含基础对话测试和工具调用测试（只读指令），需同时监控终端日志确认无401、404等异常报错。
- 常见问题涵盖端口占用、鉴权失败、模型ID不匹配等七类典型故障，文末附有官方参考链接资源。
DeepSeek Harness 是一款备受瞩目的开源 AI 工作区应用，目前正处于开发者预览阶段。它不仅能深入本地工作区协助代码与文件分析，还通过开放的自定义 Provider 机制，赋予了开发者极大的灵活性。而 B.AI 作为先进的 AI 基础设施，打造了集高可用、低延迟于一体的全栈式大模型服务平台，致力于为开发者与企业构建强大、稳定且极具弹性的智能算力网络。
本指南将为您详细演示，如何在 Windows、macOS 和 Linux 环境中从零启动 DeepSeek Harness，并成功将其与 B.AI API 进行集成。跟随本教程，您将打通从本地工作区到大模型的全链路调用闭环，全面释放 AI 驱动的生产与创新潜力。
最终实现的调用链路： DeepSeek Harness → B.AI API → B.AI 提供的模型
1. 准备环境
DeepSeek Harness 通过 Node.js 自带的 npx 启动。请确保您的系统已安装当前可用的 Node.js LTS 版本。
官方下载地址： https://nodejs.org/en/download
- Windows
可直接下载 .msi 安装包，也可以在开始菜单中搜索 PowerShell，打开后运行 WinGet 安装命令。
winget --version winget install --id OpenJS.NodeJS.LTS -e --source winget
- macOS
在 Node.js 官方下载页面选择 macOS Installer，下载 .pkg 文件并按提示完成安装。安装结束后，按 Command + Space 打开聚焦搜索，输入 Terminal，进入终端。
- Linux
请在 Node.js 官方下载页面选择您所使用的 Linux 发行版与系统架构，并按照页面提供的包管理器命令安装 LTS 版本。由于 Ubuntu、Debian、Fedora 等不同发行版的安装命令存在差异，建议以官方页面动态生成的命令为准，以确保安装过程稳妥无误。
安装结束后，关闭当前所有已打开的终端窗口，并重新开启一个新的终端（Windows 用户请使用 PowerShell，macOS 用户使用 Terminal，Linux 用户使用系统终端）。
在三个系统中，均运行以下同一组检查命令：
node -v npm -v npx -v
三条命令均返回版本号即代表环境准备就绪。
Node.js v24.19.0 npm 11.17.0 npx 11.17.0
若您准备通过 GitHub 源码构建并运行项目，则需依赖 Git 环境。请先在终端运行 git --version 检查是否已安装。如未安装，请根据您的操作系统执行以下命令：
Windows
winget install --id Git.Git -e --source winget
macOS
xcode-select --install
Ubuntu 或 Debian
sudo apt update sudo apt install git
注：如果您仅计划使用 npx 方式快速体验并配置 B.AI，可直接跳过 Git。
2. 使用 npx 启动 DeepSeek Harness (推荐)
对于常规使用及配置 B.AI API 的开发者，推荐直接使用 npx 启动。
在终端中运行以下命令（三端系统通用）：
npx @deepseek-ai/dsh web
首次运行提示： 系统会询问是否下载所需软件包，输入 y 并回车确认。
Need to install the following packages @deepseek-ai/dsh@... Ok to proceed? (y)
启动过程中若出现依赖弃用警告，属于正常现象，无需干预。
npm warn deprecated node-domexception@1.0.0
当终端输出本地地址时，说明 DeepSeek Harness 的 Web 服务已经成功启动。
dsh web: http://127.0.0.1:3080
保持终端窗口开启，然后在浏览器地址栏输入：
http://127.0.0.1:3080
该地址仅限本机访问。若关闭终端窗口或在窗口中按下 Ctrl+C，本地服务将随之停止。如果浏览器无法打开 127.0.0.1:3080，请首先检查终端是否仍在运行，并确认终端内是否已输出上述 dsh web 地址。必要时，请重新运行启动命令。
npx @deepseek-ai/dsh web
3. 源码构建方式（进阶）
若您计划开发插件、修改源码，或者参与项目开发，也可以从官方 GitHub 仓库获取源码。
官方仓库： https://github.com/deepseek-ai/deepseek-harness
请注意，GitHub 提供的是项目源代码，下载后必须通过终端完成依赖安装与项目构建，无法通过双击文件直接运行。您可以通过以下两种方式获取并运行源码：
方式一：下载 ZIP 源码包 在仓库页面点击绿色的 Code 按钮，选择 Download ZIP。下载并解压后，打开终端，使用 cd 命令进入解压后的项目目录，依次运行以下命令：
npm install -g pnpm pnpm install pnpm run build pnpm dsh web
方式二：使用 Git 克隆 建议先运行 git --version 检查 Git 环境是否存在。如未安装，请参考前文「准备环境」部分完成相应系统的 Git 安装。确认环境无误后，重新打开终端，运行以下命令：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness npm install -g pnpm pnpm install pnpm run build pnpm dsh web
无论使用 ZIP 还是 Git 方式，构建并启动成功后，访问地址同样为 http://127.0.0.1:3080。
4. B.AI 自定义 Provider 配置
步骤一、跳过官方默认配置
首次进入 DeepSeek Harness 时，系统会弹出官方模型的 API Key 填写窗口。请务必点击「稍后配置」。若在此处填入 B.AI 的 Key，系统将无法正确识别。
步骤二、进入自定义配置页
点击页面左下角的「设置」，在左侧菜单选择「模型」，点击右侧的「添加自定义提供方」。注：此时官方 Provider 显示红点属于正常状态，不影响后续操作。
步骤三、填写 B.AI 接口信息
打开自定义提供方以后，按下面的内容填写。
Provider ID bai 显示名称 B.AI API 地址 https://api.b.ai/v1 API 协议 openai-completions API 密钥 从 B.AI 后台创建的有效 API Key
步骤四、获取模型目录并完成 Provider 创建
基础信息填写完毕后，请向下滚动至「模型目录」区域。系统提供两种添加方式：点击「添加模型」手动填写模型 ID，或点击右上角的「获取可用模型」。
推荐操作： 首选点击「获取可用模型」。 让 DeepSeek Harness 直接向 B.AI 请求当前账号可用的模型目录。若模型列表能正常返回，即证明 B.AI API Key、https://api.b.ai/v1、openai-completions 协议，以及模型目录接口等配置已成功连通。
模型选择与添加注意：
- 在返回的列表中，勾选 B.AI 当前可用的 DeepSeek 模型（示例可见 deepseek-v4-flash 或 deepseek-v4-pro，请注意：具体可用模型会随账号权限和时间动态变化，请以实际返回结果为准）。
- 请勿修改模型 ID： 模型 ID 必须与 B.AI 实际返回的目录完全一致。请勿擅自更改任何大小写、连字符或版本号，否则在后续调用时极易触发 model not found 错误。
确认模型添加无误后，滚动至表单底部，点击「创建提供方」。
创建成功后，设置页面将新增一个名为 B.AI 的自定义 Provider，且旁边显示绿色圆点。这代表 B.AI 自定义 Provider 已成功保存并处于可用状态。 注：此时 DeepSeek 官方 Provider 若仍显示红点，系未填写 DeepSeek 官方 API Key 所致，这不影响绿点对应的 B.AI 接口正常使用。
步骤五、 链路连通性验证
关闭设置窗口，返回主界面新建一个会话。在模型选择器中选择 B.AI Provider，再选择刚刚添加的 DeepSeek 模型，进行以下测试：
基础对话测试： 在模型选择器中选定 B.AI 及对应模型，发送指令：
请介绍一下你自己，并说明当前正在使用的模型。
观察它能不能正常返回内容，是否有流式输出，同时确认当前 Provider 是 B.AI，模型 ID 也和你选择的一致。
工具调用测试： 发送只读指令验证工具链路：
请查看当前工作区的文件，并总结目录结构。不要修改或删除任何文件。
指令中特别强调“不要修改或删除任何文件”，是为了在不改动当前工作区的前提下，安全、快速地验证 Harness 的工具调用链路是否畅通。
在执行上述两项测试时，请回头查看运行 DeepSeek Harness 的终端窗口，确认控制台未出现 401、404、model not found 或其他请求报错信息。若终端运行平稳，至此您已成功完成所有接入与验证工作。
💡常见问题 Q&A
Q1：终端提示找不到 node、npm 或 npx 命令？
A： 这通常是 Node.js 尚未安装完成，或者新安装的命令路径还没有被当前终端读取。关闭所有终端窗口，重新打开，再运行。
node -v npm -v npx -v
依然找不到命令时，回到 Node.js 官方下载页面，确认已经安装当前的 LTS 版本。Windows 用户还可以在系统的「已安装的应用」中检查 Node.js，macOS 和 Linux 用户可以运行 which node 查看命令路径。
Q2：启动时出现 npm warn deprecated，需要处理吗？
请优先确认后面有没有出现下面这个地址：
dsh web: http://127.0.0.1:3080
若该地址正常显示，则代表 Web 服务已成功启动。deprecated 在这次实测中属于依赖弃用警告，可以继续使用。若终端随后异常退出或未输出本地地址，请再根据终端末尾的具体报错信息进行排查。
Q3：浏览器无法打开 127.0.0.1:3080，怎么办？
A：请首先检查运行 dsh web 的终端窗口是否仍处于开启状态。关闭该终端或使用 Ctrl+C 快捷键均会终止本地服务。
若服务已停止，请重新执行启动命令：
npx @deepseek-ai/dsh web
若终端提示“端口被占用”：请先结束之前残留的 DeepSeek Harness 进程，而后重试。
Q4：调用模型时遇到 401 Unauthorized 报错，如何排查？
A： 401 错误通常指向 API Key 鉴权失败。请检查：
- API Key 是否完整复制，首尾有无多余空格。
- 确认该 API Key 在 B.AI 控制台中是否处于有效（未停用）状态。
- 确认 Key 填入了正确的配置项中：请勿将其填入首次弹窗的“DeepSeek 官方 Provider”中，而必须填入「设置 → 模型 → 添加自定义提供方」对应的 B.AI 接口内。
Q5：调用模型时遇到 404 Not Found ，是哪里填写有误？
A： 请检查 API 地址是否填写完整。
https://api.b.ai/v1
Q6：提示 model not found，如何解决？
A： 请返回 B.AI 自定义 Provider 的编辑页面，重新点击「获取可用模型」。请确保所选择或填写的模型 ID 与系统返回的结果完全一致，严格保留所有大小写、连字符和版本号。此外，账号权限更新或官方模型目录调整也可能导致旧模型不可用，如遇报错，请一律以当前重新获取到的模型列表为准。
Q7：B.AI 状态显示绿点，但依旧无法对话？
A： 绿点仅代表配置信息已保存。若无法对话，请确认当前会话已正确选中 B.AI Provider 及对应的具体模型，模型 ID 准确无误，且您的 B.AI 账户具有对应模型的调用权限与可用额度。随后，请结合终端最后的报错代码（如 401/404）进行针对性排查
Q8：Windows、macOS 和 Linux 系统的接入页面会有差异吗？
A： 三个系统的准备环境略有差异。dsh web 启动后，所有系统均通过浏览器访问 http://127.0.0.1:3080，添加 B.AI Provider、获取模型和验证对话的步骤基本一致。
参考链接：
Node.js 官方下载页面：https://nodejs.org/en/download
DeepSeek Harness 官方仓库：https://github.com/deepseek-ai/deepseek-harness
B.AI API 文档：https://docs.b.ai/llmservice/api/
