🔥 手把手教你：OpenClaw 接入第三方模型，并通过 Dashboard 成功跑通

📌 阅读提示：本文基于 2026-03-25 的实际部署经验撰写，所有命令和配置均经过验证。

---

📑 目录

• 一、最终目标
• 二、准备工作
• 三、OpenClaw 初始化
• 四、定位配置文件
• 五、核心配置详解
• 六、字段逐项解读
• 七、密钥安全建议
• 八、配置校验与排错
• 九、SSH 隧道访问 Dashboard
• 十、完整实操流程速查
• 十一、踩坑总结
• 十二、最终建议

---

一、最终目标

本文要完成的完整链路如下：

┌──────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  初始化       │ ──▶ │  配置第三方模型    │ ──▶ │  校验配置          │
│  openclaw     │     │  openclaw.json    │     │  config validate   │
│  onboard      │     │  models.providers │     │  models status     │
└──────────────┘     └──────────────────┘     └────────┬──────────┘
                                                       │
                     ┌──────────────────┐              ▼
                     │  ✅ Dashboard     │ ◀── ┌───────────────────┐
                     │  验证模型可用      │     │  SSH 隧道          │
                     └──────────────────┘     │  本地端口转发       │
                                              └───────────────────┘

💡 一句话总结：先用 openclaw onboard 把 OpenClaw 跑起来，再通过 models.providers 把第三方模型接进去。

---

二、准备工作

开始之前，请确认你已具备以下条件：

序号	准备项	说明
1	🖥️ Linux 云服务器	可正常 SSH 登录
2	📦 OpenClaw 已安装	未安装请参考官方文档
3	🔑 第三方模型凭证	包括 baseUrl、apiKey、modelId
4	🌐 本地 SSH 端口转发能力	用于访问远程 Dashboard

如果尚未安装 OpenClaw，可以使用以下命令快速开始：

# 基础初始化
openclaw onboard

# 或安装为守护进程（推荐长期使用）
openclaw onboard --install-daemon

---

三、OpenClaw 初始化

3.1 执行初始化命令

openclaw onboard

如果希望将服务注册为 daemon，可使用 openclaw onboard --install-daemon。

3.2 个人使用协议

初始化过程中会看到如下提示：

I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?

选择 Yes 即可。 含义很简单：

• OpenClaw 默认面向个人使用场景
• 多用户共享需要额外做权限和安全收敛

如果只是个人部署测试，直接选 Yes 继续。

3.3 初始化模式选择

模式	适用场景	建议
QuickStart	第一次接入、快速跑通	✅ 推荐
Manual	需要精细控制每一项配置	后续再用

💡 先把链路跑通，后续可随时通过 openclaw configure 或 openclaw config 补充配置。

3.4 模型提供商选择

这是最关键的一步。

• 内置支持的标准提供商 → 直接在向导中选择对应项
• 第三方代理 / OpenAI 兼容接口 / 自建网关 / 聚合转发平台 → 建议 先跳过向导，后续手动编辑配置文件

因为真正决定"能不能连上"的，是配置文件中的以下三个字段：

models.providers  ·  agents.defaults.model.primary  ·  agents.defaults.models

3.5 Skills 和 Hooks

⚠️ 第一次接入时建议全部跳过

先把模型链路打通，后续再逐步开启功能，排错会轻松很多。

3.6 启动方式

当向导询问 How do you want to hatch your bot? 时，建议选择：

Open the Web UI

原因：

• ✅ 最快看到结果
• ✅ 最容易判断模型是否接入成功
• ✅ 出问题时方便观察 Dashboard 报错信息

---

四、定位配置文件

⚠️ 不要猜路径！

很多人会直接猜 /home/admin/.openclaw/openclaw.json，但配置文件的实际路径受多种因素影响：

• 默认 home 路径
• OPENCLAW_CONFIG_PATH 环境变量
• OPENCLAW_HOME 环境变量
• 当前运行用户

正确做法：让 OpenClaw 自己告诉你——

openclaw config file

另外需要注意：

📝 OpenClaw 的配置格式是 JSON5（不是严格 JSON），支持注释和尾逗号，手动维护更友好。

---

五、核心配置详解：OpenClaw 接入第三方模型

这是全文重点。以下是一份 脱敏后的完整参考配置，对应场景为：

通过 OpenAI-compatible 接口接入一个第三方模型

