OpenClaw DeepSeek Integration: Full Setup From API Key to Agent

The DeepSeek integration works on your first try or it fails on a config typo. There is no in-between. Most failed setups come down to three things: wrong base URL, wrong model identifier, or an API key that wasn't exported correctly. This guide closes all three gaps — step by step, with the exact values you need.

Before You Start

You need an OpenClaw installation running and a DeepSeek account. The integration works with OpenClaw v0.9 and above. If you're on an older version, check your OpenClaw version with openclaw --version before proceeding — older versions may not support the provider config format shown here.

DeepSeek's API is compatible with the OpenAI client libraries, which means OpenClaw's existing provider abstraction layer handles DeepSeek without any code changes. You're configuring, not coding.

Getting Your DeepSeek API Key

Go to platform.deepseek.com, create an account, and navigate to the API Keys section of your dashboard. Generate a new key and copy it immediately — DeepSeek only shows the full key once.

The key starts with sk- and is a 48-character string. Add it to your environment:

# Add to your shell profile or .env file
export DEEPSEEK_API_KEY="sk-your-deepseek-api-key-here"

# Verify it's set
echo $DEEPSEEK_API_KEY

If you're running OpenClaw via Docker or a process manager, add the environment variable to your service definition rather than your shell profile. The variable needs to be available to the OpenClaw process at runtime, not just in your terminal session.

Provider Configuration

Open your OpenClaw provider config file. Add a DeepSeek provider block:

providers:
  deepseek:
    type: openai_compatible
    base_url: https://api.deepseek.com/v1
    api_key: ${DEEPSEEK_API_KEY}
    default_model: deepseek-chat
    timeout: 120
    max_retries: 3
    retry_delay: 2

The type: openai_compatible field tells OpenClaw to use the OpenAI client format against this endpoint. The base_url is the critical field — this must point to DeepSeek's API, not OpenAI's. The api_key value uses an environment variable reference so the key is never stored in the config file itself.

Agent Configuration

With the provider configured, assign DeepSeek to an agent. Open the agent's config file and set the provider and model fields:

agent:
  name: research-agent
  provider: deepseek
  model: deepseek-chat        # DeepSeek-V3
  # model: deepseek-reasoner  # DeepSeek-R1 (reasoning tasks)
  temperature: 0.7
  max_tokens: 4096
  system_prompt: |
    You are a research assistant. Synthesize information clearly
    and cite your sources. Focus on accuracy over completeness.

tools:
  - web_search
  - read_file
  - write_file

The model identifiers are exact strings. deepseek-chat maps to DeepSeek-V3. deepseek-reasoner maps to DeepSeek-R1. Using a wrong identifier returns a 404 from the API — DeepSeek does not suggest the correct name in the error message, so double-check spelling before debugging further.

Testing the Connection

Once both config files are saved, test the connection directly:

# Test provider connectivity
openclaw provider test deepseek

# Send a test message to the agent
openclaw agent send research-agent "What is 2+2? Reply in one sentence."

# Watch the logs for the provider being used
openclaw logs --agent research-agent --level debug

A successful test shows the response from DeepSeek and, in debug mode, the full request payload with the model field confirming which model handled the request. Look for "model": "deepseek-chat" or "model": "deepseek-reasoner" in the response metadata.

Here's where most people stop. The test works, they move on, and then they hit an issue three days later because they didn't verify function calling. If your agent uses tools, send a message that triggers a tool call during testing — confirm the tool executes correctly before going to production.

Diagnosing Common Errors

• 401 Unauthorized — API key is wrong, missing, or not exported to the OpenClaw process environment. Verify with echo $DEEPSEEK_API_KEY in the same shell where OpenClaw runs.
• 404 Not Found — Wrong base URL (missing /v1) or wrong model identifier. Check both fields in your provider config.
• Connection timeout — DeepSeek API is rate-limiting you or experiencing latency. Increase the timeout value and add retry logic. DeepSeek's free tier has lower rate limits than paid tiers.
• Tool calls not executing — Verify your tool schemas use valid JSON Schema format. DeepSeek handles standard schemas correctly but may reject malformed schemas silently.
• Model fallback to default provider — If OpenClaw falls back to a different provider, the agent config's provider field may not match the provider name in your providers config. Both must say deepseek.

Frequently Asked Questions

Where do I get a DeepSeek API key?

Sign up at platform.deepseek.com, navigate to API Keys in your account dashboard, and generate a new key. DeepSeek offers a free tier with rate limits for testing. Paid credits are required for production workloads. The key starts with sk- and works exactly like an OpenAI API key in your OpenClaw config.

Which DeepSeek model name do I use in OpenClaw config?

Use deepseek-reasoner for DeepSeek-R1 and deepseek-chat for DeepSeek-V3. These are the exact model identifiers DeepSeek uses in their API. Check the DeepSeek platform docs for newly released models — the identifier format consistently follows this same naming pattern.

Can I switch between DeepSeek and OpenAI in the same OpenClaw setup?

Yes. Configure multiple providers in OpenClaw and assign different models to different agents. One agent can run DeepSeek-R1 for reasoning tasks while another uses GPT-4o for creative tasks. OpenClaw routes each agent to its configured provider independently without conflict or cross-contamination.

Why is my DeepSeek agent returning errors in OpenClaw?

The most common causes are an incorrect base URL (must be https://api.deepseek.com/v1), a wrong model identifier, or an invalid API key. Check your environment variables are exported correctly. DeepSeek returns 401 for auth errors and 404 for unrecognized model names — these two codes cover 90% of integration failures.

Does the DeepSeek integration work with OpenClaw tool calling?

Yes. DeepSeek-V3 and R1 both support the OpenAI tool-call format, which OpenClaw uses natively. Define your tools in the agent config exactly as you would for GPT-4. The response format for tool calls is identical, so no changes to your tool execution logic are needed in most cases.

How do I test that my DeepSeek integration is working correctly?

Send a simple message to your agent and check the OpenClaw logs for the provider being used and the model responding. Enable debug logging to see full request and response payloads. Verify the model field in the response matches your configured DeepSeek model — this confirms requests are routing correctly.