最近开发圈里又掀起了一波讨论DeepSeek、Harness、Codex 这几个词总是被放在一起比较。有人刚在客户端里看到 DeepSeek Harness 的入口却不知道它到底是什么有人在配置 Codex CLI 时反复卡在unable to locate the codex cli binary还有人已经在尝试把 DeepSeek 的 API 接进自己常用的编码工具中。信息很杂很多帖子点到为止真正能落地操作的并不多。这篇教程我会把概念拆开讲清楚同时给出可以直接运行的最小 Harness 示例并梳理接入 Codex CLI、编辑器插件等场景的通用配置思路最后集中排查大家最容易踩的坑。不管你是刚接触 DeepSeek API还是已经准备把自己的开发工作流改造成 Agent 模式这篇文章都能提供一套可复制的实践经验。1. 背景与核心概念1.1 到底什么是 DeepSeek Harness理解这个词之前先解释一下 Harness 在 AI 工程里的含义。Harness 直译是“挽具”或“控制装置”在 AI Agent 领域通常指模型和真实工具之间的一层调度框架。它负责把用户的自然语言转换为模型可理解的提示再把模型的输出转换或不转换为函数调用、Shell 命令、文件操作等真实动作。一个典型的 AI 编码 Harness 会处理以下事情接收用户输入加上系统提示词和上下文。决定是否需要调用工具。接收工具返回的结果再次交给模型进行下一步判断。直到模型认为任务已经完成或达到循环上限。所以如果你问“DeepSeek Harness 是某个官方软件吗”目前还没有一个非常统一、可以被所有人直接下载安装的独立产品名。不同语境下它可能指某个开源项目把 DeepSeek 模型封装成带工具调用的代理层。某个桌面客户端中内置的 DeepSeek 工作流模块。开发者自己基于 DeepSeek API 写的一套自动化编码调度框架。真正有实际价值的方式不是纠结名字而是理解这套结构DeepSeek 提供模型推理能力Harness 负责工程化调度。两者组合后就能让大模型具备调用代码解释器、文件搜索、命令执行等能力。1.2 Harness 在 AI 编码工作流中的位置要理解 Harness可以把它和几个容易混淆的概念做一个区分。Codex CLI 类型的工具更像是面向终端用户的“成品”。它把模型、上下文管理、终端交互、权限确认都打包好了用户装完就能用。相当于一辆组装好的汽车。Harness 更像是汽车的“底盘和控制系统”。它不一定是给终端用户直接使用的而是给开发者二次封装用的。你可以理解为一个半成品框架开发者基于它定制自己的 Agent 流程。DeepSeek API 则是“发动机”。它本身不决定用户怎么操作只接收消息并返回 token。这三者的关系可以这样理解层次例子作用模型层DeepSeek Chat / Reasoner推理、代码生成、回复文本Harness 层开发者自建工具调度决定何时调用函数、如何组织多步任务终端产品层Codex CLI 等把整个流程变成用户可操作的命令行或客户端在社区讨论中有人把 DeepSeek Harness 理解为“用 DeepSeek API 替换掉商业编码产品内部模型层”的实践也有人理解为“全新的轻量代理框架”。无论哪种核心逻辑都不变多轮对话、工具注册、工具调用结果回填。1.3 为什么说它“不想做下一个 Codex”在 OpenAI Codex 生态中通常由官方定义的 CLI 或 Agent 来决定用户如何提问、如何调用工具、如何输出结果。用户的自由度是建立在厂商设定的工作流之上的。而“DeepSeek Harness”如果想走一条不同的路线它的意义很可能不是做一个和 Codex 一模一样的竞品而是强调更开放、更模块化模型可替换切换 DeepSeek 或其他兼容模型不需要改变整体框架。工具可扩展开发者可以自己注册脚本、API、数据库命令。流程可掌控每一步模型调用都暴露给开发者而不是封装在不可拆开的黑盒中。部署方式更灵活既能用云端 API也能退回到本地模型。所以与其问“DeepSeek Harness 能否在功能上超过 Codex”不如关注它是否解决了你当前工作流中的真实痛点快速接入 DeepSeek、自己控制工具权限、避免被某个官方客户端绑死。2. DeepSeek API 的接入方式如果要自己搭建一个 Harness需要清楚 DeepSeek API 能做什么、不能做什么。DeepSeek 的接口风格和 OpenAI 兼容所以大部分基于 OpenAI SDK 写的代码改一下base_url和api_key就能跑通。2.1 OpenAI 兼容 APIDeepSeek 提供了 OpenAI 兼容的 API 端点。这意味着你可以直接使用官方 openai Python SDK也可以使用 OpenAI 生态中的许多现成脚本。核心参数如下api_key: 在 DeepSeek 开放平台创建 base_url: https://api.deepseek.com model: deepseek-chat 或 deepseek-reasoner调用时SDK 会把请求发送到兼容路径。不同 SDK 版本对 base_url 的拼接规则有所差异有时需要在 base_url 末尾加/v1有时不加也能访问。遇到 404 时优先检查这一项。2.2 本地部署如果出于隐私或成本控制需求想把模型放在内网可以考虑使用 DeepSeek 开源模型做本地推理。本地部署的优势是数据不出内网劣势是对 GPU 显存和推理性能有较高要求。这时候的架构会变成你的 Harness 工具层 ↓ 本地推理服务 / 云端兼容 API ↓ DeepSeek 系列模型对 Harness 开发来说只要本地推理服务能提供 OpenAI 兼容接口上层逻辑基本不用改动。2.3 工具调用能力DeepSeek Chat 模型支持 Function Calling也就是让模型在回答过程中请求调用某个函数。这个能力是所有 Harness 的基石。例如用户问“当前系统时间是多少”模型可能不直接生成文字而是返回一个结构化的工具调用请求{ name: get_current_time, arguments: {} }Harness 收到这个请求后执行本地函数再把结果作为一条 tool 消息返回给模型模型最终生成可读的回答。这也解释了为什么很多人说“模型很重要但调度模型的方法更重要”。没有好的 Harness模型即使具备工具调用能力也无法在真实项目里安全执行命令、访问文件、操作数据库。3. 环境准备与最小设计3.1 环境版本说明本文示例需要使用 Python 3.10 或更高版本并安装 openai SDK。如果你已经有 Python 环境可以直接用 pip 安装pip install openai python-dotenv说明这里没有锁定精确版本号因为 openai SDK 更新频繁新版本兼容性更好。建议使用较新的稳定版不要使用 1.0 之前的旧版否则部分代码写法需要调整。还需要一个 DeepSeek API Key。创建方法是在 DeepSeek 开放平台中注册并创建一个 API Key然后将 Key 放到环境变量或本地配置文件中。不要写死在代码里尤其是不要提交到 Git 仓库。3.2 设计思路不要一上来就做大平台很多开发者一开始就想着做一个完整 IDE 插件或 Agent 平台结果代码量膨胀后难以维护。更务实的路径是先写一个几十行的最小 Harness固定系统提示词让模型知道自己是本地开发助手。注册两个工具一个获取当前时间一个获取系统基本信息。开启一个循环模型返回文本就结束返回工具调用就执行并回传结果。这样做的意义在于你可以快速理解模型与工具之间的交互协议并且能很方便地观察 token 消耗和响应结构。验证完最小闭环后再逐步扩展 Shell 执行、文件读写、代码搜索等能力。4. 实战用 Python 实现一个最小 DeepSeek Harness接下来我们直接动手。这个示例会包含项目目录结构。API Key 配置。工具定义。Agent 主循环。运行演示。4.1 创建项目结构先创建一个项目文件夹并建立如下结构deepseek-harness-demo/ ├── .env ├── .env.example ├── requirements.txt └── harness_demo.pyrequirements.txt 内容如下openai1.0.0 python-dotenv1.0.0然后安装依赖pip install -r requirements.txt4.2 配置环境变量在项目根目录复制.env.example为.env然后填入自己的 Key。.env.example内容DEEPSEEK_API_KEYsk-your-key-here DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat其中DEEPSEEK_API_KEYDeepSeek API Key。DEEPSEEK_BASE_URL默认是https://api.deepseek.com如果你本地走了代理服务可以改成代理地址。DEEPSEEK_MODEL默认用deepseek-chat。复杂推理任务可以换成deepseek-reasoner但工具调用表现需要根据实际场景测试。4.3 编写核心工具函数在harness_demo.py中定义两个简单工具。这里不执行危险命令只做信息获取便于理解流程。# 文件路径deepseek-harness-demo/harness_demo.py import json import os from datetime import datetime from dotenv import load_dotenv import platform from openai import OpenAI load_dotenv() client OpenAI( api_keyos.environ.get(DEEPSEEK_API_KEY, ), base_urlos.environ.get(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) MODEL os.environ.get(DEEPSEEK_MODEL, deepseek-chat) MAX_STEPS 5 def get_current_time() - str: 获取当前系统时间 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) def get_system_info() - str: 获取操作系统平台信息 return platform.platform()这两个函数足够简单但已经能演示“模型请求调用工具 - 本地函数执行 - 结果回传”的完整链路。4.4 注册工具并编写主循环工具函数定义好后需要给模型一个结构化的工具描述。这相当于告诉模型你可以调用哪些函数、每个函数接收什么参数。TOOL_MAP { get_current_time: get_current_time, get_system_info: get_system_info, } TOOL_SCHEMAS [ { type: function, function: { name: get_current_time, description: 获取当前系统时间返回格式为 YYYY-MM-DD HH:MM:SS, parameters: { type: object, properties: {}, }, }, }, { type: function, function: { name: get_system_info, description: 获取当前操作系统基础信息, parameters: { type: object, properties: {}, }, }, }, ]接下来是主循环。逻辑如下将用户输入追加到 messages。调用模型。如果模型返回普通 content直接当成最终回答。如果模型返回 tool_calls执行工具并回传结果。如果循环达到上限强制停止。SYSTEM_PROMPT 你是一个本地开发助手。 请优先使用工具回答问题。如果某个问题无法通过工具回答请明确说明。 不要伪造工具执行结果。 def run_harness(user_input: str): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(MAX_STEPS): response client.chat.completions.create( modelMODEL, messagesmessages, toolsTOOL_SCHEMAS, tool_choiceauto, ) message response.choices[0].message # 模型判断不需要调用工具直接输出答案 if not message.tool_calls: print(f[模型最终回答] {message.content}) return print(f[第 {step 1} 步] 模型请求调用 {len(message.tool_calls)} 个工具) # 把 assistant 消息及其 tool_calls 加入会话历史 assistant_msg { role: assistant, content: message.content, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], } messages.append(assistant_msg) # 逐个执行工具 for tc in message.tool_calls: tool_name tc.function.name try: args json.loads(tc.function.arguments or {}) except json.JSONDecodeError: args {} tool_fn TOOL_MAP.get(tool_name) if tool_fn is None: result f未知工具: {tool_name} else: try: result tool_fn(**args) except Exception as e: result f工具执行异常: {e} messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) if not isinstance(result, str) else result, }) print(f[达到最大步数 {MAX_STEPS}] 循环停止请检查是否有死循环) if __name__ __main__: user_text input(请输入你的问题) run_harness(user_text)4.5 运行并验证在终端运行python harness_demo.py输入问题现在几点了我的操作系统是什么如果流程正常你会看到类似下面的输出具体内容因系统环境而异[第 1 步] 模型请求调用 2 个工具 [模型最终回答] 根据工具返回结果 1. 当前时间是 2025-xx-xx xx:xx:xx 2. 你的操作系统是 macOS-xxx这个最小 Harness 虽然功能简单但它已具备 Agent 的核心骨架。后续想扩展到真实编码场景时只需要往TOOL_MAP和TOOL_SCHEMAS中增加工具即可。注意deepseek-reasoner在部分推理流程中可能会限制工具调用使用前先确认你的模型版本是否支持 Function Calling。传统来说deepseek-chat是最稳妥的模型选择。5. 把 DeepSeek 接入现有编码工具链自己手写一个最小 Harness 是为了理解原理。日常开发中更多人希望把 DeepSeek 接入已经成熟的工具中比如 Codex CLI、VSCode 插件、JetBrains 插件等。5.1 Codex CLI 接入 DeepSeek 的思路Codex 类工具的核心机制是让模型在终端里完成任务。如果你希望使用 DeepSeek 模型需要关注工具是否支持自定义 API Base URL 和模型名。很多基于 OpenAI 兼容协议开发的命令行工具都可以通过环境变量或配置文件覆盖默认服务地址。最常见的配置思路如下# 仅示意不同 Codex 类 CLI 的变量名可能不同 export DEEPSEEK_API_KEYsk-your-deepseek-api-key export OPENAI_API_KEY$DEEPSEEK_API_KEY export OPENAI_BASE_URLhttps://api.deepseek.com export OPENAI_MODELdeepseek-chat有些工具要求 base_url 指向/v1所以如果请求出现 404可以改成export OPENAI_BASE_URLhttps://api.deepseek.com/v1也有部分工具使用配置文件的模式。使用时优先查看你安装版本的 README 或 config schema确认字段叫做baseURL、apiKey还是其他名字。这类配置因为具体工具迭代较快没有统一的“标准答案”。5.2 编辑器插件接入场景VSCode 和 JetBrains 生态中有不少 AI 编码插件支持自定义 Provider。如果你看到一个插件支持“OpenAI Compatible”选项通常只需填写三项{ apiKey: sk-your-deepseek-api-key, baseUrl: https://api.deepseek.com, model: deepseek-chat }部分插件还有“工具调用模式”开关比如选择 Function Calling、JSON Mode 或 Prompt 模式。只要插件基于 Function CallingDeepSeek 通常能直接适配。如果插件内部强制使用 OpenAI 的某些非标准参数可能出现兼容性问题这类情况下优先看插件日志定位是哪一步报错。6. 常见问题与排查思路在接入 DeepSeek 和 Codex 类工具时有几个典型错误几乎每个人都会遇到。6.1 常见报错对照表问题现象常见原因解决思路收到 401 Authentication FailsAPI Key 错误、过期或没有余额检查 Key 是否以 sk- 开头登录开放平台确认余额和权限收到 404 Not Foundbase_url 拼接不对尝试在 base_url 末尾加/v1提示 model not found 或 Model Not Exist模型名填错确认使用 deepseek-chat 或 deepseek-reasoner请求超时或连接失败网络无法访问 api.deepseek.com或系统代理配置异常先 curl 测试目标地址再检查代理变量提示 Unable to locate the Codex CLI binary桌面端没有找到本地 Codex CLI 可执行文件确认 Codex CLI 已安装并在工具设置中指定 codex_cli_path本地代理转发报错例如 cc switch local proxy failed本地代理进程、证书或流量转发异常关闭代理重试检查 Provider URL 是否能直接访问查看应用日志6.2 Unable to locate the Codex CLI binary 的排查步骤这是使用某些桌面客户端连接 Codex 时的高频问题。报错信息通常长这样ChatGPT failed to start. Unable to locate the codex cli binary. Set codex_cli_path or ensure the executable is in your PATH.排查路径如下先确认 Codex CLI 是否真的安装了。在终端执行codex --version如果命令找不到说明 CLI 未安装或没有加入 PATH。如果已经安装找到 codex 可执行文件的绝对路径。macOS/Linux 下通常是/usr/local/bin/codex或/opt/homebrew/bin/codex。在桌面工具的配置文件中写上codex_cli_path指向该绝对路径。修改 PATH 后重启相关终端或桌面应用确保新的 PATH 生效。这类问题不是 DeepSeek 本身导致而是桌面应用与 CLI 之间的路径配置问题。6.3 本地代理转发失败有同学在切换代理或自定义 Provider 时会看到类似local proxy failed while handling codex endpoint /responses这类报错通常说明本地有一个转发进程负责把请求发到目标 API但转发进程崩溃了或者证书不对。处理顺序建议是先绕过本地代理直接使用 API 原始地址测试连接是否正常。查看应用日志确认请求最终访问的是哪个域名。如果使用系统代理关掉代理或调整代理规则再重启工具。安全提示涉及生产环境或内网请求时不要随意修改系统级代理或关闭安全策略先在小范围测试环境验证。7. 工程化建议与避坑指南把 Harness 从 Demo 推向项目级应用需要补充一些工程考虑。这些点决定了你的工具在团队里能不能稳定使用。7.1 API Key 管理要严格不要把 Key 写进代码更不要提交到 Git。团队协作时建议每个开发者使用自己的 Key方便审计调用量。服务端环境使用密钥管理服务例如 Vault、云厂商 KMS 等。项目里的.env文件必须加入.gitignore。# .gitignore .env !*.example7.2 工具调用要有最小权限Harness 越强大风险越高。允许模型执行 Shell 命令时不能直接无脑授予sudo权限。建议遵循最小权限原则代码操作只允许在指定的临时目录或项目沙箱目录内执行。数据库工具只开放只读账号禁止默认使用生产库账号。工具执行前增加人工确认步骤特别是删除、覆盖、推送等不可逆操作。对命令做黑名单过滤但不要只依赖黑名单目录隔离和独立容器更可靠。7.3 给循环设置上限Agent 在复杂任务中可能陷入反复调用工具的循环。如果不设上限token 消耗会快速上升甚至卡死整个任务。实际开发中建议加入两个限制max_steps限制整个任务最多调用多少次工具。max_tokens_per_step限制模型单次回复的最大 token 数。7.4 记录每次请求的消耗上线之后最好能打印或落盘记录每次请求的模型名称、token 消耗、调用工具、耗时。这样才能回答预算问题这个 Agent 一个月烧掉多少 token哪个工具调用频次最高后续优化才有依据。7.5 不要盲目复刻 Codex很多开发者看到 Codex 界面很炫酷就想在自己项目里复刻一套一样的。建议先思考哪些能力是核心哪些只是锦上添花。DeepSeek 生态更实用的路线是先用文本问答、代码生成这类无工具场景验证模型效果。再接入代码搜索、文件读取等低风险工具。确认需求稳定后才考虑打包成 CLI 或桌面端。换句话说工程从简到繁不要“为了像 Codex 而做 Harness”。8. 结语与下一步理解 DeepSeek Harness千万不要停留在名字上。它的本质是把 DeepSeek 的模型能力、Function Calling 协议、开发者的工具链三者拼接起来。你可以用现成的 Codex 类工具可以买别人的桌面端产品也可以像本文一样自己写几十行代码搭一个最小闭环。建议下一步从三件事开始动手跑通第 4 节的最小 Harness观察模型返回的 tool_calls 结构。尝试把自己常用的一个本地脚本注册成工具。在编辑器插件或 CLI 中画出 DeepSeek API 的兼容配置积累自己的接入配置清单。真正掌握 Harness不在于用了多少新概念而在于你能否说清楚“模型什么时候调工具、工具结果如何回填、什么时候停止”。先把最小链路跑起来再逐步做权限控制、成本监控和团队内推广这条路远比纠结某个产品定义更值得投入。
最近开发圈里又掀起了一波讨论DeepSeek、Harness、Codex 这几个词总是被放在一起比较。有人刚在客户端里看到 DeepSeek Harness 的入口却不知道它到底是什么有人在配置 Codex CLI 时反复卡在unable to locate the codex cli binary还有人已经在尝试把 DeepSeek 的 API 接进自己常用的编码工具中。信息很杂很多帖子点到为止真正能落地操作的并不多。这篇教程我会把概念拆开讲清楚同时给出可以直接运行的最小 Harness 示例并梳理接入 Codex CLI、编辑器插件等场景的通用配置思路最后集中排查大家最容易踩的坑。不管你是刚接触 DeepSeek API还是已经准备把自己的开发工作流改造成 Agent 模式这篇文章都能提供一套可复制的实践经验。1. 背景与核心概念1.1 到底什么是 DeepSeek Harness理解这个词之前先解释一下 Harness 在 AI 工程里的含义。Harness 直译是“挽具”或“控制装置”在 AI Agent 领域通常指模型和真实工具之间的一层调度框架。它负责把用户的自然语言转换为模型可理解的提示再把模型的输出转换或不转换为函数调用、Shell 命令、文件操作等真实动作。一个典型的 AI 编码 Harness 会处理以下事情接收用户输入加上系统提示词和上下文。决定是否需要调用工具。接收工具返回的结果再次交给模型进行下一步判断。直到模型认为任务已经完成或达到循环上限。所以如果你问“DeepSeek Harness 是某个官方软件吗”目前还没有一个非常统一、可以被所有人直接下载安装的独立产品名。不同语境下它可能指某个开源项目把 DeepSeek 模型封装成带工具调用的代理层。某个桌面客户端中内置的 DeepSeek 工作流模块。开发者自己基于 DeepSeek API 写的一套自动化编码调度框架。真正有实际价值的方式不是纠结名字而是理解这套结构DeepSeek 提供模型推理能力Harness 负责工程化调度。两者组合后就能让大模型具备调用代码解释器、文件搜索、命令执行等能力。1.2 Harness 在 AI 编码工作流中的位置要理解 Harness可以把它和几个容易混淆的概念做一个区分。Codex CLI 类型的工具更像是面向终端用户的“成品”。它把模型、上下文管理、终端交互、权限确认都打包好了用户装完就能用。相当于一辆组装好的汽车。Harness 更像是汽车的“底盘和控制系统”。它不一定是给终端用户直接使用的而是给开发者二次封装用的。你可以理解为一个半成品框架开发者基于它定制自己的 Agent 流程。DeepSeek API 则是“发动机”。它本身不决定用户怎么操作只接收消息并返回 token。这三者的关系可以这样理解层次例子作用模型层DeepSeek Chat / Reasoner推理、代码生成、回复文本Harness 层开发者自建工具调度决定何时调用函数、如何组织多步任务终端产品层Codex CLI 等把整个流程变成用户可操作的命令行或客户端在社区讨论中有人把 DeepSeek Harness 理解为“用 DeepSeek API 替换掉商业编码产品内部模型层”的实践也有人理解为“全新的轻量代理框架”。无论哪种核心逻辑都不变多轮对话、工具注册、工具调用结果回填。1.3 为什么说它“不想做下一个 Codex”在 OpenAI Codex 生态中通常由官方定义的 CLI 或 Agent 来决定用户如何提问、如何调用工具、如何输出结果。用户的自由度是建立在厂商设定的工作流之上的。而“DeepSeek Harness”如果想走一条不同的路线它的意义很可能不是做一个和 Codex 一模一样的竞品而是强调更开放、更模块化模型可替换切换 DeepSeek 或其他兼容模型不需要改变整体框架。工具可扩展开发者可以自己注册脚本、API、数据库命令。流程可掌控每一步模型调用都暴露给开发者而不是封装在不可拆开的黑盒中。部署方式更灵活既能用云端 API也能退回到本地模型。所以与其问“DeepSeek Harness 能否在功能上超过 Codex”不如关注它是否解决了你当前工作流中的真实痛点快速接入 DeepSeek、自己控制工具权限、避免被某个官方客户端绑死。2. DeepSeek API 的接入方式如果要自己搭建一个 Harness需要清楚 DeepSeek API 能做什么、不能做什么。DeepSeek 的接口风格和 OpenAI 兼容所以大部分基于 OpenAI SDK 写的代码改一下base_url和api_key就能跑通。2.1 OpenAI 兼容 APIDeepSeek 提供了 OpenAI 兼容的 API 端点。这意味着你可以直接使用官方 openai Python SDK也可以使用 OpenAI 生态中的许多现成脚本。核心参数如下api_key: 在 DeepSeek 开放平台创建 base_url: https://api.deepseek.com model: deepseek-chat 或 deepseek-reasoner调用时SDK 会把请求发送到兼容路径。不同 SDK 版本对 base_url 的拼接规则有所差异有时需要在 base_url 末尾加/v1有时不加也能访问。遇到 404 时优先检查这一项。2.2 本地部署如果出于隐私或成本控制需求想把模型放在内网可以考虑使用 DeepSeek 开源模型做本地推理。本地部署的优势是数据不出内网劣势是对 GPU 显存和推理性能有较高要求。这时候的架构会变成你的 Harness 工具层 ↓ 本地推理服务 / 云端兼容 API ↓ DeepSeek 系列模型对 Harness 开发来说只要本地推理服务能提供 OpenAI 兼容接口上层逻辑基本不用改动。2.3 工具调用能力DeepSeek Chat 模型支持 Function Calling也就是让模型在回答过程中请求调用某个函数。这个能力是所有 Harness 的基石。例如用户问“当前系统时间是多少”模型可能不直接生成文字而是返回一个结构化的工具调用请求{ name: get_current_time, arguments: {} }Harness 收到这个请求后执行本地函数再把结果作为一条 tool 消息返回给模型模型最终生成可读的回答。这也解释了为什么很多人说“模型很重要但调度模型的方法更重要”。没有好的 Harness模型即使具备工具调用能力也无法在真实项目里安全执行命令、访问文件、操作数据库。3. 环境准备与最小设计3.1 环境版本说明本文示例需要使用 Python 3.10 或更高版本并安装 openai SDK。如果你已经有 Python 环境可以直接用 pip 安装pip install openai python-dotenv说明这里没有锁定精确版本号因为 openai SDK 更新频繁新版本兼容性更好。建议使用较新的稳定版不要使用 1.0 之前的旧版否则部分代码写法需要调整。还需要一个 DeepSeek API Key。创建方法是在 DeepSeek 开放平台中注册并创建一个 API Key然后将 Key 放到环境变量或本地配置文件中。不要写死在代码里尤其是不要提交到 Git 仓库。3.2 设计思路不要一上来就做大平台很多开发者一开始就想着做一个完整 IDE 插件或 Agent 平台结果代码量膨胀后难以维护。更务实的路径是先写一个几十行的最小 Harness固定系统提示词让模型知道自己是本地开发助手。注册两个工具一个获取当前时间一个获取系统基本信息。开启一个循环模型返回文本就结束返回工具调用就执行并回传结果。这样做的意义在于你可以快速理解模型与工具之间的交互协议并且能很方便地观察 token 消耗和响应结构。验证完最小闭环后再逐步扩展 Shell 执行、文件读写、代码搜索等能力。4. 实战用 Python 实现一个最小 DeepSeek Harness接下来我们直接动手。这个示例会包含项目目录结构。API Key 配置。工具定义。Agent 主循环。运行演示。4.1 创建项目结构先创建一个项目文件夹并建立如下结构deepseek-harness-demo/ ├── .env ├── .env.example ├── requirements.txt └── harness_demo.pyrequirements.txt 内容如下openai1.0.0 python-dotenv1.0.0然后安装依赖pip install -r requirements.txt4.2 配置环境变量在项目根目录复制.env.example为.env然后填入自己的 Key。.env.example内容DEEPSEEK_API_KEYsk-your-key-here DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat其中DEEPSEEK_API_KEYDeepSeek API Key。DEEPSEEK_BASE_URL默认是https://api.deepseek.com如果你本地走了代理服务可以改成代理地址。DEEPSEEK_MODEL默认用deepseek-chat。复杂推理任务可以换成deepseek-reasoner但工具调用表现需要根据实际场景测试。4.3 编写核心工具函数在harness_demo.py中定义两个简单工具。这里不执行危险命令只做信息获取便于理解流程。# 文件路径deepseek-harness-demo/harness_demo.py import json import os from datetime import datetime from dotenv import load_dotenv import platform from openai import OpenAI load_dotenv() client OpenAI( api_keyos.environ.get(DEEPSEEK_API_KEY, ), base_urlos.environ.get(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) MODEL os.environ.get(DEEPSEEK_MODEL, deepseek-chat) MAX_STEPS 5 def get_current_time() - str: 获取当前系统时间 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) def get_system_info() - str: 获取操作系统平台信息 return platform.platform()这两个函数足够简单但已经能演示“模型请求调用工具 - 本地函数执行 - 结果回传”的完整链路。4.4 注册工具并编写主循环工具函数定义好后需要给模型一个结构化的工具描述。这相当于告诉模型你可以调用哪些函数、每个函数接收什么参数。TOOL_MAP { get_current_time: get_current_time, get_system_info: get_system_info, } TOOL_SCHEMAS [ { type: function, function: { name: get_current_time, description: 获取当前系统时间返回格式为 YYYY-MM-DD HH:MM:SS, parameters: { type: object, properties: {}, }, }, }, { type: function, function: { name: get_system_info, description: 获取当前操作系统基础信息, parameters: { type: object, properties: {}, }, }, }, ]接下来是主循环。逻辑如下将用户输入追加到 messages。调用模型。如果模型返回普通 content直接当成最终回答。如果模型返回 tool_calls执行工具并回传结果。如果循环达到上限强制停止。SYSTEM_PROMPT 你是一个本地开发助手。 请优先使用工具回答问题。如果某个问题无法通过工具回答请明确说明。 不要伪造工具执行结果。 def run_harness(user_input: str): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(MAX_STEPS): response client.chat.completions.create( modelMODEL, messagesmessages, toolsTOOL_SCHEMAS, tool_choiceauto, ) message response.choices[0].message # 模型判断不需要调用工具直接输出答案 if not message.tool_calls: print(f[模型最终回答] {message.content}) return print(f[第 {step 1} 步] 模型请求调用 {len(message.tool_calls)} 个工具) # 把 assistant 消息及其 tool_calls 加入会话历史 assistant_msg { role: assistant, content: message.content, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], } messages.append(assistant_msg) # 逐个执行工具 for tc in message.tool_calls: tool_name tc.function.name try: args json.loads(tc.function.arguments or {}) except json.JSONDecodeError: args {} tool_fn TOOL_MAP.get(tool_name) if tool_fn is None: result f未知工具: {tool_name} else: try: result tool_fn(**args) except Exception as e: result f工具执行异常: {e} messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) if not isinstance(result, str) else result, }) print(f[达到最大步数 {MAX_STEPS}] 循环停止请检查是否有死循环) if __name__ __main__: user_text input(请输入你的问题) run_harness(user_text)4.5 运行并验证在终端运行python harness_demo.py输入问题现在几点了我的操作系统是什么如果流程正常你会看到类似下面的输出具体内容因系统环境而异[第 1 步] 模型请求调用 2 个工具 [模型最终回答] 根据工具返回结果 1. 当前时间是 2025-xx-xx xx:xx:xx 2. 你的操作系统是 macOS-xxx这个最小 Harness 虽然功能简单但它已具备 Agent 的核心骨架。后续想扩展到真实编码场景时只需要往TOOL_MAP和TOOL_SCHEMAS中增加工具即可。注意deepseek-reasoner在部分推理流程中可能会限制工具调用使用前先确认你的模型版本是否支持 Function Calling。传统来说deepseek-chat是最稳妥的模型选择。5. 把 DeepSeek 接入现有编码工具链自己手写一个最小 Harness 是为了理解原理。日常开发中更多人希望把 DeepSeek 接入已经成熟的工具中比如 Codex CLI、VSCode 插件、JetBrains 插件等。5.1 Codex CLI 接入 DeepSeek 的思路Codex 类工具的核心机制是让模型在终端里完成任务。如果你希望使用 DeepSeek 模型需要关注工具是否支持自定义 API Base URL 和模型名。很多基于 OpenAI 兼容协议开发的命令行工具都可以通过环境变量或配置文件覆盖默认服务地址。最常见的配置思路如下# 仅示意不同 Codex 类 CLI 的变量名可能不同 export DEEPSEEK_API_KEYsk-your-deepseek-api-key export OPENAI_API_KEY$DEEPSEEK_API_KEY export OPENAI_BASE_URLhttps://api.deepseek.com export OPENAI_MODELdeepseek-chat有些工具要求 base_url 指向/v1所以如果请求出现 404可以改成export OPENAI_BASE_URLhttps://api.deepseek.com/v1也有部分工具使用配置文件的模式。使用时优先查看你安装版本的 README 或 config schema确认字段叫做baseURL、apiKey还是其他名字。这类配置因为具体工具迭代较快没有统一的“标准答案”。5.2 编辑器插件接入场景VSCode 和 JetBrains 生态中有不少 AI 编码插件支持自定义 Provider。如果你看到一个插件支持“OpenAI Compatible”选项通常只需填写三项{ apiKey: sk-your-deepseek-api-key, baseUrl: https://api.deepseek.com, model: deepseek-chat }部分插件还有“工具调用模式”开关比如选择 Function Calling、JSON Mode 或 Prompt 模式。只要插件基于 Function CallingDeepSeek 通常能直接适配。如果插件内部强制使用 OpenAI 的某些非标准参数可能出现兼容性问题这类情况下优先看插件日志定位是哪一步报错。6. 常见问题与排查思路在接入 DeepSeek 和 Codex 类工具时有几个典型错误几乎每个人都会遇到。6.1 常见报错对照表问题现象常见原因解决思路收到 401 Authentication FailsAPI Key 错误、过期或没有余额检查 Key 是否以 sk- 开头登录开放平台确认余额和权限收到 404 Not Foundbase_url 拼接不对尝试在 base_url 末尾加/v1提示 model not found 或 Model Not Exist模型名填错确认使用 deepseek-chat 或 deepseek-reasoner请求超时或连接失败网络无法访问 api.deepseek.com或系统代理配置异常先 curl 测试目标地址再检查代理变量提示 Unable to locate the Codex CLI binary桌面端没有找到本地 Codex CLI 可执行文件确认 Codex CLI 已安装并在工具设置中指定 codex_cli_path本地代理转发报错例如 cc switch local proxy failed本地代理进程、证书或流量转发异常关闭代理重试检查 Provider URL 是否能直接访问查看应用日志6.2 Unable to locate the Codex CLI binary 的排查步骤这是使用某些桌面客户端连接 Codex 时的高频问题。报错信息通常长这样ChatGPT failed to start. Unable to locate the codex cli binary. Set codex_cli_path or ensure the executable is in your PATH.排查路径如下先确认 Codex CLI 是否真的安装了。在终端执行codex --version如果命令找不到说明 CLI 未安装或没有加入 PATH。如果已经安装找到 codex 可执行文件的绝对路径。macOS/Linux 下通常是/usr/local/bin/codex或/opt/homebrew/bin/codex。在桌面工具的配置文件中写上codex_cli_path指向该绝对路径。修改 PATH 后重启相关终端或桌面应用确保新的 PATH 生效。这类问题不是 DeepSeek 本身导致而是桌面应用与 CLI 之间的路径配置问题。6.3 本地代理转发失败有同学在切换代理或自定义 Provider 时会看到类似local proxy failed while handling codex endpoint /responses这类报错通常说明本地有一个转发进程负责把请求发到目标 API但转发进程崩溃了或者证书不对。处理顺序建议是先绕过本地代理直接使用 API 原始地址测试连接是否正常。查看应用日志确认请求最终访问的是哪个域名。如果使用系统代理关掉代理或调整代理规则再重启工具。安全提示涉及生产环境或内网请求时不要随意修改系统级代理或关闭安全策略先在小范围测试环境验证。7. 工程化建议与避坑指南把 Harness 从 Demo 推向项目级应用需要补充一些工程考虑。这些点决定了你的工具在团队里能不能稳定使用。7.1 API Key 管理要严格不要把 Key 写进代码更不要提交到 Git。团队协作时建议每个开发者使用自己的 Key方便审计调用量。服务端环境使用密钥管理服务例如 Vault、云厂商 KMS 等。项目里的.env文件必须加入.gitignore。# .gitignore .env !*.example7.2 工具调用要有最小权限Harness 越强大风险越高。允许模型执行 Shell 命令时不能直接无脑授予sudo权限。建议遵循最小权限原则代码操作只允许在指定的临时目录或项目沙箱目录内执行。数据库工具只开放只读账号禁止默认使用生产库账号。工具执行前增加人工确认步骤特别是删除、覆盖、推送等不可逆操作。对命令做黑名单过滤但不要只依赖黑名单目录隔离和独立容器更可靠。7.3 给循环设置上限Agent 在复杂任务中可能陷入反复调用工具的循环。如果不设上限token 消耗会快速上升甚至卡死整个任务。实际开发中建议加入两个限制max_steps限制整个任务最多调用多少次工具。max_tokens_per_step限制模型单次回复的最大 token 数。7.4 记录每次请求的消耗上线之后最好能打印或落盘记录每次请求的模型名称、token 消耗、调用工具、耗时。这样才能回答预算问题这个 Agent 一个月烧掉多少 token哪个工具调用频次最高后续优化才有依据。7.5 不要盲目复刻 Codex很多开发者看到 Codex 界面很炫酷就想在自己项目里复刻一套一样的。建议先思考哪些能力是核心哪些只是锦上添花。DeepSeek 生态更实用的路线是先用文本问答、代码生成这类无工具场景验证模型效果。再接入代码搜索、文件读取等低风险工具。确认需求稳定后才考虑打包成 CLI 或桌面端。换句话说工程从简到繁不要“为了像 Codex 而做 Harness”。8. 结语与下一步理解 DeepSeek Harness千万不要停留在名字上。它的本质是把 DeepSeek 的模型能力、Function Calling 协议、开发者的工具链三者拼接起来。你可以用现成的 Codex 类工具可以买别人的桌面端产品也可以像本文一样自己写几十行代码搭一个最小闭环。建议下一步从三件事开始动手跑通第 4 节的最小 Harness观察模型返回的 tool_calls 结构。尝试把自己常用的一个本地脚本注册成工具。在编辑器插件或 CLI 中画出 DeepSeek API 的兼容配置积累自己的接入配置清单。真正掌握 Harness不在于用了多少新概念而在于你能否说清楚“模型什么时候调工具、工具结果如何回填、什么时候停止”。先把最小链路跑起来再逐步做权限控制、成本监控和团队内推广这条路远比纠结某个产品定义更值得投入。
