前言

相信不少使用 OpenClaw 的玩家都有同款困扰：翻遍全网各类教程、技术社群、开源文档，始终找不到一套完整可用的 DeepSeek 官方 APIKey 配置方案。网上零散教程要么步骤缺失，要么版本老旧适配不了新版本，照着操作频频踩坑失败。

索性我亲自一步步实操调试、逐个环节排查问题，摸索出一套可直接落地的完整流程，再由 Claude Code 根据完整实操记录整理成文。专门分享给所有想在 OpenClaw 中绑定 DeepSeek 官方原生 API 的小伙伴，全程无删减、无套路，照着步骤一步步来，新手也能一次性配置成功。

目录

系统要求 安装 OpenClaw 初始化配置 配置 DeepSeek 官方 API 测试与使用 常用命令 故障排除 高级配置

系统要求

想要平稳运行并正常配置调用，首先要满足基础环境门槛：

  • 操作系统：兼容 macOS、Linux、Windows WSL 子系统
  • Node.js：必须 22 及以上版本，老手建议用 nvm 做版本管理，避免环境冲突
  • 网络环境：可正常直连访问 DeepSeek 官方接口api.deepseek.com，网络不通后续配置全部无效

安装 OpenClaw

1. 全局安装最新版



    
 
  1. npm install -g openclaw@latest
    2. 



安装过程无需额外操作，全程自动拉取依赖，耗时大概3-5分钟，会自动下载约674个依赖组件，耐心等待安装完成即可。


2. 校验安装是否成功




    
 
  1. openclaw --version
    2. 



终端正常输出类似🦞OpenClaw2026.2.9 版本信息，就代表安装无误，可以进入下一步配置。


初始化配置


1. 执行初始化配置向导




    
 
  1. openclaw onboard --install-daemon --non-interactive --accept-risk
    2. 



参数简单说明：


    
 
  • --install-daemon：自动安装后台守护进程，常驻运行
    • 
 
  • --non-interactive：免交互式弹窗，一键静默配置
    • 
 
  • --accept-risk：自动同意安全风险声明，省去手动确认步骤
    • 



2. 查看后台服务运行状态




    
 
  1. openclaw status
    2. 



确认 Gateway 网关服务处于正常运行状态，这是后续模型调用的核心基础。


配置 DeepSeek 官方 API


1. 申领 DeepSeek 官方 API Key


前往 DeepSeek 官方平台完成注册入驻，在开发者中心生成专属 API 密钥，标准格式为sk- 开头的一串加密字符。


2. 接入配置 DeepSeek 模型服务商


执行下方命令，记得把你的API_KEY替换成自己申领的真实密钥：




    
 
  1. openclaw config set models.providers.deepseek '{
    2. 
 
  2. "baseUrl": "https://api.deepseek.com/v1",
    3. 
 
  3. "apiKey": "你的API_KEY",
    4. 
 
  4. "api": "openai-completions",
    5. 
 
  5. "models": [
    6. 
 
  6. {
    7. 
 
  7. "id": "deepseek-chat",
    8. 
 
  8. "name": "DeepSeek Chat (V3)"
    9. 
 
  9. },
    10. 
 
  10. {
    11. 
 
  11. "id": "deepseek-reasoner",
    12. 
 
  12. "name": "DeepSeek Reasoner (R1)"
    13. 
 
  13. }
    14. 
 
  14. ]
    15. 
 
  15. }'
    16. 



3. 设定全局默认调用模型




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



4. 自定义模型别名（可选推荐）


设置简易别名，后续聊天切换模型更方便：




    
 
  1. openclaw models aliases add deepseek-v3 "deepseek/deepseek-chat"
    2. 
 
  2. openclaw models aliases add deepseek-r1 "deepseek/deepseek-reasoner"
    3. 



5. 重启网关服务生效




    
 
  1. openclaw gateway restart
    2. 



等待3-5秒，让网关服务完全重启加载新配置。


测试与使用


1. 命令行快速连通测试




    
 
  1. openclaw agent --session-id test --message "你好，请介绍一下你自己"
    2. 



如果配置无误，DeepSeek 模型会正常以中文回复，代表接口调用完全打通。


2. 启动 Web 可视化控制面板




    
 
  1. openclaw dashboard
    2. 



命令执行后会自动唤起浏览器打开管理面板，访问地址格式如下：




    
 
  1. http://127.0.0.1:18789/#token=你的gateway_token
    2. 



3. 查看全局模型配置状态




    
 
  1. openclaw models status
    2. 



终端会清晰展示：默认模型为deepseek/deepseek-chat，已配置列表中正常显示 DeepSeek 两大模型即代表配置完整。


常用命令


服务管理




    
 
  1. # 启动 Gateway 网关
    2. 
 
  2. openclaw gateway
    3. 
 
  3. 
 
  4. # 重启 Gateway 网关
    5. 
 
  5. openclaw gateway restart
    6. 
 
  6. 
 
  7. # 停止 Gateway 网关
    8. 
 
  8. openclaw gateway stop
    9. 
 
  9. 
 
  10. # 查看基础运行状态
    11. 
 
  11. openclaw status
    12. 
 
  12. 
 
  13. # 查看完整详细状态
    14. 
 
  14. openclaw status --all
    15. 
 
  15. 
 
  16. # 实时监听运行日志
    17. 
 
  17. openclaw logs --follow
    18. 



