Agent harness 是什么?它与模型和框架的区别
了解 agent harness 如何通过循环、工具、权限、会话状态和工作目录运行模型,及其与模型、运行框架的区别;Claude Code、Codex、Gemini CLI 均采用这种划分。
Agent harness 是什么
Agent harness 是围绕语言模型运行、并将其转变为 agent 的程序。它负责维护持续调用模型的循环、模型可以调用的工具定义、决定哪些调用实际执行的权限规则、在多轮交互之间保留的会话状态,以及执行任务的工作目录。其中的模型可以替换。
请记住上一句。模型单独运行时,只会回答问题,然后忘记您。Harness 会询问模型下一步该做什么,执行模型请求的命令,将结果反馈给模型,然后再次询问。人们所说的“agent”,指的就是这种重复过程。如果相关术语仍不清晰,可以先阅读AI agent、LLM 和 assistant 的区别,再选择工具。
框架并非模型
两者常被混淆,因为供应商以同一个品牌名称发布它们。
dsh 和 DeepSeek 是不同的产品。DeepSeek Harness 于 2026 年 8 月 13 日在 github.com/deepseek-ai/deepseek-harness 发布,采用 MIT 许可证,是一个安装在机器上的 Node 程序。DeepSeek 模型则是通过 API(应用程序接口)提供服务的权重文件。将 dsh 指向其他供应商的模型,它依然可以正常工作,因为框架只需要一个能够接收消息并返回工具调用的接口。
Claude Code 和 Claude 是同类组合。Claude Code 是一个框架:一个包含循环、权限系统以及文件和 Shell 工具的终端程序。Claude 是它默认调用的模型系列。Codex 和 Gemini CLI 的划分方式相同。
以下是每次都能验证这一点的测试方法。安装一个框架。调用一个模型。如果该程序在你的磁盘上有版本号,且在你的主目录下有配置文件,那么它就是框架。如果它是配置文件中的一个字符串,例如 deepseek-flash,那么它就是模型。
循环实际执行的内容
一次 harness 循环如下所示。请慢慢阅读,因为不同 harness 之间几乎所有差异,都体现在这 5 个步骤中。
- harness 将当前为止的对话以及工具定义列表发送给模型。
- 模型返回文本,或请求调用其中一个工具。
- harness 根据权限规则检查该请求,然后执行工具,或暂停并请求您的确认。
- harness 运行工具,捕获输出和退出码;如果输出过长,则将其截断。
- harness 将结果追加到对话中,然后返回第 1 步。
在日常使用中,第 3 步最能体现 harness 之间的差异。每条命令都先询问的 harness 更安全,但也令人疲惫。完全不询问的 harness 最终可能会在模型判断错误的路径上执行破坏性命令。现在,所有成熟的 harness 都提供一种折中设置:允许列表中的命令无需询问即可运行,其他命令则显示提示并请求确认。
其余差异主要存在于第 1 步。harness 还会在每次请求中附带 system prompt;Claude Code 直接提供了这个调节选项,因为输出样式会修改它发送的 system prompt,从而改变每次返回的回复。对话会在每一轮中增长,而模型的上下文窗口大小固定,因此 harness 必须决定丢弃哪些内容、总结哪些内容,以及将哪些内容写入文件并在之后读回。正是这一决策,在很大程度上决定了两个使用同一模型的 harness 为何会产生不同质量的结果。如果这 5 个步骤仍然比较抽象,最有效的方法是亲自编写一次简易循环;循序渐进的 AI agent 学习路径正是让您在早期构建这样的循环。
现在,大多数 harness 都通过 MCP(模型上下文协议)接入外部工具。MCP 是一种标准方式,可将工具提供给任何支持该协议的 harness,因此一次集成即可用于多个 harness。在 VPS 上运行 MCP 服务器介绍了这一部分。Web 搜索通常是人们接入的第一个工具;让 agent 使用您自己的 SearXNG 实例可以避免将查询发送给第三方,同时也清楚表明,agent 随后读取的每个页面都是在循环中接收的不可信输入。如果您已经有 DeepSeek API Key,又不想自己维护搜索实例,DeepSeek 的 Search 与 Fetch API可以用同一个密钥为循环提供搜索和网页抓取,代价是查询会发送给 DeepSeek,并按调用次数计费。
Agent harness 与 agent framework 的区别
每当有新的 harness 发布时,这个问题就会出现,且各方观点不一,部分原因是供应商对此定义存在分歧。以下是目前公认的解释。
Framework(框架)是你导入的库。你需要编写循环逻辑,决定何时调用模型,并自行处理工具的执行结果。LangChain 是众所周知的例子:你获取构建模块,然后在代码中组装 agent。
Harness(工具套件)是你运行的程序。循环逻辑已预先编写,工具已内置,权限模型也有默认配置。你执行第一条命令即可获得一个可用的 agent,后续只需进行配置。
安装测试通常能决定其归属。如果你安装后需要编写代码,它就是 framework。如果你安装后直接与其交互,它就是 harness。
这一界限确实存在争议,最明显的证据来自 LangChain 自身的文档。截至 2026 年 10 月,它将 Deep Agents 称为“一个 agent harness”,同时也称其为“构建在 LangChain 核心 agent 构建模块之上的独立库”,而 langchain-ai/deepagents 仓库则自称为“内置全套功能的 agent harness”。这两种描述都合理。Deep Agents 是一个你导入的 Python SDK(软件开发工具包),因此安装测试将其归类为库,但它提供了足够的默认行为,使得人们将其作为 harness 使用。Microsoft 于 2026 年 7 月发布了一个稳定的 agent harness,同月其 Foundry Hosted Agents 正式发布,这表明该术语现在已成为一个产品类别,而非单纯的行业术语。
因此,请通过评估你的工作负载来判断。如果你编写循环,你就拥有该循环的控制权:包括重试机制、上下文裁剪、权限提示以及操作记录。如果循环是预置的,你就继承了他人对上述所有问题的解决方案,这种方式启动速度快,但后续修改难度较大。
聊天窗口与 harness 的区别
聊天窗口和 harness 都会显示模型输出。区别在于工作在哪台计算机上执行。在聊天窗口中,模型运行的任何代码都会在供应商的沙箱内执行,操作的是您上传的文件;会话结束后,这些内容就会消失。harness 则会在您启动它的计算机上运行工具,以启动它的用户身份运行,并操作真实文件,同时使用其环境中的真实凭据。
这两句话概括了它的全部优势和全部风险。代理终于可以执行实际工作。代理也可以删除这些工作。
目前实际运行的开发辅助工具
此列表特意标注为 2026 年 8 月 19 日。该领域每周都在变化,任何汇总信息都会迅速过时。
- Claude Code 和 Codex 是厂商提供的辅助工具。它们以终端为核心,默认绑定厂商自有的模型,并具备最完善的权限管理机制。Claude Code、Cursor、Codex 和 Copilot 的对比 对它们进行了详细分析。
- DeepSeek Harness (
dsh) 采用 MIT 协议,其核心理念是:一切皆插件。因此,模型、工具、会话、沙箱和用户界面均可替换。安装的每个插件都以代理自身的权限运行,因此在添加插件前 检查 dsh 插件的访问权限 比在工具集固定的辅助工具中更为重要。截至 2026 年 8 月 19 日(发布后六天),其 GitHub 星数约为 166,800。 - Hermes(来自 Nous Research)是一个通用自主代理,而非单纯的编码工具。它于 2026 年 2 月以 MIT 协议发布,所有数据均保留在本地:记忆和技能存储在
~/.hermes下的文件中,会话历史记录存储在本地的 SQLite 数据库中。在 VPS 上自托管 Hermes 介绍了具体操作步骤。 - Omnigent 是一款元辅助工具:它在统一的 API 之下驱动其他辅助工具(包括 Claude Code 和 Codex),并提供共享会话、支出上限和操作系统级沙箱。作为多代理辅助工具的 Omnigent 介绍了其带来的优势。
- OneCLI 是一款面向团队的沙箱化辅助工具,其核心是一个网关,可将真实凭据注入出站请求,确保代理本身仅能看到占位符密钥。
其中三个工具经常同时出现在候选名单中,因此建议阅读 DeepSeek Harness、Claude Code 和 Omnigent 的横向对比,了解它们在模型耦合、许可协议、成熟度以及服务器运行要求方面的差异。
dsh 快速启动仅需一条命令,运行一次即可最快了解该辅助工具。机器上需要安装 Node.js。
npx @deepseek-ai/dsh web该命令会在 http://127.0.0.1:3080 启动 Web UI(用户界面)。在依赖它之前请阅读 README,因为 dsh 将自身定义为开发者预览版,并明确指出未来会有破坏兼容性的变更。如果第一条命令直接失败或拉取了非预期的构建版本,锁定确切的 dsh 版本并清除 npx 缓存 通常能解决问题。在 VPS 上运行 DeepSeek Harness 涵盖了服务器安装过程,为什么地址以 127.0.0.1 开头 解释了默认使用回环地址的原因。
路由器位于 harness 之上
模型路由器是 harness 与提供商 API 之间的本地代理。Claude Code Router 是常见示例:它默认绑定到 127.0.0.1:3456,接收 Claude Code 原本会发送给其供应商的请求,并将请求转发到您配置的提供商。harness 不知道发生了变化。
路由器之所以存在,是因为模型可以替换,因此它们很好地证明了本文的核心观点。路由器也会集中风险,因为代理可以看到每个提示词,并持有每个提供商的密钥。应将其视为基础设施,而不是便利工具。harness 保存 API 密钥和模型设置的位置 是下移一层后遇到的同一问题。
当 harness 在 VPS 上运行时会有哪些变化
当 harness 从笔记本电脑迁移到租用的服务器上时,会有四个方面的变化。
合上盖子后它仍会继续运行。 长时间运行的任务不会因为你的通勤或电池电量耗尽而中断。在 tmux 中启动它并脱离会话:
tmux new -s agent
# start the harness, then press Ctrl-b and then d to detach
tmux attach -t agent对于需要在重启后自动恢复的任务,使用用户服务(user service)比终端会话更可靠:
loginctl enable-linger $USER
systemctl --user status my-agent.serviceloginctl enable-linger 是人们容易忽略的部分。如果没有它,systemd 会在你关闭最后一个 SSH (secure shell) 会话时立即停止你的用户服务,导致你注销后代理程序终止,且没有任何错误提示。在 systemd 下以无头模式运行 dsh 中提供了单元文件。一旦服务器上运行了一个会话,开启第二个会话不会产生额外开销,并且 同一台机器上的两个 Claude Code 会话可以互相通信,因此你早上启动的那个会话可以将任务交给另一个,无需手动中转。
它持有你的密钥。 提供商密钥现在存储在服务器的配置文件中。请检查谁有权读取它:
ls -l ~/.config任何以你的用户身份运行的进程都可以读取该文件,这包括代理程序以及代理程序选择运行的任何内容。
它可以访问你的其他机器。 与其他机器处于同一私有网络中的 VPS 为代理程序提供了访问它们的路由。这正是其核心用途,但同时也构成了爆炸半径。
你可以从任何地方访问它。 大多数 harness 都会暴露一个 Web UI,并且出于安全考虑,它们通常将其绑定到回环地址(loopback)。请检查你的配置:
ss -tlnp | grep 3080127.0.0.1:3080 表示只有服务器本身可以连接。0.0.0.0:3080 表示 UI 监听所有接口,这意味着除非前端防火墙拦截了该端口,否则任何能访问服务器公网地址的人都可以连接。截至 2026 年 10 月,dsh 在启动时会拒绝此类通配符地址,但许多其他 Web UI 仍会接受。请通过 SSH 隧道访问回环地址上的 UI,而不是修改绑定地址:
ssh -N -L 3080:127.0.0.1:3080 you@your-server然后在你笔记本电脑的浏览器中打开 http://127.0.0.1:3080。流量通过 SSH 会话传输,因此不会向互联网暴露任何新的内容。
上述每一项同样也是安全论据
请以攻击者的视角重新审视这四个特性。
该程序在无人值守的情况下运行,因此当模型误读路径时,无人能够及时发现。它持有你的密钥,因此任何一个可读取的配置文件都可能导致整个服务商账户被窃取。它能够访问你的其他机器,因此提示词注入(即隐藏在网页或代理读取的文件中的指令)现在有了通往数据库主机的路径。它可从任何地方访问,因此一个监听在公网地址、前端没有防火墙且自身缺乏身份验证的 Web UI,对于任何发现它的人来说就是一个 Shell。dsh 会在启动时打印的 URL 中包含一个进程令牌,这虽然有帮助,但该 URL 本身现在就是凭据,因此请像对待密码一样谨慎分享它。
针对每种情况的修复方案都很枯燥,且每次都一样。为代理分配一个独立的非特权用户账户,而不是使用你的账户:
sudo adduser --disabled-password --gecos "" agent将 Web UI 保持在回环地址(loopback)上,并通过 SSH 访问。为代理提供仅能完成任务所需的最小权限凭据,如何让 AI 代理远离敏感密钥 一文对此有详细说明。对于任何在你无人值守时运行的任务,使用一次性机器优于精心配置的机器:在临时虚拟机中运行编程代理 和 在 VPS 上安全运行 Claude Code 均采用了这种方案。
您需要代理框架吗?
如果您的工作是一次处理一个问题,聊天窗口就足够了,而框架只会增加一个需要您监督的循环。当任务涉及针对真实文件的多个步骤,或者需要在您休息时持续运行时,框架的价值就会显现。
该类别中的大多数项目尚处于早期阶段。截至 2026 年 10 月,dsh 在其 README 中标注为开发者预览版,其余项目的发展速度也很快,您今天编写的配置文件下个月可能就需要修改。这正是保持设置精简且可复现的原因,也是记录您所做更改的原因。同样的克制在循环内部也很有帮助,一种推动代理进行最小可行性更改的技能 能让您在无人值守运行结束后,获得一个真正可读的差异对比。从一台服务器上的一个框架开始,给它分配一个任务和一个权限受限的密钥,只有在第一个任务连续一周运行平稳后,再扩大其访问权限。目前值得运行的自托管代理 是选择第一个框架的合理参考点。
FAQ
什么是 Agent Harness(智能体外壳)?
它是围绕模型运行的程序。模型负责生成文本并请求使用工具。Harness 负责维持循环,执行模型请求的工具,强制执行无需授权即可运行的工具规则,并保存会话状态和轮次间的文件。更换模型后 Harness 依然可以工作,这是两者相互独立的明确标志。
Claude Code 是模型还是 Harness?
Claude Code 是一个 Harness。它是一个带有循环、权限系统以及内置文件和 Shell 工具的终端程序。Claude 是它默认调用的模型系列。同样的区分也适用于 DeepSeek Harness (dsh),它是一个你安装的 Node 程序,而 DeepSeek 模型则是通过 API 提供服务的。你将 Harness 安装在机器上,通过网络调用模型。
Agent Harness 和 Agent Framework(智能体框架)有什么区别?
框架是你导入并基于其编写代码的库,因此你需要自行处理循环、重试和上下文管理。Harness 是你直接运行的程序,所有这些功能都已内置,你只需配置默认值,无需编写代码。在实际应用中,两者的界限比较模糊:截至 2026 年 10 月,LangChain 的 Deep Agents 是一个可导入的 SDK,但其自身仓库将其称为“内置功能完备的智能体外壳(batteries-included agent harness)”。判断标准在于你是否需要自己编写循环。这个问题的答案决定了哪个术语更适合你的情况。
运行 Agent Harness 需要 VPS 吗?
不需要。此处提到的每个 Harness 都能在笔记本电脑上运行。使用服务器会改变四点:合上盖子后智能体仍能运行;它将你的密钥保存在一台始终在线的机器上;它可以访问你的其他服务器;你可以从任何设备返回同一个会话。每一项都涉及安全考量,因此请为智能体分配单独的用户账户,并将任何 Web UI 绑定到 127.0.0.1。
我可以在同一个 Harness 中使用不同的模型吗?
通常可以,这也是 Harness 的定义属性。大多数 Harness 在其配置中接受模型名称和基础 URL,因此将其指向另一个提供商只需修改配置,无需重写代码。如果某个 Harness 不支持,可以在它与提供商之间部署一个本地路由器(如 Claude Code Router),由它负责转换请求,默认绑定到 127.0.0.1:3456。请谨慎使用此类代理,因为它能看到所有提示词并持有所有密钥。