接入 DeepSeek：V4 系列模型配置实战

OpenClaw 接入 DeepSeek 是国产模型专页的第一站，也是最省心的一家：OpenAI 兼容 API、一个环境变量、一条 onboarding 命令。上一课的「装插件 → 配凭据 → 选模型」三步，这一课完整走一遍，全程约 8 分钟（DeepSeek 账号注册另计）。

先给你一张速览表，本课所有配置都从它出发：

属性	值
Provider id	`deepseek`
认证环境变量	`DEEPSEEK_API_KEY`
API 形态	OpenAI 兼容
Base URL	`https://api.deepseek.com`
官方插件	`@openclaw/deepseek-provider`（外部插件，需安装）
onboarding 默认模型	`deepseek/deepseek-v4-pro`

一个必须先知道的坏消息：deepseek-chat 和 deepseek-reasoner 已于 2026-07-24 退役，旧 ID 不再可访问。网上大量旧教程还在用它们——本课全程使用现役的 V4 系列 ID，旧配置的迁移放在踩坑提醒里。本教程基于 v2026.10.9。

学完你能做什么

装上 DeepSeek 官方插件 @openclaw/deepseek-provider，把 DEEPSEEK_API_KEY 配进 OpenClaw——onboarding、配置文件、非交互脚本三种写法任选
分清 V4 系列四个现役模型 ID，知道 onboarding 默认的 deepseek-v4-pro 什么时候该换
把还在用 deepseek-chat / deepseek-reasoner 的旧配置迁移到新 ID
用 /think 控制 DeepSeek 的推理强度；多轮工具调用中途切 provider 不用 /new
让同一个插件给任意模型提供 web_search，不用另买搜索服务

🎒 开始前的准备

完成了连接模型总览：provider 体系与模型切换：「装插件 → 配凭据 → 选模型」三步和 provider/model 引用规则心里有数
OpenClaw 已安装、Gateway 在运行：openclaw gateway status 有输出（插件对运行中的 Gateway 自动生效；没在跑则下次启动生效）
能访问 DeepSeek 开放平台：下一步要去 platform.deepseek.com 注册并创建 API Key
走服务器 / 守护进程部署的话，知道 ~/.openclaw/.env 在哪——Key 最终要住那里

跟我做

第 1 步：注册 DeepSeek 并创建 API Key

为什么：DeepSeek 的模型走官方 API 计费，OpenClaw 只负责调用——Key 得先从 DeepSeek 平台拿。

浏览器打开 https://platform.deepseek.com，注册 / 登录
进入 API Keys 页面：https://platform.deepseek.com/api_keys
创建一把新 Key，复制保存

你应该看到：一把可复制的 API Key，形如官方配置示例里的 sk-...。它就是 OpenClaw 访问 DeepSeek API 的唯一凭据，下一步全在配它。

💡 Key 就是 DeepSeek 侧的唯一凭据

聊天、图像、搜索都用同一把 Key（web_search 也走它，见进阶一节）。创建完别急着关页面，先粘到安全的地方。

第 2 步：OpenClaw 接入 DeepSeek——先装插件，再配 DEEPSEEK_API_KEY

为什么：DeepSeek 在 OpenClaw 里是外部官方插件（不像 MiniMax 那样内置），所以比内置插件多一步「安装」；装完再配凭据。

先装插件（三种方式共用的第一步）：

bash

openclaw plugins install @openclaw/deepseek-provider

你应该看到：安装成功。对运行中的 Gateway 自动生效；Gateway 没在跑则下次启动时生效。

然后配 Key，三条路选一条：

方式 A（推荐）：onboarding 引导

bash

openclaw onboard --auth-choice deepseek-api-key

为什么推荐：一条命令走完「配凭据 + 选模型」——提示你粘贴 API Key，验证通过后自动把 deepseek/deepseek-v4-pro 设为默认模型。

你应该看到：先提示输入 API Key，验证连接通过后保存凭据，默认模型变为 deepseek/deepseek-v4-pro。

两个定心丸（官方文档明确写了）：

onboarding 保留你已有的模型条目——重跑不会清掉其他 provider 的配置
models.mode: "replace" 模式下会同时写入内置目录（因为该模式跳过 discovery）

方式 B：手动改配置文件

喜欢一切尽在掌握？官方配置示例（原样）：

json5

{
  env: { vars: { DEEPSEEK_API_KEY: "sk-..." } },
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v4-pro" },
    },
  },
}

两处各管一件事：env.vars.DEEPSEEK_API_KEY 放 Key，agents.defaults.model.primary 放默认模型。

方式 C：非交互脚本（服务器 / 自动化）

脚本化安装时把所有参数一次给全（原样，$DEEPSEEK_API_KEY 需在脚本环境里已设置）：

bash

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice deepseek-api-key \
  --deepseek-api-key "$DEEPSEEK_API_KEY" \
  --skip-health \
  --accept-risk

⚠️ Gateway 跑成守护进程？Key 别放交互 shell

Gateway 作为 launchd / systemd 服务运行时，看不到你终端里 export 的环境变量。把 DEEPSEEK_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供给那个进程。

