Skip to content

Integrate DeepSeek: Hands-on V4 Series Model Configuration ​

OpenClaw integration with DeepSeek is the first stop on the domestic models page, and also the most hassle-free one: an OpenAI-compatible API, one environment variable, and a single onboarding command. The three steps from the previous lesson—"install plugin → configure credentials → choose model"—we will walk through completely in this lesson, taking about 8 minutes in total (DeepSeek account registration not included).

First, here is a quick-reference table; all configuration in this lesson starts from it:

PropertyValue
Provider iddeepseek
Auth environment variableDEEPSEEK_API_KEY
API formOpenAI-compatible
Base URLhttps://api.deepseek.com
Official plugin@openclaw/deepseek-provider (external plugin, requires installation)
onboarding default modeldeepseek/deepseek-v4-pro

One piece of bad news you must know first: deepseek-chat and deepseek-reasoner were retired on 2026-07-24, and the old IDs are no longer accessible. Plenty of old tutorials online still use them—this lesson uses the active V4 series IDs throughout, with migration of old configurations covered in the pitfall reminders. This tutorial is based on v2026.10.9.

What You'll Be Able to Do ​

  • Install the DeepSeek official plugin @openclaw/deepseek-provider and configure DEEPSEEK_API_KEY into OpenClaw—choose any of three approaches: onboarding, config file, or non-interactive script
  • Distinguish the four active model IDs of the V4 series, and know when to switch away from the onboarding default deepseek-v4-pro
  • Migrate old configurations still using deepseek-chat / deepseek-reasoner to the new IDs
  • Control DeepSeek's reasoning intensity with /think; no need for /new when switching providers mid multi-turn tool call
  • Let the same plugin provide web_search to any model, without buying a separate search service

