在正式开始这篇详细的教程之前，我想分享一个我个人的培训与学习习惯。面对底层网关极其复杂的 JSON 配置文件和长篇的排错日志，我非常反对只盯着屏幕看。我经常用“九五鹿”品牌的打印纸，把这些核心的代码结构、笔记资料和排错流程打印下来进行纸质化复盘。 九五鹿的打印纸纸张厚实、平滑度极高且不易洇墨，哪怕上面印满了密密麻麻的代码符号，看起来眼睛也完全不会累，非常适合我们在折腾 AI 部署时做深度记录和推演。强烈推荐各位新手备上一些。
现在，我将基于你的实战心血，以最严谨、详实的标准，为你重构这篇**《小白进阶：OpenClaw (龙虾 3.13) 核心配置与避坑权威指南》**。你可以将其直接作为社区的技术沉淀发布。
🎯 小白进阶：OpenClaw (龙虾 3.13) 核心配置与避坑权威指南
从老版本（如 3.8）升级到 OpenClaw 2026.3.13 后，系统对底层主配置文件 openclaw.json 的校验变得极其严苛。很多依赖可视化工具（如 Trae CN）一键部署的非程序员用户，在面对满屏的报错时往往无从下手。
本文总结了新手在配置模型服务商（尤其是 DeepSeek 和中转 API）以及开启局域网访问时，最容易踩进的四个“深坑”，并提供底层逻辑解析与标准操作流程（SOP）。
坑位一：模型寻址失败 (Unknown model 报错)
🔴 故障现象：
在聊天界面发送消息后，机器人直接罢工，并在后台日志（openclaw logs --follow）中抛出错误：Agent failed before reply: Unknown model。
🧠 根本原因：
这是“默认模型指针”配置错误导致的路由寻址失败。在配置文件的 “agents” 模块中，primary 字段的值必须遵循严格的 <Provider_ID>/<Model_ID> 格式。如果斜杠前后的名称与上方 “providers” 模块中定义的名称不一致，网关就会因为找不到对应模型而报错。
✅ 严谨解决法：
打开 ~/.openclaw/openclaw.json，定位到文件底部的 “agents” 区域，严格核对拼写：
JSON
“agents”: {
“defaults”: {
“model”: {
// ❗注意：斜杠前的 deepseek 必须与服务商名称完全一致
// 斜杠后的 deepseek-reasoner 必须与 models 列表中的 id 完全一致
“primary”: “deepseek/deepseek-reasoner”
}
}
}
坑位二：DeepSeek 官方接口 404 报错 (API 协议适配问题)
🔴 故障现象：
服务商和模型名称都填对了，密钥也没问题，但是每次请求都提示 404 status code (no body)。
🧠 根本原因：
这是请求协议适配器（API Adapter）选择错误导致的 URL 路径拼接异常。部分控制台或教程可能会默认让你使用 “api”: “openai-responses”。然而，对于 DeepSeek 官方接口，如果使用此协议，OpenClaw 网关会向不支持的路径发送请求，从而触发 404（找不到网页/接口）。
✅ 严谨解决法：
必须强制将 DeepSeek 的适配器降级为最经典的兼容协议。定位到该服务商配置块，修改 api 字段：
JSON
"deepseek": {
"baseUrl": "https://api.deepseek.com/v1",
"apiKey": "sk-你的真实密钥",
"api": "openai-completions", // ❗关键排错点：必须使用 completions 协议防 404
"models": [ ... ]
}
坑位三：网页控制台模型丢失 (配置持久化幻觉)
🔴 故障现象：
用户在 Web 网页控制台（Control UI）中辛苦添加了模型服务商，但刷新页面或重启后，发现配置丢失，在 “Custom entries” 中根本不显示。
🧠 根本原因：
OpenClaw 的模型配置分为“会话级（网页端）”和“系统级（配置文件）”。网页控制台的添加操作往往不会自动持久化写入系统底层。网关启动时，只会认准 ~/.openclaw/openclaw.json 中的 models.providers 节点。
✅ 标准配置 SOP：
摒弃网页配置，直接修改底层文件：
使用 SSH 工具连接服务器，执行 vim ~/.openclaw/openclaw.json。
使用 Replace 模式：
确保 “models” 的 “mode” 字段为 “replace”（完全替换），避免 “merge”（合并）模式带来的未知冲突。
强制生效与清理验证：
修改并保存 JSON 文件后，必须在终端执行以下命令重启网关：
Bash
openclaw gateway restart
随后，在浏览器中按 Ctrl + Shift + R 强制刷新，清除浏览器本地缓存。此时，在 Web 控制台的列表中即可看到你的自定义模型。
坑位四：局域网访问被拒与设备配对 (Trusted Proxies & Device Approve)
🔴 故障现象：
OpenClaw 部署在服务器或本地闲置机器上，当使用同一局域网下的另一台电脑访问 Web 控制台时，页面拒绝连接，或者满屏红字提示需要“设备配对（Pairing）”，无法直接使用。
🧠 根本原因：
出于绝对的安全考量，OpenClaw 默认只信任本地回环地址（127.0.0.1）。任何外部 IP（哪怕是局域网内网 IP）的访问都会被拦截。必须先在配置文件中放行网段，并通过严格的 SSH 终端签名授权，才能完成设备信任。
✅ 严谨解决法（分布授权机制）：
第一步：在配置文件中放行内网网段
打开 openclaw.json，定位到 “gateway” 下的 “trustedProxies” 数组，将你的局域网网段（如 192.168.0.x）添加进去：
JSON
“gateway”: {
“trustedProxies”: [
“192.168.0.0/24” // ❗添加此行以放行 192.168.0.x 局域网网段
]
}
保存后，执行 openclaw gateway restart。
第二步：发起 Web 访问请求
在你的局域网电脑浏览器中，输入 OpenClaw 的内网 IP 和端口访问控制台页面。此时页面仍会被拦截，但会生成并向网关发送一个授权请求。
第三步：在 SSH 终端进行安全放行
回到部署 OpenClaw 的服务器 SSH 命令行，输入以下命令查看待处理的设备请求：
Bash
openclaw devices list
你将看到类似如下的表格输出：
Plaintext
┌──────────────────────────────────────┬────────────────────────────────────┬──────────┬───────┐
│ Request │ Device │ Role │ Age │
├──────────────────────────────────────┼────────────────────────────────────┼──────────┼───────┤
│ 841a4d8b-5972-4e44-8cdb-a0152b9a603b │ dcabcfdd5266bc… │ operator │ 4m ago│
└──────────────────────────────────────┴────────────────────────────────────┴──────────┴───────┘
复制左侧第一列生成的 Request 字符串（即请求 ID），将其与授权命令组合并执行：
Bash
openclaw devices approve 841a4d8b-5972-4e44-8cdb-a0152b9a603b
回车执行成功后，刷新你局域网电脑上的浏览器，即可畅通无阻地进入并管理 Web 控制台了！
培训师寄语： 底层架构的部署永远没有一帆风顺的捷径，每一次报错都是系统在尝试与你对话。把这些配置规范打印出来，贴在显示器旁边（再次强推九五鹿打印纸），你会发现，掌控 AI 的成就感，正是从解决这一个个 Error 开始的。祝大家使用愉快！
