Comprehensive Guide to Integrating DeepSeek API with OpenClaw

Preface

I searched all over the web but could not find a guide on how to configure the official DeepSeek API key in OpenClaw, so I created one myself. The content below was summarized and generated by Claude Code based on my chat history. I hope it helps anyone who wants to use the official DeepSeek API key in OpenClaw.

System Requirements

• Operating System: macOS / Linux / Windows (WSL)
• Node.js: Version 22+ (using nvm is recommended)
• Network: Access to the DeepSeek API is required (api.deepseek.com)

Install OpenClaw

1. Install OpenClaw Globally

npm install -g openclaw@latest

The installation process may take 3-5 minutes and will download about 674 dependency packages.

2. Verify the Installation

openclaw --version

It should display something like:🦞 OpenClaw 2026.2.9

Initial Setup

1. Run the Setup Wizard

openclaw onboard --install-daemon --non-interactive --accept-risk

Explanation:

--install-daemon: Install the background service

--non-interactive: Non-interactive mode

--accept-risk: Accept the security risk notice

2. Check Service Status

openclaw status

Make sure the Gateway service is running.

Configure the Official DeepSeek API

1. Get a DeepSeek API Key

Visit DeepSeek Official Website to register and obtain an API key.

1. The API key format looks like:sk-test

2. Configure the DeepSeek Provider

Run the following command (replace YOUR_API_KEY with your actual API key):

openclaw config set models.providers.deepseek '{
  "baseUrl": "https://api.deepseek.com/v1",
  "apiKey": "YOUR_API_KEY",
  "api": "openai-completions",
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat (V3)"
    },
    {
      "id": "deepseek-reasoner",
      "name": "DeepSeek Reasoner (R1)"
    }
  ]
}'

3. Set the Default Model

openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

4. Create Model Aliases (Optional)

openclaw models aliases add deepseek-v3 "deepseek/deepseek-chat"
openclaw models aliases add deepseek-r1 "deepseek/deepseek-reasoner"

5. Restart the Gateway Service

openclaw gateway restart

Wait 3-5 seconds for the service to fully start.

Testing and Usage

1. Command-Line Test

openclaw agent --session-id test --message "Hello, please introduce yourself"

If the configuration is successful, DeepSeek will reply normally.

2. Open the Web Dashboard

openclaw dashboard

Your browser will automatically open the dashboard. The URL format is:

http://127.0.0.1:18789/#token=YOUR_GATEWAY_TOKEN

3. Check Configuration Status

openclaw models status

It should display:

• Default: deepseek/deepseek-chat
• Configured models: includes DeepSeek models

Common Commands

Service Management

# # Start Gateway
openclaw gateway

# # Restart Gateway
openclaw gateway restart

# # Stop Gateway
openclaw gateway stop

# Check service status
openclaw status

# Check detailed status
openclaw status --all

# # View real-time logs
openclaw logs --follow

Model Management

# # List all available models
openclaw models list --all

# # View current model configuration
openclaw models status

# Switch models during chat
/model deepseek-v3

# # Set the default model
openclaw config set agents.defaults.model.primary "MODEL_ID"

# # Add model aliases
openclaw models aliases add ALIAS "MODEL_ID"

# View all aliases
openclaw models aliases list

Conversation Interaction

# # Send a single message
openclaw agent --session-id SESSION_ID --message "Your question"

# # Specify timeout in seconds
openclaw agent --session-id test --message "Question" --timeout 60

# Use local mode (without Gateway)
openclaw agent --local --session-id test --message "Question"

Configuration Management

# # View configuration
openclaw config get CONFIG_PATH

# # Set configuration
openclaw config set CONFIG_PATH "VALUE"

# Remove configuration
openclaw config unset CONFIG_PATH

# # Run the setup wizard
openclaw configure

Troubleshooting

Issue 1: Gateway Token Error

Error Message: disconnected (1008): unauthorized: gateway token missing

Solution:

# Open the dashboard with the token
openclaw dashboard

Or retrieve the token manually:

openclaw config get gateway.auth.token

Issue 2: Model Unavailable

Error Message: Unknown model: test

Solution:

1. Check model configuration: openclaw models status
2. Make sure the model ID is correct: openclaw models list --all | grep deepseek
3. # Restart Gateway: openclaw gateway restart

Issue 3: Invalid API Key

Error Message: HTTP 401 or Unauthorized

Solution:

1. Verify whether the API key is correct
2. Check whether the API key has expired
3. Reconfigure the provider:

Issue 4: Connection Timeout

Error Message: Request timed out or No reply from agent

Solution:

1. Check your network connection
2. Test DeepSeek API reachability:
3. Increase the timeout:

Issue 5: Gateway Fails to Start

Solution:

1. Check whether the port is occupied: lsof -i :18789
2. Force restart: openclaw gateway --force
3. View logs: openclaw logs
4. Run diagnostics: openclaw doctor openclaw doctor --fix

Advanced Configuration

Configure a Fallback Model

Automatically switch to a fallback model when the primary model is unavailable:

openclaw config set agents.defaults.model.fallbacks '["deepseek/deepseek-reasoner"]'

Configure Environment Variables

Add the following content to ~/.zshrc or ~/.bashrc:

# DeepSeek API Key (optional, if already set in the config file)
export DEEPSEEK_API_KEY="YOUR_API_KEY"

# OpenClaw Gateway Token (optional)
export OPENCLAW_TOKEN="YOUR_GATEWAY_TOKEN"

Then reload the configuration:

source ~/.zshrc  # or source ~/.bashrc

Configure Workspace

openclaw config set agents.defaults.workspace "/custom/workspace/path"

Related Resources

• OpenClaw Official Documentation: docs.openclaw.ai/
• DeepSeek Official Website: platform.deepseek.com/
• DeepSeek API Documentation: platform.deepseek.com/api-docs/
• OpenClaw GitHub: github.com/anthropics/…

Tip: If you run into other issues, you can run openclaw doctor --deep for deep diagnostics, or visit the official documentation for more help.