企业官网建设流程全解析

OpenClaw 接入 ds4：用本地 Metal 后端的 DeepSeek V4 Flash 驱动完整 Agent 工具调用

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

本文讲解如何把 OpenClaw 接到 ds4（antirez 的 DeepSeek V4 Flash 本地推理服务）上：ds4 以 OpenAI 兼容的/v1API 从本地 Metal 后端提供模型推理，OpenClaw 则通过通用的openai-completionsprovider 家族与之对接。读完本篇，你可以独立完成 ds4-server 的启动与验证、编写 OpenClaw 的 provider 配置（含按需启动localService）、理解 DeepSeek 风格thinking/reasoning_effort参数的底层契约，并用一键命令完成模型路由与 Agent 工具调用的冒烟测试。

1. ds4 在 OpenClaw 中的定位：纯配置 provider，非内置插件

ds4 不是一个随 OpenClaw 分发的 provider 插件，它只是一个实现了 OpenAI 兼容 Chat Completions 协议的外部服务。OpenClaw 通过models.providers.ds4这个配置项接入它，之后即可选择ds4/deepseek-v4-flash作为模型引用（model ref）。

核心属性如下：

从源码结构看，OpenClaw 对所有 OpenAI 兼容后端走同一条传输链路：api: "openai-completions"决定了请求以标准 Chat Completions 格式发出，而模型级别的compat元数据则负责处理各家后端的协议差异。例如 extra-params.ts 中对deepseek-v4-flash模型 id 有专门判断，并对thinkingFormat为deepseek（或未设置）的后端发出 DeepSeek 原生的thinking: { type }线格式请求——这正是 ds4 配置中compat.thinkingFormat: "deepseek"的落点。而 model.compat.ts 中的readCompatThinkingFormat负责从 provider 配置里解析compat.thinkingFormat字段，供请求构造阶段使用。

2. 环境要求与上下文大小警告

运行前提：

• 支持 Metal 的 macOS 机器；
• 一个可用的 ds4 检出目录（下称<DS4_DIR>），包含ds4-server可执行文件和 DeepSeek V4 Flash 的 GGUF 模型文件；
• 足够的内存容纳你选择的上下文长度——更大的--ctx会在服务启动时分配更多 KV 内存。

关键警告：OpenClaw 的 agent 回合包含工具 schema 和工作区上下文，token 消耗远超一条 curl 消息。--ctx 4096这种极小上下文可能通过直接 curl 测试，但完整 agent 运行会报500 prompt exceeds context。做 agent 与工具冒烟测试时至少使用--ctx 32768；只有内存充足、且想启用 ds4 Think Max 时才考虑--ctx 393216。

3. 快速上手三步走

第 1 步：启动 ds4-server。将<DS4_DIR>替换为你的 ds4 检出路径：

<DS4_DIR>/ds4-server \ --model <DS4_DIR>/ds4flash.gguf \ --host 127.0.0.1 \ --port 18000 \ --ctx 32768 \ --tokens 128

第 2 步：验证 OpenAI 兼容端点：

curl http://127.0.0.1:18000/v1/models

响应中应包含deepseek-v4-flash。

第 3 步：写入 OpenClaw provider 配置并跑一次性模型检查。添加下面第 4 节的完整配置后执行：

openclaw infer model run \ --local \ --model ds4/deepseek-v4-flash \ --thinking off \ --prompt "Reply with exactly: openclaw-ds4-ok" \ --json

4. 完整 provider 配置与字段解读

以下配置假设 ds4 已在127.0.0.1:18000上运行：