模型管理




    
 
  1. # 列出所有已加载可用模型
    2. 
 
  2. openclaw models list --all
    3. 
 
  3. 
 
  4. # 查看当前模型配置概况
    5. 
 
  5. openclaw models status
    6. 
 
  6. 
 
  7. # 对话内快速切换模型
    8. 
 
  8. /model deepseek-v3
    9. 
 
  9. 
 
  10. # 重新设置全局默认模型
    11. 
 
  11. openclaw config set agents.defaults.model.primary "模型ID"
    12. 
 
  12. 
 
  13. # 新增模型自定义别名
    14. 
 
  14. openclaw models aliases add 别名 "模型ID"
    15. 
 
  15. 
 
  16. # 查看全部已设置别名
    17. 
 
  17. openclaw models aliases list
    18. 



对话交互




    
 
  1. # 发起单轮会话提问
    2. 
 
  2. openclaw agent --session-id 会话ID --message "你的问题"
    3. 
 
  3. 
 
  4. # 自定义请求超时时长（单位：秒）
    5. 
 
  5. openclaw agent --session-id test --message "问题" --timeout 60
    6. 
 
  6. 
 
  7. # 本地直连模式，不经过 Gateway 网关
    8. 
 
  8. openclaw agent --local --session-id test --message "问题"
    9. 



配置管理




    
 
  1. # 查看指定配置项
    2. 
 
  2. openclaw config get 配置路径
    3. 
 
  3. 
 
  4. # 手动修改配置项
    5. 
 
  5. openclaw config set 配置路径 "值"
    6. 
 
  6. 
 
  7. # 删除无用配置项
    8. 
 
  8. openclaw config unset 配置路径
    9. 
 
  9. 
 
  10. # 重新唤起配置向导
    11. 
 
  11. openclaw configure
    12. 



故障排除


整理实操中最高频的5类报错问题，附直接可用的排查解决方案：


问题1：Gateway Token 授权错误


报错提示：disconnected(1008):unauthorized:gateway token missing 解决办法：




    
 
  1. # 自动打开带合法令牌的控制面板
    2. 
 
  2. openclaw dashboard
    3. 



也可手动单独获取令牌：




    
 
  1. openclaw config get gateway.auth.token
    2. 



问题2：提示未知模型不可用


报错提示：Unknownmodel:xxx 解决办法：




    
 
  1. # 核查当前已配置模型
    2. 
 
  2. openclaw models status
    3. 
 
  3. 
 
  4. # 检索核对 DeepSeek 模型ID是否正确
    5. 
 
  5. openclaw models list --all | grep deepseek
    6. 
 
  6. 
 
  7. # 修改配置后重启网关
    8. 
 
  8. openclaw gateway restart
    9. 



问题3：API Key 认证失效


报错提示：HTTP 401、Unauthorized 授权失败 解决办法： 先核对密钥是否输入错误、是否过期失效，重新配置密钥并重启服务：




    
 
  1. openclaw config set models.providers.deepseek.apiKey "新的API_KEY"
    2. 
 
  2. openclaw gateway restart
    3. 



问题4：接口请求超时无响应


报错提示：Requesttimedout 或模型无任何回复 解决办法： 先自查本地网络能否访问外网，测试接口连通性：




    
 
  1. curl -I https://api.deepseek.com/v1/models
    2. 



适当拉长请求超时时间：




    
 
  1. openclaw agent --session-id test --message "测试" --timeout 120
    2. 



问题5：Gateway 网关无法正常启动


解决办法：




    
 
  1. # 排查18789端口是否被占用
    2. 
 
  2. lsof -i :18789
    3. 
 
  3. 
 
  4. # 强制强制重启网关
    5. 
 
  5. openclaw gateway --force
    6. 
 
  6. 
 
  7. # 查看运行日志定位报错
    8. 
 
  8. openclaw logs
    9. 
 
  9. 
 
  10. # 自动诊断并修复环境问题
    11. 
 
  11. openclaw doctor
    12. 
 
  12. openclaw doctor --fix
    13. 



高级配置


配置备用兜底模型


设置主模型故障时自动切换备用模型，避免会话中断：




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



配置全局环境变量


将密钥写入环境配置文件，永久生效，无需每次手动配置： 在~/.zshrc 或~/.bashrc 中添加：




    
 
  1. # DeepSeek 官方密钥（可选）
    2. 
 
  2. export DEEPSEEK_API_KEY="你的API_KEY"
    3. 
 
  3. 
 
  4. # OpenClaw 网关令牌（可选）
    5. 
 
  5. export OPENCLAW_TOKEN="你的gateway_token"
    6. 



保存后重载配置：




    
 
  1. source ~/.zshrc 
    2. 
 
  2. # 或 source ~/.bashrc
    3. 



自定义默认工作空间




    
 
  1. openclaw config set agents.defaults.workspace "/自定义/工作空间/路径"
    2. 

 
  

        # 大数据
      
  
 
 Logo 
龙虾开发者社区
 
小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用
 
 
  
更多推荐
  
cover
 
Agent沙箱实战：Shell工具调用的路径白名单与零信任逃逸审计
 
 
avatar 龙虾开发者社区
 
cover
 
HiClaw网关的审批流设计：如何避免工具调用中的误操作灾难？
 
 
avatar 龙虾开发者社区
 
cover
 
Agent 网关密钥管理：为什么你的硬件绑定总在 session 失效时翻车
 
 
avatar 龙虾开发者社区