🎒 Preparation Before Starting ​

  • Completed Model Connection Overview: The provider System and Model Switching: have a clear grasp of the three steps "install plugin → configure credentials → choose model" and the provider/model reference rules
  • OpenClaw is installed and the Gateway is running: openclaw gateway status produces output (the plugin takes effect automatically on a running Gateway; if it's not running, it takes effect on next startup)
  • Can access the DeepSeek open platform: the next step is to register and create an API Key at platform.deepseek.com
  • If you deploy on a server / as a daemon, know where ~/.openclaw/.env is—the Key will ultimately live there

Follow Along ​

Step 1: Register with DeepSeek and Create an API Key ​

Why: DeepSeek's models are billed through the official API, and OpenClaw only handles the calls—you need to get the Key from the DeepSeek platform first.

  1. Open https://platform.deepseek.com in a browser and register / log in
  2. Go to the API Keys page: https://platform.deepseek.com/api_keys
  3. Create a new Key and copy it somewhere safe

What you should see: a copyable API Key, shaped like the sk-... in the official configuration example. This is the sole credential for OpenClaw to access the DeepSeek API, and the next step is all about configuring it.

💡 The Key is the sole credential on the DeepSeek side

Chat, image, and search all use the same Key (web_search goes through it too; see the advanced section). After creating it, don't rush to close the page—paste it somewhere safe first.

Step 2: OpenClaw Integrate DeepSeek——Install the Plugin First, Then Configure DEEPSEEK_API_KEY ​

Why: In OpenClaw, DeepSeek is an external official plugin (unlike MiniMax, which is built in), so there's one extra "install" step compared to built-in plugins; configure the credentials after installing.

First install the plugin (the shared first step for all three approaches):

bash
openclaw plugins install @openclaw/deepseek-provider

What you should see: Installation succeeded. It takes effect automatically on a running Gateway; if the Gateway isn't running, it takes effect on next startup.

Then configure the Key—pick one of three paths:

Option A (recommended): onboarding guide ​

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

Why it's recommended: one command completes "configure credentials + choose model"—it prompts you to paste the API Key, and after validation passes, automatically sets deepseek/deepseek-v4-pro as the default model.

What you should see: first a prompt for the API Key, then after the connection is validated the credentials are saved and the default model becomes deepseek/deepseek-v4-pro.

Two reassurances (explicitly stated in the official documentation):

  • onboarding preserves your existing model entries—re-running it won't wipe out other providers' configurations
  • Under models.mode: "replace" mode, it also writes to the built-in catalog (because that mode skips discovery)

Option B: Manually Edit the Config File ​

Like having everything under control? The official configuration example (as-is):

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

The two spots each handle one thing: env.vars.DEEPSEEK_API_KEY holds the Key, agents.defaults.model.primary holds the default model.

Option C: non-interactive script (server / automation) ​

For scripted installs, provide all parameters at once (as-is; $DEEPSEEK_API_KEY must already be set in the script environment):

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

⚠️ Running Gateway as a daemon? Don't put the Key in your interactive shell

When Gateway runs as a launchd / systemd service, it cannot see the environment variables from export in your terminal. Write DEEPSEEK_API_KEY into ~/.openclaw/.env, or provide it to that process via env.shellEnv in the configuration.

  • In the credentials overview of openclaw models status, the deepseek line shows the source of DEEPSEEK_API_KEY

Step 3: Choose a V4 series model and verify ​

Why: onboarding selected deepseek-v4-pro as the default, but the V4 series currently has four active IDs with different roles; take a look at the catalog, switch the default as needed, and finally send a message to verify the whole chain.

First, look at the active catalog:

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

You should see: four model references — this is DeepSeek's entire built-in catalog in OpenClaw:

Model referenceNameInputContextMax outputPositioning
deepseek/deepseek-flashDeepSeek V4.1 FlashText, images1,000,000384,000Mainstream Flash model
deepseek/deepseek-v4-flashDeepSeek V4 FlashText1,000,000384,000Fast V4, supports thinking
deepseek/deepseek-v4-proDeepSeek V4 ProText1,000,000384,000onboarding default
deepseek/deepseek-v4-flash-vision-expDeepSeek V4 Flash Vision (experimental)Text, images1,000,000384,000Experimental image understanding

How to choose, in three sentences:

Your needPick thisRationale
Don't know what to pick / heavy workloadsdeepseek/deepseek-v4-proIt's the onboarding default
Need to send images (PNG / JPEG / GIF / WebP)deepseek/deepseek-flashThe mainstream image model in the catalog; the legacy selection deepseek-v4-flash-vision-exp also retains image support
Need speeddeepseek/deepseek-v4-flashOfficially positioned as "Fast V4"

To change the default model (e.g., switch to Flash):

bash
openclaw models set deepseek/deepseek-flash

You can also switch temporarily in chat: /model deepseek/deepseek-v4-pro only affects the current session; see Chat Commands Crash Course for the full command family.

Final verification — send a test message:

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

(openclaw agent requires at least one session selector; --agent main points to the default agent — installations that completed onboarding have main by default; alternatively, run openclaw dashboard to open the Control UI and send directly from the chat box.)

You should see: the model replies normally, with no errors about missing credentials or nonexistent models. At this point, OpenClaw is fully connected to DeepSeek.

A quick note on pricing (so the bill doesn't surprise you):

  • The costs in the OpenClaw catalog are estimates: the deepseek/deepseek-flash row uses DeepSeek's peak prices — $0.30 per million input tokens, $1.20 for output, $0.006 for cached input; the officially announced off-peak prices are halved

  • deepseek-v4-flash and deepseek-v4-flash-vision-exp are still accepted by DeepSeek, but they route to V4.1 Flash and are billed at current Flash prices

  • No pricing documentation is given for deepseek-v4-pro; DeepSeek can change prices at any time — billing is governed by the official Models & Pricing page

  • The test message received a reply from DeepSeek

Checkpoint ✅ ​

  • openclaw plugins install @openclaw/deepseek-provider executed, plugin listed
  • The credentials overview of openclaw models status shows deepseek's DEEPSEEK_API_KEY
  • openclaw models list --provider deepseek lists the four active V4 series models
  • A reply from DeepSeek was received after sending the test message
  • No retired IDs like deepseek-chat / deepseek-reasoner in the configuration

Pitfall Reminders ​

❌ Still using deepseek-chat / deepseek-reasoner (retired) ​

Cause: DeepSeek retired these two model IDs on 2026-7-24 at 15:59 UTC; they are no longer accessible. These two names are all over old tutorials and old configurations — copying them verbatim will always produce errors.

text
# ❌ Retired, no longer accessible
deepseek/deepseek-chat
deepseek/deepseek-reasoner

# ✅ Officially designated migration targets (both support thinking)
deepseek/deepseek-v4-flash
deepseek/deepseek-v4-pro

The right fix: replace the old IDs in your configuration and sessions with one of the two new IDs above; if unsure, run openclaw models list --provider deepseek and copy from the active catalog.

❌ After installing Gateway as a daemon, the exported Key "doesn't take effect" ​

Cause: launchd / systemd services cannot see environment variables from your interactive shell — every provider's documentation specifically emphasizes this.

The right fix: write DEEPSEEK_API_KEY into ~/.openclaw/.env, or provide it via env.shellEnv in the configuration; restart the Gateway service after changing the Key.

❌ Wanted the model to see images, but picked v4-pro / v4-flash ​

Cause: in the catalog, deepseek-v4-pro and deepseek-v4-flash only accept text. For image input, use deepseek/deepseek-flash — it accepts PNG, JPEG, GIF, and WebP, over the same API and the same Key; the legacy deepseek-v4-flash-vision-exp selection also retains image support.

❌ Treating the prices in the OpenClaw directory as your bill ​

Reason: OpenClaw's local costs are estimates, and DeepSeek can change prices at any time; off-peak prices are half of peak, so billing fluctuations are normal.

The right approach: always treat DeepSeek's official Models & Pricing page as the source of truth for billing; to control costs, watch the peak / off-peak difference and the low price for cached input ($0.006 / million tokens).

🔧 DeepSeek-specific capabilities (optional) ​

Once the plugin is installed, three DeepSeek-specific capabilities come along automatically.

thinking control ​

Both the Flash and V4 series support DeepSeek's thinking control:

text
/think xhigh   # maps to DeepSeek's maximum reasoning_effort "max"
/think max     # also maps to "max"

When thinking is disabled (including the None option in the UI), OpenClaw sends thinking: { type: "disabled" } and strips reasoning_content from the outgoing history, keeping the session firmly on the non-thinking path.

Multi-turn tool calling has a DeepSeek-specific requirement—V4's thinking sessions require subsequent requests to replay reasoning_content—the plugin backfills this field automatically, so tool calls within a thinking session continue normally; switching over from another provider mid-session also doesn't require /new.

DSML tool recovery ​

DeepSeek models sometimes emit tool markers as plain text (DSML markers, including when forwarded via other OpenAI-compatible providers such as OpenRouter). OpenClaw restores the valid calls / tool_calls / tool_call / function_calls blocks among them into real tool calls, instead of leaving you staring at a blob of marker text in the chat.

Three boundaries:

  • Native tool calls take priority—when both appear in the same response, recovered duplicate calls are not executed
  • Malformed or incomplete blocks are only hidden, never executed
  • Recovered calls still go through the existing tool permission controls

web_search: one plugin, two uses ​

The same deepseek plugin can also provide web_search for any model—going directly through DeepSeek's search engine, not chat completion. Select DeepSeek in Settings → Search, or:

bash
openclaw configure --section web

Config file syntax (as-is; the Key can be omitted—credential priority: plugin search Key → environment variable DEEPSEEK_API_KEY → model provider Key):

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

Billing and limits: 5 requests per second per account; $0.75 / 1000 successful non-empty searches—empty results and failed requests are not billed. Search always calls https://api.deepseek.com/v1/tools/search; even if you configured a relay baseUrl for chat, search will not be routed through the proxy.

Next steps ​

OpenClaw DeepSeek configuration is now complete. The domestic-model pages have just gotten started:

Related tutorials ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.