openclaw models status 的凭据概览里，deepseek 一行能看到 DEEPSEEK_API_KEY 的来源

第 3 步：选择 V4 系列模型并验证

为什么：onboarding 默认选了 deepseek-v4-pro，但 V4 系列现役有四个 ID、分工不同；看一眼目录、按需换默认，最后发条消息验证全链路。

先看现役目录：

bash

openclaw models list --provider deepseek        # Gateway 在运行时
openclaw models list --all --provider deepseek  # 不启动 Gateway 也能看静态目录

你应该看到：四个模型引用——这就是 DeepSeek 在 OpenClaw 里的全部内置目录：

模型引用	名称	输入	上下文	最大输出	定位
`deepseek/deepseek-flash`	DeepSeek V4.1 Flash	文本、图像	1,000,000	384,000	主力 Flash 模型
`deepseek/deepseek-v4-flash`	DeepSeek V4 Flash	文本	1,000,000	384,000	快速 V4，支持 thinking
`deepseek/deepseek-v4-pro`	DeepSeek V4 Pro	文本	1,000,000	384,000	onboarding 默认
`deepseek/deepseek-v4-flash-vision-exp`	DeepSeek V4 Flash Vision（实验）	文本、图像	1,000,000	384,000	实验性图像理解

怎么选，三句话：

你的需求	选它	依据
不知道选啥 / 重活	`deepseek/deepseek-v4-pro`	onboarding 默认就是它
要发图（PNG / JPEG / GIF / WebP）	`deepseek/deepseek-flash`	目录里的主力图像模型；旧选区 `deepseek-v4-flash-vision-exp` 也保留图像支持
要快	`deepseek/deepseek-v4-flash`	官方定位「Fast V4」

换默认模型（比如换到 Flash）：

bash

openclaw models set deepseek/deepseek-flash

聊天里临时切也行：/model deepseek/deepseek-v4-pro 只影响当前会话，命令族详见聊天命令速成。

最后验证——发一句测试消息：

bash

openclaw agent --agent main --model deepseek/deepseek-v4-pro --message "用一句话介绍你自己"

（openclaw agent 要求至少给一个会话选择器，--agent main 指向默认 agent——完成过 onboarding 的安装里默认就有 main；或者 openclaw dashboard 打开 Control UI，在聊天框直接发。）

你应该看到：模型正常回复，没有凭据缺失或模型不存在的报错。到这里，OpenClaw 接入 DeepSeek 就通了。

价格顺手说清（免得账单吓一跳）：

OpenClaw 目录里的成本是估算：deepseek/deepseek-flash 行按 DeepSeek 峰值价——每百万输入 token $0.30、输出 $1.20、缓存输入 $0.006；官方公布的错峰价减半
deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 仍被 DeepSeek 接受，但会路由到 V4.1 Flash、按现行 Flash 价计费
deepseek-v4-pro 的价格文档未给；DeepSeek 可随时调价——计费以官方 Models & Pricing 页为准
测试消息收到了来自 DeepSeek 的回复

检查点 ✅

openclaw plugins install @openclaw/deepseek-provider 已执行，插件在列
openclaw models status 的凭据概览里能看到 deepseek 的 DEEPSEEK_API_KEY
openclaw models list --provider deepseek 列出 V4 系列四个现役模型
测试消息发出后收到了 DeepSeek 的回复
配置里没有 deepseek-chat / deepseek-reasoner 这类退役 ID

踩坑提醒

❌ 还在用 deepseek-chat / deepseek-reasoner（已退役）

原因：DeepSeek 已于 2026 年 7 月 24 日 15:59 UTC 退役这两个模型 ID，它们不再可访问。旧教程、旧配置里到处是这两个名字，照抄必报错。

text

# ❌ 已退役，不再可访问
deepseek/deepseek-chat
deepseek/deepseek-reasoner

# ✅ 官方指名的迁移目标（两个都支持 thinking）
deepseek/deepseek-v4-flash
deepseek/deepseek-v4-pro

正确做法：把配置和会话里的旧 ID 换成上面两个新 ID 之一；拿不准就 openclaw models list --provider deepseek，照现役目录抄。

❌ Gateway 装成守护进程后，export 的 Key「不生效」

原因：launchd / systemd 服务看不到你交互 shell 里的环境变量——各 provider 文档都专门强调这一点。

正确做法：DEEPSEEK_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供；换 Key 后重启 Gateway 服务。

❌ 想让模型看图，选了 v4-pro / v4-flash

原因：目录里 deepseek-v4-pro 和 deepseek-v4-flash 只收文本。图像输入要用 deepseek/deepseek-flash——它收 PNG、JPEG、GIF、WebP，走同一个 API 和同一把 Key；旧的 deepseek-v4-flash-vision-exp 选区也保留图像支持。

❌ 把 OpenClaw 目录里的价格当账单

原因：OpenClaw 的本地成本是估算值，DeepSeek 可随时调价；错峰价是峰值的一半，账单波动很正常。

正确做法：计费一律以 DeepSeek 官方 Models & Pricing 页为准；想控成本，关注峰值 / 错峰差异，以及缓存输入的低价（$0.006 / 百万 token）。

🔧 DeepSeek 专属能力（可选）

插件装好之后，三件 DeepSeek 专属的能力自动跟着来。

thinking 控制

Flash 和 V4 系列都支持 DeepSeek 的 thinking 控制：

text

/think xhigh   # 映射到 DeepSeek 最大 reasoning_effort "max"
/think max     # 同样映射到 "max"

关闭 thinking（包括 UI 里的 None 档）时，OpenClaw 会发送 thinking: { type: "disabled" }，并从发出去的历史里剥掉 reasoning_content，让会话稳在非 thinking 路径。

多轮工具调用有个 DeepSeek 特有的要求——V4 的 thinking 会话要求后续请求回放 reasoning_content——插件会自动回填这个字段，所以 thinking 会话里的工具调用能正常续；中途从别的 provider 切过来也不用 /new。

DSML 工具恢复

DeepSeek 模型有时把工具标记当文本吐出来（DSML 标记，包括经 OpenRouter 等其他 OpenAI 兼容 provider 转发时）。OpenClaw 会把其中有效的 calls / tool_calls / tool_call / function_calls 块恢复成真实工具调用，而不是让你在聊天里看一坨标记文本。

三条边界：

原生工具调用优先——同一响应里两者都有时，恢复出来的重复调用不会执行
畸形、未写完的块只隐藏、不执行
恢复出的调用照样过既有的工具权限管控

web_search：一个插件两用

同一个 deepseek 插件还能给任意模型提供 web_search——直接走 DeepSeek 的搜索引擎，不是聊天补全。在 Settings → Search 选 DeepSeek，或：

bash

openclaw configure --section web

配置文件写法（原样；Key 可省略——凭据优先级：插件搜索 Key → 环境变量 DEEPSEEK_API_KEY → 模型 provider Key）：

json5

{
  tools: {
    web: {
      search: { provider: "deepseek" },
    },
  },
  plugins: {
    entries: {
      deepseek: {
        config: {
          webSearch: {
            apiKey: "YOUR_DEEPSEEK_API_KEY",
          },
        },
      },
    },
  },
}

计费与限额：每账户 5 次请求 / 秒；$0.75 / 1000 次成功非空搜索——空结果和失败请求不计费。搜索固定调 https://api.deepseek.com/v1/tools/search，就算你给聊天配了中转 baseUrl，搜索也不会被导去代理。

下一步

OpenClaw DeepSeek 配置到此通关。国产模型专页才刚开张：

下一课接入通义千问 Qwen：DashScope 三种套餐：DashScope 的 Coding / Standard / Token Plan 三套端点怎么选，QWEN_API_KEY 怎么配
其他模型专页（GLM、Kimi、MiniMax、豆包、混元 / 千帆）从连接模型总览的课程表进
模型配好了？日常使用从日常使用：和你的 Claw 高效相处开始——Control UI、聊天命令、记忆系统都在那一章

接入 DeepSeek：V4 系列模型配置实战 ​

学完你能做什么 ​

🎒 开始前的准备 ​

跟我做 ​

第 1 步：注册 DeepSeek 并创建 API Key ​

第 2 步：OpenClaw 接入 DeepSeek——先装插件，再配 DEEPSEEK_API_KEY ​

方式 A（推荐）：onboarding 引导 ​

方式 B：手动改配置文件 ​

方式 C：非交互脚本（服务器 / 自动化） ​

第 3 步：选择 V4 系列模型并验证 ​

检查点 ✅ ​

踩坑提醒 ​

❌ 还在用 deepseek-chat / deepseek-reasoner（已退役） ​

❌ Gateway 装成守护进程后，export 的 Key「不生效」 ​

❌ 想让模型看图，选了 v4-pro / v4-flash ​

❌ 把 OpenClaw 目录里的价格当账单 ​

🔧 DeepSeek 专属能力（可选） ​

thinking 控制 ​

DSML 工具恢复 ​

web_search：一个插件两用 ​

下一步 ​

相关教程 ​

接入 DeepSeek：V4 系列模型配置实战

学完你能做什么

🎒 开始前的准备

跟我做

第 1 步：注册 DeepSeek 并创建 API Key

第 2 步：OpenClaw 接入 DeepSeek——先装插件，再配 DEEPSEEK_API_KEY

方式 A（推荐）：onboarding 引导

方式 B：手动改配置文件

方式 C：非交互脚本（服务器 / 自动化）

第 3 步：选择 V4 系列模型并验证

检查点 ✅

踩坑提醒

❌ 还在用 deepseek-chat / deepseek-reasoner（已退役）

❌ Gateway 装成守护进程后，export 的 Key「不生效」

❌ 想让模型看图，选了 v4-pro / v4-flash

❌ 把 OpenClaw 目录里的价格当账单

🔧 DeepSeek 专属能力（可选）

thinking 控制

DSML 工具恢复

web_search：一个插件两用

下一步

相关教程