{
  // ═══════════════════════════════════════════
  // 📦 模型配置
  // ═══════════════════════════════════════════
  models: {
    mode: "merge",
    providers: {
      myproxy: {
        baseUrl: "https://YOUR_API_HOST/v1",
        apiKey: "${THIRD_PARTY_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gemini-3-flash",
            name: "Gemini 3 Flash (Custom Provider)",
            api: "openai-completions",
            reasoning: false,
            input: ["text", "image"],
            cost: {
              input: 0,
              output: 0,
              cacheRead: 0,
              cacheWrite: 0,
            },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },

  // ═══════════════════════════════════════════
  // 🤖 Agent 默认配置
  // ═══════════════════════════════════════════
  agents: {
    defaults: {
      model: {
        primary: "myproxy/gemini-3-flash",
      },
      models: {
        "myproxy/gemini-3-flash": {},
      },
      workspace: "~/.openclaw/workspace",
    },
  },

  // ═══════════════════════════════════════════
  // 🔧 工具配置
  // ═══════════════════════════════════════════
  tools: {
    profile: "coding",
  },

  // ═══════════════════════════════════════════
  // 🌐 网关配置
  // ═══════════════════════════════════════════
  gateway: {
    port: 18789,
    mode: "local",
    bind: "loopback",
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

---

六、字段逐项解读

很多接入失败都出在配置细节上，建议逐项对照检查。

6.1 models.mode

mode: "merge"

模式	含义	建议
merge	保留默认模型目录，同时合并自定义 provider	✅ 推荐
replace	用自定义配置完全覆盖默认内容	❌ 初次不建议

6.2 models.providers（⭐ 核心）

providers: {
  myproxy: {
    baseUrl: "https://YOUR_API_HOST/v1",
    apiKey: "${THIRD_PARTY_API_KEY}",
    api: "openai-completions",
  },
}

字段	说明	注意事项
myproxy	自定义的 provider 名称	需要和 primary 中的前缀一致
baseUrl	第三方接口地址	⚠️ 注意是否需要 /v1 后缀
apiKey	访问密钥	建议使用环境变量引用
api	调用协议适配器	OpenAI 兼容用 openai-completions

⚠️ 如果对方是 Anthropic 兼容接口，则不能使用 openai-completions，需要改为对应的消息协议适配器。协议类型必须与接口匹配！

6.3 baseUrl 的 /v1 问题

这是最常见的坑之一：

✅ https://YOUR_API_HOST/v1       ← 大多数情况需要带 /v1
❌ https://YOUR_API_HOST           ← 缺少 /v1，可能导致 404 或静默失败

少了 /v1 可能出现：404 错误、请求路径不对、"看起来连上了但始终调用失败"等诡异问题。务必查阅对方平台文档确认。

6.4 models[].id 必须与平台实际模型名一致

id: "gemini-3-flash"    // 必须是对方平台真实支持的模型 ID

常见症状：Dashboard 能打开、Provider 看起来也配上了，但一调用就报"模型不存在"。

6.5 agents.defaults.model.primary

primary: "myproxy/gemini-3-flash"
//        ───┬───  ──────┬──────
//        provider名     模型ID

格式固定为 provider/model，前后两部分必须与 providers 中的定义一一对应。

6.6 agents.defaults.models（容易遗漏！）

models: {
  "myproxy/gemini-3-flash": {},
}

📌 官方文档明确指出：如果设置了 agents.defaults.models，它会成为可用模型的 allowlist。

只配了 primary 而没配这里，可能导致：

• 模型不显示
• 默认模型解析异常
• 模型选择器行为不符合预期

6.7 tools.profile

Profile	权限范围	建议场景
coding	标准编码工具集	✅ 初次接入推荐
full	完整工具权限	确认需要高权限时再启用

当前最重要的是 先证明模型能用，而不是把所有权限都放到最大。

---

七、密钥安全建议

敏感信息	风险等级	处理建议
apiKey	🔴 高	使用环境变量 ${THIRD_PARTY_API_KEY}
gateway.auth.token	🔴 高	使用环境变量 ${OPENCLAW_GATEWAY_TOKEN}
clientSecret	🔴 高	脱敏或使用 SecretRef
服务器 IP	🟡 中	替换为 你的服务器IP
带 token 的 Dashboard URL	🔴 高	不要截图或粘贴原文

✅ 做法一：环境变量引用

apiKey: "${THIRD_PARTY_API_KEY}"
token: "${OPENCLAW_GATEWAY_TOKEN}"

✅ 做法二：SecretRef（正式环境推荐）

OpenClaw 对部分敏感配置支持 SecretRef 管理。长期运行的环境建议将 token、apiKey 等敏感信息迁移到更安全的管理方式。

---

八、配置校验与排错

修改完配置后，不要直接打开 Dashboard 盲测，先做以下检查：

8.1 配置格式校验

# 基础校验
openclaw config validate

# 结构化 JSON 输出（便于脚本处理）
openclaw config validate --json

可帮助排除：❌ 配置路径错误 · ❌ JSON5 语法错误 · ❌ 字段结构不对

8.2 模型状态检查

# 查看主模型和认证状态
openclaw models status

# 查看完整的可用模型列表
openclaw models list

重点关注：

• ✅ 当前主模型是否正确解析
• ✅ Provider 是否被识别
• ✅ 认证信息是否完整
• ✅ 模型是否进入默认候选集

---

九、通过 SSH 隧道访问 Dashboard

如果 OpenClaw 部署在云服务器上，最推荐的访问方式是 SSH 本地端口转发。

9.1 建立 SSH 隧道

在本地终端执行：

ssh -N -L 18789:127.0.0.1:18789 root@你的服务器IP

9.2 打开 Dashboard

在服务器上执行（获取带认证信息的访问入口）：

openclaw dashboard

9.3 本地浏览器访问

http://127.0.0.1:18789/

📌 官方安全建议：Dashboard 权限很高，不建议直接暴露到公网。推荐的访问方式：

• localhost 直接访问
• Tailscale 组网访问
• SSH 隧道 端口转发

个人部署场景下，loopback + SSH 隧道 是最稳方案。

---

十、完整实操流程速查

📋 照着下面的步骤依次执行即可。

 Step 1 ──▶ Step 2 ──▶ Step 3 ──▶ Step 4 ──▶ Step 5 ──▶ Step 6 ──▶ Step 7 ──▶ Step 8
 初始化      定位配置    编辑配置    校验配置    检查模型    打开面板    SSH隧道    浏览器验证

步骤	操作	命令 / 说明
Step 1	初始化 OpenClaw	openclaw onboard
Step 2	确认配置文件路径	openclaw config file
Step 3	编辑配置文件	重点配置 models.providers、primary、models allowlist、gateway.auth
Step 4	校验配置	openclaw config validate
Step 5	检查模型状态	openclaw models status
Step 6	打开 Dashboard	openclaw dashboard
Step 7	本地建立 SSH 隧道	ssh -N -L 18789:127.0.0.1:18789 admin@你的服务器IP
Step 8	浏览器访问验证	打开 http://127.0.0.1:18789/

✅ 如果一切正常，此时你应该能在 Dashboard 中看到模型已成功接入并可用。

---

十一、踩坑总结

🕳️ 以下是实操过程中最容易踩的 5 个坑，建议收藏。

#	坑	症状	解决方案
1	🕳️ 直接猜配置文件路径	修改了错误的文件，配置不生效	使用 openclaw config file 获取真实路径
2	🕳️ baseUrl 缺少 /v1	404 错误或请求静默失败	确认第三方平台文档，通常需带 /v1
3	🕳️ 只配 primary 未配 models	模型不显示或候选集为空	primary 和 agents.defaults.models 必须同时配置
4	🕳️ Provider 名与模型名不对齐	模型解析失败	确保 primary: "provider名/模型ID" 与定义一致
5	🕳️ 真实密钥直接发布	密钥泄露、安全风险	统一使用环境变量引用，发布前脱敏

---

十二、最终建议

如果你也是第一次接入 OpenClaw 第三方模型，不要一上来就想把所有功能全配完。

最稳的方式是 —— 先跑通最小闭环：

openclaw onboard → 改配置 → validate → models status → Dashboard 验证

这条链路跑通之后，再逐步扩展：

• 🔌 Skills 配置
• 🪝 Hooks 使用
• 📡 Channels 接入
• 🤖 多模型切换
• 🔐 更细粒度的 Tools 权限
• ⚙️ Automation 自动化

💬 一句话总结：OpenClaw 接第三方模型，真正的关键不在向导，而在 models.providers + primary model + models allowlist 这三个地方有没有配对。

---

十四、后记

本文是一份来自实际部署的经验总结。如果你正在折腾以下任一场景，希望这篇能帮你少踩几个坑：

• 🔧 OpenClaw 首次部署
• 🔌 第三方模型接入
• 🛠️ 自定义 Provider 配置
• 🌐 服务器远程访问 Dashboard

📝 后续计划：如果后续整理出多模型切换、Skills 配置、Hooks 使用、Dashboard 深度联调等内容，会继续更新，欢迎关注！

---

📣 觉得有帮助？ 欢迎 点赞 👍 收藏 ⭐ 关注 三连，你的支持是我持续输出的动力！