随着AI Agent技术快速发展，很多开发者在搭建智能体时会遇到工具调用混乱、模型切换繁琐、扩展困难等痛点。DeepSeek Harness作为一款开源微内核AI Agent运行框架，采用“一切皆插件”的设计思路，把大模型、工具集、沙箱环境、存储、UI界面全部做成可插拔组件，开发者可以自由替换模型、增减工具，快速搭建具备自主规划、工具调用、迭代执行能力的AI智能体。它同时提供Web可视化界面和命令行CLI两种操作模式，既适合新手可视化操作，也适合技术人员在服务器端自动化调用。可以部署在本地电脑，也可以直接在ECS云服务器上部署，并且能够对接百炼平台模型，使用Token Plan订阅套餐降低调用成本。本文为保姆级完整教程，从环境准备、多种安装方式、百炼模型接入、Profile环境管理、插件安装、任务实战，再到运维命令、常见报错排查完整讲解，附带大量可直接复制执行的代码命令，零基础用户也可以跟着步骤成功部署并使用DeepSeek Harness。
一、DeepSeek Harness核心概念与架构介绍
DeepSeek Harness底层基于Cordis微内核架构，内核本身只负责插件加载、依赖调度、生命周期管理，不绑定任何大模型和固定工具，所有能力全部依靠插件实现。这里有两个核心名词，新手必须理解：Profile和Bundle。Profile可以理解为一套独立的Agent运行环境，包含模型配置、已安装插件、会话记录、本地存储，你可以创建多个不同Profile，不同项目、不同实验环境相互隔离，测试新插件时新建Profile，即使环境损坏，也不会影响主工作环境。Bundle是插件打包分发单元，一个Bundle可以一次性批量安装多个关联插件，快速给Profile增加整套能力，比如代码沙箱、文件处理、网页检索等工具包。
Harness原生支持OpenAI兼容协议接口，所以可以接入多种大模型，包括百炼平台Qwen系列模型，搭配Token Plan订阅套餐使用。Agent运行流程分为任务规划、工具调用、结果校验、迭代重试。当用户提交复杂任务，Harness会自动拆解子任务，判断是否需要调用工具，执行工具动作，拿到结果之后交给模型继续推理，如果结果不达标会自动重试，形成完整Agent循环。支持文件读写、Shell命令执行、代码沙箱、网页抓取、MCP协议工具扩展，适合代码开发、文档批量处理、资料调研、自动化脚本编写等场景。同时支持WebUI可视化交互和CLI命令行模式，服务器后台无人值守任务优先使用CLI，日常调试任务推荐WebUI界面。
阿里云部署AI Agent：OpenClaw/Hermes Agent全网最简单，只需两步，详情👉访问阿里云OpenClaw/Hermes一键部署专题页面了解。
Token Plan Token 最便宜/支持多模型切换：👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。
二、部署前置环境准备
安装DeepSeek Harness首要依赖Node.js运行环境，版本要求Node.js >=22.19或者24及以上版本。Windows、macOS、Linux（ECS服务器Ubuntu系统）都支持。先打开终端，执行下面命令检测Node是否安装成功。
node --version
npm --version
如果输出版本号，说明环境就绪；如果提示命令不存在，需要前往Node官网下载对应系统LTS版本安装。ECS服务器Ubuntu系统安装Node命令如下：
sudo apt update && sudo apt install curl -y
curl -fsSL https://deb.nodesource.com/node_22.x | sudo -E bash -
sudo apt install nodejs -y
node --version
npm --version
安装完成之后，需要启用corepack，用于管理pnpm，Harness插件安装依赖pnpm包管理器：
corepack enable pnpm
pnpm --version
在ECS服务器部署时，需要提前放行WebUI端口，默认WebUI端口为3080，在安全组开放3080端口，同时防火墙放行端口，执行：
sudo ufw allow 3080/tcp
sudo ufw reload
准备API密钥，前往百炼控制台创建API Key，支持Token Plan个人版、团队版，保存密钥，后续配置模型时使用。
三、三种安装方式，按需选择
方式1：npx一键临时启动（新手体验首选，无需全局安装）
不需要下载源码，不需要全局安装包，直接npx命令在线拉起WebUI，适合快速体验。
npx @deepseek-ai/dsh web
首次运行会提示确认安装依赖，输入y回车等待下载。启动成功后终端输出访问地址，本地环境访问http://127.0.0.1:3080；ECS服务器部署，则访问http://ECS公网IP:3080。如果需要自定义端口，执行：
npx @deepseek-ai/dsh web --port 8080
注意，终端窗口必须保持打开，关闭终端，Harness服务就会停止。
方式2：全局安装（长期使用推荐，任意位置调用dsh命令）
全局安装之后，系统全局可用dsh命令，不需要每次npx拉取。
npm install -g @deepseek-ai/dsh
安装完成验证版本：
dsh --version
启动WebUI：
dsh web
进入CLI交互式终端模式：
dsh chat
方式3：源码编译安装（二次开发、深度定制场景）
如果需要修改底层代码，自定义插件，选择源码部署，ECS服务器开发环境推荐此方式。
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm build
# 启动web界面
pnpm run web
源码部署完成后，配置文件、日志目录都在项目目录内，方便修改底层逻辑。
四、接入百炼模型，配置Token Plan接口
Harness支持自定义模型服务商，我们添加百炼作为模型提供方，两种配置方式，Web界面可视化配置或者直接修改yaml配置文件。
方式1：WebUI界面可视化配置（新手推荐）
打开WebUI页面，找到Settings（设置）→Models（模型）→Add a custom provider，新增服务商。
- Provider ID填写：bailian-tpp
- BaseURL：https://dashscope.aliyuncs.com/compatible-mode/v1
- API Key填入百炼Token Plan生成的sk开头密钥
- 模型列表添加qwen3.8-max、qwen3.7-plus、qwen3.7-flash等模型ID
保存配置，在模型下拉框选中对应的Qwen模型，即可使用百炼Token Plan套餐的算力。
方式2：直接修改配置文件settings.yaml
配置文件路径，Linux/ECS服务器：~/.dsh/settings.yaml，Windows在用户目录下.dsh文件夹。
vim ~/.dsh/settings.yaml
写入配置内容：
agent-default-model:
provider: bailian-tpp
model: qwen3.8-flash
llm-pi-ai:
providers:
bailian-tpp:
api: openai-completions
baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
apiKeyEnv: BAILIAN_API_KEY
models:
- id: qwen3.8-max
- id: qwen3.8-flash
- id: qwen3.7-plus
保存退出，在环境变量中设置BAILIAN_API_KEY，Linux临时设置：
export BAILIAN_API_KEY="sk-替换为你的百炼TokenPlan密钥"
永久写入环境变量，编辑bash配置文件：
vim ~/.bashrc
# 在文件末尾添加
export BAILIAN_API_KEY="sk-替换为你的百炼TokenPlan密钥"
source ~/.bashrc
配置完成，执行健康检查命令，校验整个环境是否正常：
dsh doctor
dsh doctor命令会自动检测Node版本、pnpm、配置文件、模型接口连通性，输出所有问题，方便定位故障。
五、Profile环境管理核心命令
Profile是Harness最核心的隔离机制，下面是Profile常用操作命令。
# 创建新的profile，命名为project-demo
dsh profile create project-demo
# 查看本机所有profile列表
dsh profile list
# 切换当前使用profile
dsh profile use project-demo
# 删除无用profile（谨慎操作，会清空这个环境所有插件、会话记录）
dsh profile remove project-demo
# 导出当前profile配置备份
dsh profile export project-demo ./project-demo-backup.json
# 导入备份profile
dsh profile import ./project-demo-backup.json
推荐不同业务项目使用独立Profile，例如一个profile专门做代码开发，另一个profile用于文档分析，插件和会话数据相互隔离，不会互相干扰。
六、插件安装、管理，扩展Agent能力
Harness所有工具能力依靠插件，文件读写、代码沙箱、网页抓取、MCP工具全部以插件形式安装。安装插件通用命令格式：
dsh plugin --profile 你的profile名称 add 插件包地址
示例，给默认default环境安装代码沙箱插件：
dsh plugin --profile default add dsh-sandbox
查看当前环境已安装插件列表：
dsh plugin --profile default list
卸载不需要的插件：
dsh plugin --profile default remove dsh-sandbox
更新插件到最新版本：
dsh plugin --profile default update
查看插件详细文档：
dsh plugin --profile default info dsh-sandbox
插件安装注意事项：出于安全限制，插件构建脚本默认禁止执行。如果插件需要编译构建，需要在profile的pnpm-workspace.yaml添加信任白名单，或者执行交互式批准命令：
cd ~/.dsh/profiles/default
pnpm approve-builds
执行命令之后，交互式界面勾选信任的插件依赖，允许构建脚本运行。
七、任务实操，WebUI与CLI两种模式实战
WebUI模式实战
打开Web界面，选择配置好的百炼Qwen模型，直接输入自然语言任务指令。例如输入：读取当前目录的项目文档，梳理项目需求，编写Python脚本实现数据清洗，执行脚本并输出结果。Harness会自动拆解任务，读取文件，调用代码沙箱编写代码，运行脚本，捕获报错，迭代修改代码，输出最终结果。在对话页面可以查看Agent每一步思考日志、工具调用记录，每一步操作都可追溯，可以随时中断任务，修改提示词继续执行。
CLI命令行模式实战（服务器无人值守场景）
进入dsh交互式对话：
dsh chat --profile default
输入任务指令，Agent执行任务。也可以直接单次执行任务，非交互式，适合脚本自动化调用：
dsh run --profile default "读取./report.md，提取核心结论，整理成结构化markdown报告保存为summary.md"
也可以编写shell脚本批量执行任务，示例脚本dsh_task.sh：
#!/bin/bash
export BAILIAN_API_KEY="sk-替换密钥"
dsh run --profile default "分析./sales.csv，生成数据分析结论并输出图表描述"
赋予执行权限，定时执行：
chmod +x dsh_task.sh
# 定时任务，每天凌晨3点自动执行
crontab -e
0 3 * * * /home/ubuntu/dsh_task.sh >> ./task_log.txt
八、常用运维命令与日志查看
# 查看dsh帮助文档
dsh --help
# 查看web服务日志，实时跟踪任务执行信息
dsh logs -f
# 清理缓存，插件缓存、会话临时文件
dsh cache clean
# 重置当前profile所有配置，插件保留，清空模型配置
dsh config reset llm
# 导出会话记录，用于复盘Agent执行过程
dsh session export session01 ./session_backup.json
ECS服务器部署，设置systemd实现Harness开机自启，创建服务文件：
sudo vim /etc/systemd/system/dsh.service
写入内容：
[Unit]
Description=DeepSeek Harness Web Service
After=network.target
[Service]
User=ubuntu
Environment="BAILIAN_API_KEY=sk-替换密钥"
WorkingDirectory=/home/ubuntu
ExecStart=/home/ubuntu/.npm-global/bin/dsh web --port 3080
Restart=on-failure
[Install]
WantedBy=multi-user.target
启用开机自启：
sudo systemctl daemon-reload
sudo systemctl enable dsh
sudo systemctl start dsh
# 查看服务运行状态
sudo systemctl status dsh
九、常见报错与避坑指南
- node版本不兼容报错：提示版本过低，需要升级Node到22.19及以上版本，使用nvm管理多Node版本。
- MISSING_CREDENTIAL密钥缺失：检查环境变量BAILIAN_API_KEY是否正确，WebUI内填写密钥保存后刷新页面，密钥不要带多余空格换行。
- UNKNOWN_MODEL模型不存在：核对模型ID，百炼Qwen系列模型ID不能写错，在provider配置内手动添加模型ID。
- 插件安装失败，pnpm构建脚本禁止：执行pnpm approve-builds，信任插件依赖，或者修改白名单配置。
- ECS服务器Web页面打不开：检查安全组3080端口放行，服务器本地防火墙ufw放行端口，确认服务正常运行。
- Agent执行Shell命令权限风险：默认沙箱插件做权限隔离，不要给Harness分配root权限运行，防止AI执行高危系统命令删除文件。
- Token消耗管控：在百炼控制台开启用量告警，优先使用Flash系列模型做简单任务，复杂推理任务切换Max模型，减少不必要的高级模型调用，控制套餐积分消耗。
十、场景选型与落地建议
DeepSeek Harness强大的插件化架构，适合多种AI Agent场景。开发人员可以搭建编程助手，自动编写、调试代码，排查项目bug；业务人员可以用来批量解析文档、自动撰写调研报告；运维人员在ECS服务器部署，定时执行日志分析、巡检脚本。本地电脑部署适合日常调试实验；ECS服务器部署适合长期7×24小时运行自动化任务，搭配百炼Token Plan套餐，降低模型调用成本。
新手入门建议流程：先用npx命令本地快速体验，熟悉WebUI交互；确认功能满足需求之后，全局安装dsh；新建独立Profile做实验，不要直接在默认Profile大量安装插件；优先使用官方插件，第三方社区插件使用前评估安全风险；配置好百炼模型之后，先用简单任务测试连通，再尝试多步骤复杂Agent任务。
Harness微内核插件化的设计带来极高的灵活性，你可以随时替换底层大模型，自由增减工具能力，自定义Agent执行逻辑，相比很多封装固定的AI Agent平台，二次开发空间更大。这套从0到1的完整流程，覆盖本地电脑和ECS服务器部署，对接百炼模型订阅套餐，只需要按照本文命令一步步操作，就能快速搭建属于自己的可扩展开源AI智能体。随着不断新增插件，持续丰富工具集，可以逐步搭建满足开发、文档处理、自动化任务等各类需求的Agent工作流。