{ agents: { defaults: { model: { primary: "ds4/deepseek-v4-flash" }, models: { "ds4/deepseek-v4-flash": { alias: "DS4 local", }, }, }, }, models: { mode: "merge", providers: { ds4: { baseUrl: "http://127.0.0.1:18000/v1", apiKey: "ds4-local", api: "openai-completions", timeoutSeconds: 300, models: [ { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash (ds4)", reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 32768, maxTokens: 128, compat: { supportsUsageInStreaming: true, supportsReasoningEffort: true, maxTokensField: "max_tokens", supportsStrictMode: false, thinkingFormat: "deepseek", supportedReasoningEfforts: ["low", "medium", "high", "xhigh"], }, }, ], }, }, }, }

逐字段说明：

• mode: "merge"：让自定义 provider 与内置模型目录合并，而不是整体替换；
• apiKey: "ds4-local"：ds4 本地服务无鉴权，此值仅作占位满足 provider 契约；
• timeoutSeconds: 300：provider 级请求超时，避免长生成撞默认超时；
• contextWindow：必须与 ds4-server 的--ctx保持一致，否则 OpenClaw 会在错误的窗口假设下切分和压缩上下文；
• maxTokens：应与--tokens对齐；除非你有意让 OpenClaw 向服务端请求比服务端默认更少的输出；
• compat.supportsUsageInStreaming: true：允许 OpenClaw 在流式响应中读取 usage 统计；
• compat.maxTokensField: "max_tokens"：声明该后端用max_tokens字段（而非其他变体）控制最大输出长度；
• compat.supportsStrictMode: false：不支持 OpenAI 严格工具模式，OpenClaw 会相应放宽工具 schema 约束；
• compat.thinkingFormat: "deepseek"：告知请求构造层使用 DeepSeek 原生thinking线格式（见第 1 节的源码说明）；
• compat.supportedReasoningEfforts：声明后端接受的推理强度档位，--thinking或reasoning_effort的取值受此约束。

5. 按需启动：localService 让 ds4 随模型选择而拉起

OpenClaw 支持只在某个ds4/...模型被选中时才启动 ds4。给同一个 provider 条目加上localService即可：

{ models: { providers: { ds4: { baseUrl: "http://127.0.0.1:18000/v1", apiKey: "ds4-local", api: "openai-completions", timeoutSeconds: 300, localService: { command: "<DS4_DIR>/ds4-server", args: [ "--model", "<DS4_DIR>/ds4flash.gguf", "--host", "127.0.0.1", "--port", "18000", "--ctx", "32768", "--tokens", "128", ], cwd: "<DS4_DIR>", healthUrl: "http://127.0.0.1:18000/v1/models", readyTimeoutMs: 300000, idleStopMs: 0, }, models: [ { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash (ds4)", reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 32768, maxTokens: 128, compat: { supportsUsageInStreaming: true, supportsReasoningEffort: true, maxTokensField: "max_tokens", supportsStrictMode: false, thinkingFormat: "deepseek", supportedReasoningEfforts: ["low", "medium", "high", "xhigh"], }, }, ], }, }, }, }

localService各字段的完整语义在 Local model services 中有权威定义，要点包括：

• command必须是绝对可执行路径，不会走 Shell PATH 查找，也不做~展开；
• args是纯进程参数，不做 Shell 展开、管道、glob 或引号解析；
• healthUrl缺省时默认取baseUrl加/models，显式写出更稳妥；
• readyTimeoutMs缺省为 120000，ds4 冷启动较慢（Metal 驻留 + 模型预热），文档建议给到 300000；
• idleStopMs为 0 或省略时，由 OpenClaw 拉起的进程会一直存活直到 OpenClaw 退出。

工作机制（同样见 Local model services）：模型或嵌入请求解析到该 provider 后，OpenClaw 先探测healthUrl；健康则复用已运行服务，不健康则用command+args拉起子进程并轮询健康端点直到readyTimeoutMs到期，随后请求走正常模型传输。该服务只是最早需要它的 OpenClaw 进程的普通子进程，OpenClaw 不会替你安装 launchd、systemd 或 Docker 守护。同一 provider 的启动按 command/args/env 组合串行化，并发请求不会重复拉起服务。

6. Think Max：大上下文 + 最高推理档的联动开关

ds4 只在两个条件同时成立时启用 Think Max：

1. ds4-server以--ctx 393216或更高启动；
2. 请求携带reasoning_effort: "max"（或等价的 ds4 effort 字段）。

小上下文下会回退到 high 级推理。如果你要跑这么长的上下文，需要同步更新服务端参数和 OpenClaw 的模型元数据：

{ contextWindow: 393216, maxTokens: 384000, compat: { supportsUsageInStreaming: true, supportsReasoningEffort: true, maxTokensField: "max_tokens", supportsStrictMode: false, thinkingFormat: "deepseek", supportedReasoningEfforts: ["low", "medium", "high", "xhigh", "max"], }, }

注意supportedReasoningEfforts在这里比标准配置多了"max"档位——只有同时声明它，OpenClaw 才允许向 ds4 发出reasoning_effort: "max"请求，Think Max 才有可能被触发。

7. 验证与冒烟测试：三层递进

第一层：绕过 OpenClaw 的直接 HTTP 检查，确认服务端本身可用：

curl http://127.0.0.1:18000/v1/chat/completions \ -H 'content-type: application/json' \ -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Reply with exactly: ds4-ok"}],"max_tokens":16,"stream":false,"thinking":{"type":"disabled"}}'

第二层：OpenClaw 模型路由检查（与快速上手相同）：

openclaw infer model run \ --local \ --model ds4/deepseek-v4-flash \ --thinking off \ --prompt "Reply with exactly: openclaw-ds4-ok" \ --json

第三层：完整 agent + 工具调用冒烟测试（上下文至少 32768）：

openclaw agent \ --local \ --session-id ds4-tool-smoke \ --model ds4/deepseek-v4-flash \ --thinking off \ --message "Use the shell command pwd once, then reply exactly: tool-ok <output>" \ --json \ --timeout 240

预期结果（可用于自动化断言）：

• executionTrace.winnerProvider为ds4；
• executionTrace.winnerModel为deepseek-v4-flash；
• toolSummary.calls至少为1（证明 OpenAI 风格tools/tool_calls链路打通）；
• finalAssistantVisibleText以tool-ok开头。

8. 故障排查

curl /v1/models连不上：ds4 没在运行，或没有绑定到baseUrl中声明的主机/端口。先启动ds4-server再重试：

curl http://127.0.0.1:18000/v1/models

500 prompt exceeds context：配置的--ctx对 OpenClaw 的回合来说太小。调大ds4-server --ctx，同时把models.providers.ds4.models[].contextWindow改成一致的值。带工具的完整 agent 回合所需上下文远大于一条 curl 单消息。

Think Max 不生效：ds4 只在--ctx至少为393216且请求要求reasoning_effort: "max"时才走 Think Max，小上下文会回退到 high 推理。另外检查模型元数据的supportedReasoningEfforts是否包含"max"。

首个请求很慢：ds4 有冷 Metal 驻留与模型预热阶段。由 OpenClaw 按需拉起服务时，把localService.readyTimeoutMs设为 300000，避免就绪轮询在预热完成前超时报错。

9. 延伸阅读

• Local model services：localService全部字段的完整语义与冷启动/就绪/空闲停机控制；
• Local models：本地模型后端的选择与操作指引；
• Model providers：provider 引用、鉴权与故障转移的通用机制；
• DeepSeek：DeepSeek 官方 provider 的原生行为与 thinking 控制，可与 ds4 的 DeepSeek 线格式对照阅读。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw