代码 Agent 正在成为开发者工具里变化最快的方向之一。DeepSeek 自研代码 Agent 上线的消息让不少团队开始重新评估是继续使用 Claude Code还是切换到基于 DeepSeek 模型的代码 Agent 工具链。新闻标题虽然有“对标”两个字但对大多数开发者来说真正有价值的问题是代码 Agent 是如何工作的DeepSeek 模型能在里面扮演什么角色以及怎么把这类工具接入自己的项目里。这篇内容不会重复发布会式的介绍而是把代码 Agent 当成一个可拆解的工程系统来看。先讲清楚 Agent 的循环机制、模型与客户端的边界然后给出两条可操作路线一条是直接用 DeepSeek API 跑通一个最小 Agent另一条是把 DeepSeek 模型接进 Claude Code 这类现成客户端。最后补充高频报错、排查链路和选型建议方便你在自己的环境里快速定位问题。1. 先理解代码 Agent 不是“聊天框加代码”而是一套循环执行系统1.1 用一句话说清楚 Agent 是什么代码 Agent 是一个能够自主调用工具的 AI 程序。你给它一个任务例如“修一下测试失败”“给这个函数补注释”“把这段逻辑重构为异步”它不会只输出一段代码让你自己粘贴而是会自己读取文件、执行命令、查看运行结果再根据结果继续修改直到任务完成或达到步数上限。这个“判断结果、再执行、再看结果”的过程和传统的“大模型生成一次回答”完全不同。普通聊天模型是一个单次预测过程输入问题输出答案结束。Agent 则是多轮工具调用过程每一步都相当于模型在决策“下一步该调用哪个工具”工具执行完的结果再回到模型上下文里模型基于新信息继续判断。1.2 代码 Agent 的四个核心组件一个代码 Agent 可以拆成四层来看。模型引擎大脑负责理解任务、生成代码、决定要不要调用工具。DeepSeek 这类模型在这里负责“想”和“写”。工具层手脚命令执行、文件读写、代码搜索、测试运行等能力。没有工具模型再强也只能输出文本。上下文管理层维护对话历史和工具输出的记录。上下文越长模型可参考的信息越多但也会带来成本上升、响应变慢和准确率下降。策略与约束层决定是否允许执行命令、如何卡超时、如何截断超长输出、如何重试失败的工具调用。在 Agent 领域负责把模型、工具和上下文串起来的这一层也经常被称为 harness也就是驱动外壳或执行框架。模型本身不会自己去打开终端harness 才是那个替模型完成实际动作的执行者。层级典型问题对应组件模型引擎这段代码怎么写下一步调用哪个工具LLM API、模型推理工具层命令在哪里执行文件怎么修改Shell、文件系统、代码索引上下文管理层历史太长如何处理工具输出太大怎么截断窗口滑动、摘要、输出截断策略与约束层命令能不能执行超时怎么办权限确认、超时、白名单1.3 DeepSeek 入局为什么值得关注DeepSeek 的能力重心一直在代码生成和数学推理这类强逻辑任务上公开 API 又采用 OpenAI 兼容协议这意味着很多现成 Agent 框架不需要大改就能接入。“对标 Claude Code”的本质是大家都在抢占同一个位置让开发者用一个命令行工具在终端里完成从理解需求、写代码到运行验证的完整过程。对开发者来说模型厂商是否推出自己的 Agent 客户端并不是最重要的重要的是模型能不能自由接入到自己的工具链里。模型服务是能力提供方Agent 客户端是执行载体。DeepSeek 可以自己做 Agent 客户端第三方也可以基于 DeepSeek 模型做 Agent。所以下面几条路线会同时覆盖直接用 DeepSeek API 自己写最小 Agent以及把 DeepSeek 模型接进 Claude Code 这类现成客户端。2. 动手前先把“模型”和“Agent 客户端”的关系对齐2.1 模型服务是大脑Agent 客户端是手脚实际项目里经常出现一个误区把 DeepSeek 模型和 Claude Code 放在同一句话里时默认它们是同一个层面的东西。其实它们是两个角色DeepSeek 提供模型推理能力通过 API 暴露。模型本身不会自己打开终端也不会自己保存文件。Claude Code、Codex 或者自研的 Agent 客户端负责把模型输出转成工具调用并管理整个执行流程。只要协议兼容同一套 Agent 客户端可以接不同的模型。这也是为什么社区里会出现“claude code 接入 deepseek”“codex 接入 deepseek”这类玩法。这样做的价值在于工具链可以保持稳定模型按需替换。项目在评估 DeepSeek 时不需要重新学一套终端工具只需要切换模型配置。2.2 学习环境与生产环境的要求差异学习环境的目标是尽快看到模型调用和 Agent 循环跑起来所以可以简化权限、不做监控、不处理并发。建议先准备一个 Python 3.9 以上的环境安装 openai 和 python-dotenv 两个依赖然后直接调用 API。生产环境的目标是稳定、可控、可审计关注点完全不同模型密钥放在密钥管理服务里而不是明文环境变量。Agent 的指令执行要有权限确认和命令白名单。工具调用和输出日志要有结构化记录方便回溯问题。接口超时、限流、重试要单独设计。模型版本变动时要能固定版本并支持回滚。2.3 环境准备清单项目建议值说明Python3.9 及以上运行 Agent 示例代码openai SDK1.x使用 chat.completions 接口和 tools 参数操作系统macOS / Linux / Windows WSL涉及 shell 命令执行Windows 原生环境建议用 PowerShell 或 WSL 验证API KeyDEEPSEEK_API_KEY从模型服务控制台创建不要提交到仓库网络能访问 API 服务公司内网环境先确认网关地址和鉴权方式动手前先做一轮快速检查python --version python -m pip install openai python-dotenv同时确认环境变量已经准备好export DEEPSEEK_API_KEYsk-你的密钥这里要注意第一个常见坑很多人把 API Key 直接写进代码然后连同源码一起提交到 Git 仓库。一旦仓库公开密钥就会被外部刷量产生费用甚至被封禁。正确做法是放在环境变量或 .env 文件里并且 .env 必须加入 .gitignore。3. 用 DeepSeek API 跑通一个最小代码 Agent3.1 创建项目并安装依赖先建立一个干净的实验目录用虚拟环境隔离依赖mkdir deepseek-agent-demo cd deepseek-agent-demo python3 -m venv .venv source .venv/bin/activate pip install openai python-dotenv在项目根目录创建 .env 文件DEEPSEEK_API_KEYsk-你的密钥 DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat模型名和基础接口地址在不同阶段可能调整落地前要以服务商当前文档为准。这里给出的是常见配置deepseek-chat 是公开接口里的常用模型名。3.2 最小 Agent 完整代码下面这个 Agent 只做四件事接收任务、把任务和对话历史发给模型、模型决定调用工具或直接回答、工具结果回填后继续下一轮。为了控制篇幅只实现 execute_shell 和 read_file 两个工具并加上 max_steps 上限防止死循环。import json import os import subprocess from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) TOOLS [ { type: function, function: { name: execute_shell, description: 在项目目录中执行 shell 命令返回标准输出和错误输出。适合运行测试、构建、查看文件列表等操作。, parameters: { type: object, properties: { command: { type: string, description: 要执行的完整命令例如 python -m pytest }, workdir: { type: string, description: 命令的工作目录可选默认是当前目录 } }, required: [command] } } }, { type: function, function: { name: read_file, description: 读取指定路径的文本文件返回文件内容。, parameters: { type: object, properties: { path: { type: string, description: 文件相对或绝对路径 } }, required: [path] } } } ] SYSTEM_PROMPT ( 你是一个运行在终端里的代码助手。你需要用工具完成用户的开发任务。 需要执行命令时调用 execute_shell需要查看文件内容时调用 read_file。 每次只做一步观察结果后再继续直到任务完成。 ) def run_tool(name: str, args: dict) - str: if name execute_shell: workdir args.get(workdir, os.getcwd()) result subprocess.run( args[command], shellTrue, cwdworkdir, capture_outputTrue, textTrue, timeout60, ) output result.stdout result.stderr return output[-4000:] if name read_file: with open(args[path], r, encodingutf-8) as f: content f.read() return content[-4000:] return 未知工具 def run_agent(task: str, max_steps: int 8): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: task}, ] for step in range(max_steps): print(f[step {step 1}] 调用模型) message client.chat.completions.create( modelos.getenv(DEEPSEEK_MODEL, deepseek-chat), messagesmessages, toolsTOOLS, tool_choiceauto, ).choices[0].message if not message.tool_calls: print([完成] 模型给出最终回答) print(message.content) return message.content messages.append( { role: assistant, content: message.content or , tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], } ) for tc in message.tool_calls: name tc.function.name args json.loads(tc.function.arguments) print(f[step {step 1}] 调用工具 {name}参数{args}) tool_output run_tool(name, args) messages.append( {role: tool, tool_call_id: tc.id, content: tool_output} ) raise RuntimeError(f达到最大步数 {max_steps}任务未完成注意检查是否出现死循环。) if __name__ __main__: run_agent(列出当前目录下的文件并读取其中任意一个 Python 文件的前 20 行告诉我它的用途。)这段代码有四个关键点tool_calls 是模型返回的结构化字段解析后要原样保存回 messages不能转成普通字符串否则模型会丢失工具调用信息。每个 tool 消息必须有 tool_call_id并且要和模型返回的 id 对应否则 API 会校验失败。工具输出用 [-4000:] 截断是为了防止一条超长日志把上下文塞满。execute_shell 里的 timeout60 保证命令不会无限挂起。3.3 运行与预期输出运行python agent.py预期会出现类似下面的过程[step 1] 调用模型 [step 1] 调用工具 execute_shell参数{command: ls -la} [step 2] 调用模型 [step 2] 调用工具 read_file参数{path: agent.py} [step 3] 调用模型 [完成] 模型给出最终回答 这个文件是一个最小代码 Agent 示例它通过 DeepSeek API 调用模型模型可以决策调用 shell 命令和读取文件...实际内容会因目录结构不同而不同。如果模型第一轮就直接回答而不是调用工具通常有两种原因系统提示词没有说清楚必须使用工具或者当前任务确实不需要工具。这里要注意第二个常见坑模型在多轮工具调用后有时会返回“重复内容”或“结论不完整”。常见原因有两个。一是工具输出被截断但截断后没有给模型任何“此处已截断”的提示模型误以为看到了全部内容。二是 assistant 消息里的 content 为 None 时被遗漏破坏了消息格式。处理方式是保留 content 字段空内容用空字符串占位并在截断时明确标注。3.4 关键参数说明参数作用常见值注意点temperature控制随机性0.1 到 0.3 适合代码太高会出现拼写错误和幻觉max_tokens单次生成上限视任务复杂度过小会导致代码被截断tools模型可调用的工具列表按需定义不要塞大量无用工具tool_choice是否强制调用工具auto 或 requirednone 表示禁用工具调用timeout请求超时60 到 120 秒推理模型可能较慢max_stepsAgent 总步数上限8 到 20防止死循环和费用失控还有一个容易被忽略的点如果使用 deepseek-reasoner 这类推理模型模型在生成最终回答前会先进行较长的推理单次请求耗时会明显高于普通 chat 模型。客户端的超时配置要相应调大否则会出现“请求还没返回客户端已经判定超时”的现象。4. 把 DeepSeek 模型接进现成 Agent 客户端Claude Code 与 Codex4.1 先理解这类客户端的接入原理Claude Code 这类终端 Agent 在设计上默认绑定特定模型服务只调用它内置的模型地址。但为了让企业用户和第三方模型接入客户端一般会开放自定义接口地址、自定义模型名、自定义鉴权头等配置项。它内部的工作方式可以理解为客户端自己负责上下文管理、工具执行、会话显示模型推理部分改由用户指定的接口提供。社区里“claude code 接入 deepseek”的做法本质就是通过环境变量把客户端默认的模型服务地址指向一个兼容的模型接入点再指定一个可用的 DeepSeek 模型名。这里要特别注意协议兼容不等于客户端完全认账。Claude Code 对模型名有校验逻辑对工具调用协议也有版本要求。如果模型返回的格式和客户端预期不一致就会出现模型不被识别或工具调用失败。4.2 常见配置方式下面是一份社区里常见的配置方式用于说明思路不代表每个版本都支持。落地前要确认你安装的客户端版本支持这些环境变量而且模型服务端确实提供了对应模型名。# 以 Claude Code 为例不同版本配置名可能不同 export ANTHROPIC_BASE_URLhttps://你的模型接入网关地址 export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat然后启动claude首次启动时客户端会走一遍登录和权限确认流程。如果配置正确在对话里输入一个真实编码任务客户端会通过工具循环执行。如果配置错误通常会直接报错或者在发送第一条消息后就失败。这里要解释一个很多人踩过的坑DeepSeek API 是 OpenAI 兼容协议而 Claude Code 原生使用的是 Anthropic 协议。直接把 OpenAI 协议的接口地址塞给 Claude Code往往会出现协议格式不兼容。如果客户端本身不支持协议转换就需要在中间加一个独立的协议转换层这个组件在生产环境里要单独维护不是简单改一个 URL 就能解决的。4.3 配置后如何验证验证顺序很重要不要一上来就跑复杂任务。建议按下面四步走先验证 API Key 能直接调用模型用 curl 发一个最小请求。再验证客户端配置启动后输入“你好”看是否正常返回。再验证工具循环给一个需要执行命令的任务例如“运行 pytest 并汇报失败的测试”。最后验证边界能力让 Agent 修改文件后再次读取确认变更。第一步的最小请求示例curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d {model:deepseek-chat,messages:[{role:user,content:返回 ok}],max_tokens:10}如果这一步返回正常 JSON说明密钥和模型名没有问题问题出在客户端接入配置。如果这一步就 401说明密钥无效换谁都接不上。4.4 模型名不被识别从报错倒推配置问题社区里经常看到这样 代码Agent与DeepSeek接入实战：原理、配置与排错
代码 Agent 正在成为开发者工具里变化最快的方向之一。DeepSeek 自研代码 Agent 上线的消息让不少团队开始重新评估是继续使用 Claude Code还是切换到基于 DeepSeek 模型的代码 Agent 工具链。新闻标题虽然有“对标”两个字但对大多数开发者来说真正有价值的问题是代码 Agent 是如何工作的DeepSeek 模型能在里面扮演什么角色以及怎么把这类工具接入自己的项目里。这篇内容不会重复发布会式的介绍而是把代码 Agent 当成一个可拆解的工程系统来看。先讲清楚 Agent 的循环机制、模型与客户端的边界然后给出两条可操作路线一条是直接用 DeepSeek API 跑通一个最小 Agent另一条是把 DeepSeek 模型接进 Claude Code 这类现成客户端。最后补充高频报错、排查链路和选型建议方便你在自己的环境里快速定位问题。1. 先理解代码 Agent 不是“聊天框加代码”而是一套循环执行系统1.1 用一句话说清楚 Agent 是什么代码 Agent 是一个能够自主调用工具的 AI 程序。你给它一个任务例如“修一下测试失败”“给这个函数补注释”“把这段逻辑重构为异步”它不会只输出一段代码让你自己粘贴而是会自己读取文件、执行命令、查看运行结果再根据结果继续修改直到任务完成或达到步数上限。这个“判断结果、再执行、再看结果”的过程和传统的“大模型生成一次回答”完全不同。普通聊天模型是一个单次预测过程输入问题输出答案结束。Agent 则是多轮工具调用过程每一步都相当于模型在决策“下一步该调用哪个工具”工具执行完的结果再回到模型上下文里模型基于新信息继续判断。1.2 代码 Agent 的四个核心组件一个代码 Agent 可以拆成四层来看。模型引擎大脑负责理解任务、生成代码、决定要不要调用工具。DeepSeek 这类模型在这里负责“想”和“写”。工具层手脚命令执行、文件读写、代码搜索、测试运行等能力。没有工具模型再强也只能输出文本。上下文管理层维护对话历史和工具输出的记录。上下文越长模型可参考的信息越多但也会带来成本上升、响应变慢和准确率下降。策略与约束层决定是否允许执行命令、如何卡超时、如何截断超长输出、如何重试失败的工具调用。在 Agent 领域负责把模型、工具和上下文串起来的这一层也经常被称为 harness也就是驱动外壳或执行框架。模型本身不会自己去打开终端harness 才是那个替模型完成实际动作的执行者。层级典型问题对应组件模型引擎这段代码怎么写下一步调用哪个工具LLM API、模型推理工具层命令在哪里执行文件怎么修改Shell、文件系统、代码索引上下文管理层历史太长如何处理工具输出太大怎么截断窗口滑动、摘要、输出截断策略与约束层命令能不能执行超时怎么办权限确认、超时、白名单1.3 DeepSeek 入局为什么值得关注DeepSeek 的能力重心一直在代码生成和数学推理这类强逻辑任务上公开 API 又采用 OpenAI 兼容协议这意味着很多现成 Agent 框架不需要大改就能接入。“对标 Claude Code”的本质是大家都在抢占同一个位置让开发者用一个命令行工具在终端里完成从理解需求、写代码到运行验证的完整过程。对开发者来说模型厂商是否推出自己的 Agent 客户端并不是最重要的重要的是模型能不能自由接入到自己的工具链里。模型服务是能力提供方Agent 客户端是执行载体。DeepSeek 可以自己做 Agent 客户端第三方也可以基于 DeepSeek 模型做 Agent。所以下面几条路线会同时覆盖直接用 DeepSeek API 自己写最小 Agent以及把 DeepSeek 模型接进 Claude Code 这类现成客户端。2. 动手前先把“模型”和“Agent 客户端”的关系对齐2.1 模型服务是大脑Agent 客户端是手脚实际项目里经常出现一个误区把 DeepSeek 模型和 Claude Code 放在同一句话里时默认它们是同一个层面的东西。其实它们是两个角色DeepSeek 提供模型推理能力通过 API 暴露。模型本身不会自己打开终端也不会自己保存文件。Claude Code、Codex 或者自研的 Agent 客户端负责把模型输出转成工具调用并管理整个执行流程。只要协议兼容同一套 Agent 客户端可以接不同的模型。这也是为什么社区里会出现“claude code 接入 deepseek”“codex 接入 deepseek”这类玩法。这样做的价值在于工具链可以保持稳定模型按需替换。项目在评估 DeepSeek 时不需要重新学一套终端工具只需要切换模型配置。2.2 学习环境与生产环境的要求差异学习环境的目标是尽快看到模型调用和 Agent 循环跑起来所以可以简化权限、不做监控、不处理并发。建议先准备一个 Python 3.9 以上的环境安装 openai 和 python-dotenv 两个依赖然后直接调用 API。生产环境的目标是稳定、可控、可审计关注点完全不同模型密钥放在密钥管理服务里而不是明文环境变量。Agent 的指令执行要有权限确认和命令白名单。工具调用和输出日志要有结构化记录方便回溯问题。接口超时、限流、重试要单独设计。模型版本变动时要能固定版本并支持回滚。2.3 环境准备清单项目建议值说明Python3.9 及以上运行 Agent 示例代码openai SDK1.x使用 chat.completions 接口和 tools 参数操作系统macOS / Linux / Windows WSL涉及 shell 命令执行Windows 原生环境建议用 PowerShell 或 WSL 验证API KeyDEEPSEEK_API_KEY从模型服务控制台创建不要提交到仓库网络能访问 API 服务公司内网环境先确认网关地址和鉴权方式动手前先做一轮快速检查python --version python -m pip install openai python-dotenv同时确认环境变量已经准备好export DEEPSEEK_API_KEYsk-你的密钥这里要注意第一个常见坑很多人把 API Key 直接写进代码然后连同源码一起提交到 Git 仓库。一旦仓库公开密钥就会被外部刷量产生费用甚至被封禁。正确做法是放在环境变量或 .env 文件里并且 .env 必须加入 .gitignore。3. 用 DeepSeek API 跑通一个最小代码 Agent3.1 创建项目并安装依赖先建立一个干净的实验目录用虚拟环境隔离依赖mkdir deepseek-agent-demo cd deepseek-agent-demo python3 -m venv .venv source .venv/bin/activate pip install openai python-dotenv在项目根目录创建 .env 文件DEEPSEEK_API_KEYsk-你的密钥 DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat模型名和基础接口地址在不同阶段可能调整落地前要以服务商当前文档为准。这里给出的是常见配置deepseek-chat 是公开接口里的常用模型名。3.2 最小 Agent 完整代码下面这个 Agent 只做四件事接收任务、把任务和对话历史发给模型、模型决定调用工具或直接回答、工具结果回填后继续下一轮。为了控制篇幅只实现 execute_shell 和 read_file 两个工具并加上 max_steps 上限防止死循环。import json import os import subprocess from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) TOOLS [ { type: function, function: { name: execute_shell, description: 在项目目录中执行 shell 命令返回标准输出和错误输出。适合运行测试、构建、查看文件列表等操作。, parameters: { type: object, properties: { command: { type: string, description: 要执行的完整命令例如 python -m pytest }, workdir: { type: string, description: 命令的工作目录可选默认是当前目录 } }, required: [command] } } }, { type: function, function: { name: read_file, description: 读取指定路径的文本文件返回文件内容。, parameters: { type: object, properties: { path: { type: string, description: 文件相对或绝对路径 } }, required: [path] } } } ] SYSTEM_PROMPT ( 你是一个运行在终端里的代码助手。你需要用工具完成用户的开发任务。 需要执行命令时调用 execute_shell需要查看文件内容时调用 read_file。 每次只做一步观察结果后再继续直到任务完成。 ) def run_tool(name: str, args: dict) - str: if name execute_shell: workdir args.get(workdir, os.getcwd()) result subprocess.run( args[command], shellTrue, cwdworkdir, capture_outputTrue, textTrue, timeout60, ) output result.stdout result.stderr return output[-4000:] if name read_file: with open(args[path], r, encodingutf-8) as f: content f.read() return content[-4000:] return 未知工具 def run_agent(task: str, max_steps: int 8): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: task}, ] for step in range(max_steps): print(f[step {step 1}] 调用模型) message client.chat.completions.create( modelos.getenv(DEEPSEEK_MODEL, deepseek-chat), messagesmessages, toolsTOOLS, tool_choiceauto, ).choices[0].message if not message.tool_calls: print([完成] 模型给出最终回答) print(message.content) return message.content messages.append( { role: assistant, content: message.content or , tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], } ) for tc in message.tool_calls: name tc.function.name args json.loads(tc.function.arguments) print(f[step {step 1}] 调用工具 {name}参数{args}) tool_output run_tool(name, args) messages.append( {role: tool, tool_call_id: tc.id, content: tool_output} ) raise RuntimeError(f达到最大步数 {max_steps}任务未完成注意检查是否出现死循环。) if __name__ __main__: run_agent(列出当前目录下的文件并读取其中任意一个 Python 文件的前 20 行告诉我它的用途。)这段代码有四个关键点tool_calls 是模型返回的结构化字段解析后要原样保存回 messages不能转成普通字符串否则模型会丢失工具调用信息。每个 tool 消息必须有 tool_call_id并且要和模型返回的 id 对应否则 API 会校验失败。工具输出用 [-4000:] 截断是为了防止一条超长日志把上下文塞满。execute_shell 里的 timeout60 保证命令不会无限挂起。3.3 运行与预期输出运行python agent.py预期会出现类似下面的过程[step 1] 调用模型 [step 1] 调用工具 execute_shell参数{command: ls -la} [step 2] 调用模型 [step 2] 调用工具 read_file参数{path: agent.py} [step 3] 调用模型 [完成] 模型给出最终回答 这个文件是一个最小代码 Agent 示例它通过 DeepSeek API 调用模型模型可以决策调用 shell 命令和读取文件...实际内容会因目录结构不同而不同。如果模型第一轮就直接回答而不是调用工具通常有两种原因系统提示词没有说清楚必须使用工具或者当前任务确实不需要工具。这里要注意第二个常见坑模型在多轮工具调用后有时会返回“重复内容”或“结论不完整”。常见原因有两个。一是工具输出被截断但截断后没有给模型任何“此处已截断”的提示模型误以为看到了全部内容。二是 assistant 消息里的 content 为 None 时被遗漏破坏了消息格式。处理方式是保留 content 字段空内容用空字符串占位并在截断时明确标注。3.4 关键参数说明参数作用常见值注意点temperature控制随机性0.1 到 0.3 适合代码太高会出现拼写错误和幻觉max_tokens单次生成上限视任务复杂度过小会导致代码被截断tools模型可调用的工具列表按需定义不要塞大量无用工具tool_choice是否强制调用工具auto 或 requirednone 表示禁用工具调用timeout请求超时60 到 120 秒推理模型可能较慢max_stepsAgent 总步数上限8 到 20防止死循环和费用失控还有一个容易被忽略的点如果使用 deepseek-reasoner 这类推理模型模型在生成最终回答前会先进行较长的推理单次请求耗时会明显高于普通 chat 模型。客户端的超时配置要相应调大否则会出现“请求还没返回客户端已经判定超时”的现象。4. 把 DeepSeek 模型接进现成 Agent 客户端Claude Code 与 Codex4.1 先理解这类客户端的接入原理Claude Code 这类终端 Agent 在设计上默认绑定特定模型服务只调用它内置的模型地址。但为了让企业用户和第三方模型接入客户端一般会开放自定义接口地址、自定义模型名、自定义鉴权头等配置项。它内部的工作方式可以理解为客户端自己负责上下文管理、工具执行、会话显示模型推理部分改由用户指定的接口提供。社区里“claude code 接入 deepseek”的做法本质就是通过环境变量把客户端默认的模型服务地址指向一个兼容的模型接入点再指定一个可用的 DeepSeek 模型名。这里要特别注意协议兼容不等于客户端完全认账。Claude Code 对模型名有校验逻辑对工具调用协议也有版本要求。如果模型返回的格式和客户端预期不一致就会出现模型不被识别或工具调用失败。4.2 常见配置方式下面是一份社区里常见的配置方式用于说明思路不代表每个版本都支持。落地前要确认你安装的客户端版本支持这些环境变量而且模型服务端确实提供了对应模型名。# 以 Claude Code 为例不同版本配置名可能不同 export ANTHROPIC_BASE_URLhttps://你的模型接入网关地址 export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat然后启动claude首次启动时客户端会走一遍登录和权限确认流程。如果配置正确在对话里输入一个真实编码任务客户端会通过工具循环执行。如果配置错误通常会直接报错或者在发送第一条消息后就失败。这里要解释一个很多人踩过的坑DeepSeek API 是 OpenAI 兼容协议而 Claude Code 原生使用的是 Anthropic 协议。直接把 OpenAI 协议的接口地址塞给 Claude Code往往会出现协议格式不兼容。如果客户端本身不支持协议转换就需要在中间加一个独立的协议转换层这个组件在生产环境里要单独维护不是简单改一个 URL 就能解决的。4.3 配置后如何验证验证顺序很重要不要一上来就跑复杂任务。建议按下面四步走先验证 API Key 能直接调用模型用 curl 发一个最小请求。再验证客户端配置启动后输入“你好”看是否正常返回。再验证工具循环给一个需要执行命令的任务例如“运行 pytest 并汇报失败的测试”。最后验证边界能力让 Agent 修改文件后再次读取确认变更。第一步的最小请求示例curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d {model:deepseek-chat,messages:[{role:user,content:返回 ok}],max_tokens:10}如果这一步返回正常 JSON说明密钥和模型名没有问题问题出在客户端接入配置。如果这一步就 401说明密钥无效换谁都接不上。4.4 模型名不被识别从报错倒推配置问题社区里经常看到这样