DeepSeek 接入与使用指南：API、客户端与常见排查

这是一份面向日常使用的 DeepSeek 配置教程。文中的 BASE_URL、API_KEY、模型名请按你的服务实际情况替换。不要把 API Key 发给别人，也不要提交到公开仓库。

1. 适合哪些场景

DeepSeek 适合放在这些工作流里：

• 日常问答、资料整理、长文本总结；
• 代码解释、脚本生成、错误排查；
• 接入 OpenAI 兼容客户端、Bot、内部工具；
• 作为 Codex / OpenClaw / Hermes 等 Agent 工具的模型供应商之一。

如果你的服务提供的是 OpenAI 兼容接口，接入方式通常就是：

BASE_URL=https://你的服务地址/v1
API_KEY=你的_API_KEY
MODEL=deepseek-chat

推理模型可按实际可用名称替换，例如：

MODEL=deepseek-reasoner

---

2. 通用 API 调用

cURL 示例

curl https://你的服务地址/v1/chat/completions \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一个清晰、直接的助手。"},
      {"role": "user", "content": "用三句话解释 DeepSeek 适合做什么。"}
    ]
  }'

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="你的_API_KEY",
    base_url="https://你的服务地址/v1",
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个清晰、直接的助手。"},
        {"role": "user", "content": "写一个 Python 读取 CSV 的示例。"},
    ],
)

print(response.choices[0].message.content)

JavaScript 示例

import OpenAI from "openai"

const client = new OpenAI({
  apiKey: "你的_API_KEY",
  baseURL: "https://你的服务地址/v1",
})

const response = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [
    { role: "system", content: "你是一个清晰、直接的助手。" },
    { role: "user", content: "给我一个 Node.js 读取 JSON 文件的例子。" },
  ],
})

console.log(response.choices[0].message.content)

---

3. Windows PowerShell 测试

Windows 用户可以直接用 PowerShell 验证接口是否可用：

$body = @{
  model = "deepseek-chat"
  messages = @(
    @{ role = "user"; content = "你好，简单介绍一下 DeepSeek。" }
  )
} | ConvertTo-Json -Depth 5

curl.exe https://你的服务地址/v1/chat/completions `
  -H "Authorization: Bearer 你的_API_KEY" `
  -H "Content-Type: application/json" `
  -d $body

如果中文乱码，先确认终端编码：

chcp 65001

---

4. 接入 Codex / OpenClaw / Hermes

只要工具支持 OpenAI 兼容供应商，一般填这三项即可：

Provider Name: deepseek
Base URL: https://你的服务地址/v1
API Key: 你的_API_KEY
Model: deepseek-chat

如果需要更强推理能力，可以把模型切换为：

deepseek-reasoner

注意：不同客户端对 Responses API、Chat Completions API 的支持不完全一样。如果某个客户端配置 responses 不通，可以切回普通 chat/completions 兼容模式，或者在该客户端里选择 OpenAI Compatible / Custom Provider。

---

5. 推荐参数

参数	建议	说明
temperature	0.2 - 0.7	越低越稳定，越高越发散
max_tokens	按任务设置	长文总结、代码生成可适当调高
stream	true	聊天客户端建议开启流式输出
model	deepseek-chat	通用对话与代码任务
model	deepseek-reasoner	更复杂的推理、规划、分析任务

示例：

{
  "model": "deepseek-chat",
  "temperature": 0.3,
  "stream": true,
  "messages": [
    {"role": "user", "content": "按步骤帮我排查这个报错。"}
  ]
}

---

6. 常见问题

401 / Unauthorized

通常是 API Key 错误、复制不完整，或请求头没有带上：

Authorization: Bearer 你的_API_KEY

404 / Model not found

模型名和服务侧支持的名称不一致。先用服务商后台展示的模型名测试，例如：

deepseek-chat

请求一直等待

可能是任务太长、服务繁忙或客户端超时太短。建议：

• 开启 stream: true；
• 缩短输入内容；
• 客户端超时设置到 120 秒以上；
• 先用简单问题验证接口连通性。

JSON 解析失败

常见原因是请求体引号、逗号、换行格式不对。排查时先用最小请求体：

{
  "model": "deepseek-chat",
  "messages": [{"role": "user", "content": "hello"}]
}

---

7. 最小验证清单

上线或交给别人使用前，至少确认：

• Base URL 包含 /v1；
• API Key 没有多复制空格；
• deepseek-chat 能正常返回；
• Windows PowerShell 和 macOS/Linux cURL 都能跑通；
• 客户端里模型名、供应商名、鉴权方式一致。