OpenClaw 配置

OpenClaw ↗ 是一款开源的本地 AI 助手，可以把模型能力接入 Telegram、WhatsApp、Slack 等消息渠道。下面使用 LAYSO AI 的兼容接口完成安装、模型供应商、Agent 与首次调用配置。

一个 Key，访问全平台模型

模型按照 LAYSO AI 模型与价格页面显示的当前价格计费。每个成功请求都有独立扣费明细，失败任务不会产生扣费。

为什么使用 LAYSO AI？

一个 Key 访问平台模型：不用为每个模型分别管理密钥。
兼容主流协议：OpenAI Responses、Anthropic Messages 与 Gemini 原生协议均可接入。
适合多 Agent 分工：可为主 Agent、研究任务和日常任务设置不同模型。
费用可追踪：每次成功请求都能在任务明细中核对模型、Token 与扣费。

OpenClaw 的长任务和多 Agent 工作流可能消耗较多 Token。请先在模型与价格页面 ↗ 根据能力、上下文长度和价格选择模型，再复制页面显示的完整模型 ID。

安装

OpenClaw 当前要求 Node.js 22.22.3+、24.15+ 或 25.9+，推荐使用 Node.js 26。下面使用官方安装脚本。

macOS / Linux / WSL2

bash

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell

powershell

iwr -useb https://openclaw.ai/install.ps1 | iex

验证安装

bash

openclaw --version

能够正常显示版本号即表示安装完成。

图片位置 01安装并检查 OpenClaw 版本/screenshots/openclaw/01-install-version.png建议比例 16:9 · 建议尺寸 1600 × 900

快速开始

第 1 步：获取 API Key 和模型 ID

前往 LAYSO AI API Key 页面 ↗ 创建并复制 API Key。
打开 LAYSO AI 模型与价格 ↗，选择模型并复制完整模型 ID。

不要猜测模型别名，也不要把真实 API Key 写入项目文件或提交到 Git 仓库。

第 2 步：保存 API Key

OpenClaw 推荐把供应商密钥放在全局运行环境文件 ~/.openclaw/.env。该文件可被当前用户的 Gateway 服务读取，比项目目录中的 .env 更适合保存 Provider 密钥。

macOS / Linux / WSL2

bash

mkdir -p ~/.openclaw
printf 'LAYSO_API_KEY=sk-...\n' >> ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

Windows PowerShell

powershell

New-Item -ItemType Directory -Force "$HOME\.openclaw"
Add-Content "$HOME\.openclaw\.env" 'LAYSO_API_KEY=sk-...'

把 sk-... 替换为完整的 LAYSO AI API Key。如果文件中已经存在 LAYSO_API_KEY，请编辑原有行，不要重复追加。

第 3 步：运行配置向导

首次使用建议运行官方向导，并让 OpenClaw 安装后台 Gateway 服务：

bash

openclaw onboard --install-daemon

向导会继续配置工作目录、Gateway 和消息渠道。模型 Provider 使用下一节的 openclaw.json 配置；如果向导要求先选择模型，可暂时跳过或选择自定义 Provider，之后再以本文配置为准。

图片位置 02完成 OpenClaw 首次配置向导/screenshots/openclaw/02-onboarding.png建议比例 16:9 · 建议尺寸 1600 × 900

第 4 步：打开配置文件

OpenClaw 使用 JSON5 格式的 openclaw.json。默认位置如下：

系统	配置文件位置
macOS	`/Users/<用户名>/.openclaw/openclaw.json`
Windows	`C:\Users\<用户名>\.openclaw\openclaw.json`
Linux / WSL2	`/home/<用户名>/.openclaw/openclaw.json`

也可以让 OpenClaw 输出当前实际使用的文件位置：

bash

openclaw config file

第 5 步：添加 LAYSO AI Provider

推荐使用 OpenAI Responses 兼容方式。把 <PRIMARY_MODEL_ID> 替换为模型价格页上的完整模型 ID：

json5

{
  models: {
    mode: "merge",
    providers: {
      layso_ai: {
        baseUrl: "https://api.layso.ai/v1",
        apiKey: "${LAYSO_API_KEY}",
        api: "openai-responses",
        models: [
          {
            id: "<PRIMARY_MODEL_ID>",
            name: "LAYSO AI Primary"
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "layso_ai/<PRIMARY_MODEL_ID>"
      }
    }
  }
}

Provider ID 是 layso_ai，因此 OpenClaw 中的完整模型引用必须写成 layso_ai/<MODEL_ID>。

第 6 步：验证并打开控制台

bash

openclaw config validate
openclaw models list --provider layso_ai
openclaw gateway restart
openclaw dashboard

如果没有安装后台服务，可在当前终端运行 openclaw gateway run。进入 Dashboard 后发送一条简短消息，并到 LAYSO AI 任务明细核对模型、Token 与扣费记录。

图片位置 03在 Dashboard 验证 LAYSO AI 连接/screenshots/openclaw/03-dashboard-success.png建议比例 16:9 · 建议尺寸 1600 × 900

完整配置

Provider 协议与地址

OpenClaw 的 api 字段决定请求适配器。选择一种与模型和使用场景匹配的协议即可；首次接入推荐 OpenAI Responses。

协议	`api`	`baseUrl`	说明
OpenAI Responses	`openai-responses`	`https://api.layso.ai/v1`	推荐，适合支持 Responses API 的模型
OpenAI Chat Completions	`openai-completions`	`https://api.layso.ai/v1`	适合只支持 Chat Completions 的工具或模型
Anthropic Messages	`anthropic-messages`	`https://api.layso.ai`	Claude 请求使用根地址，不添加 `/anthropic` 或 `/v1`
Gemini 原生	`google-generative-ai`	`https://api.layso.ai`	Gemini 请求使用根地址，不添加 `/gemini` 或 `/v1beta`

同一个 Provider 只能设置一个 api。如需同时使用多种协议，请分别创建 layso_openai、layso_anthropic、layso_gemini 等 Provider ID。

Models 配置

自定义 Provider 必须在 models 数组中登记可用模型。一个 LAYSO AI API Key 可以访问平台模型，但 OpenClaw 只会显示你在当前 Provider 中登记的模型。

json5

models: [
  { id: "<PRIMARY_MODEL_ID>", name: "Primary" },
  { id: "<FAST_MODEL_ID>", name: "Fast" },
  { id: "<RESEARCH_MODEL_ID>", name: "Research" }
]

所有 ID 都应从 LAYSO AI 模型与价格页面 ↗ 复制。模型能力、上下文长度和价格以该页面的实时信息为准。

Agent 默认模型与回退

下面把主模型设为默认模型，并在主模型不可用时回退到快速模型：

json5

agents: {
  defaults: {
    model: {
      primary: "layso_ai/<PRIMARY_MODEL_ID>",
      fallbacks: ["layso_ai/<FAST_MODEL_ID>"]
    },
    models: {
      "layso_ai/<PRIMARY_MODEL_ID>": { alias: "primary" },
      "layso_ai/<FAST_MODEL_ID>": { alias: "fast" },
      "layso_ai/<RESEARCH_MODEL_ID>": { alias: "research" }
    }
  }
}

模型引用的格式始终是 <Provider ID>/<模型 ID>。只写模型 ID 会导致 OpenClaw 无法找到自定义 Provider。

多 Agent 分工

如果你已经在 OpenClaw 中创建多个 Agent，可以为不同 Agent 指定不同模型：

json5

agents: {
  defaults: {
    model: { primary: "layso_ai/<PRIMARY_MODEL_ID>" }
  },
  list: [
    { id: "main", model: "layso_ai/<PRIMARY_MODEL_ID>" },
    { id: "research", model: "layso_ai/<RESEARCH_MODEL_ID>" },
    { id: "quick", model: "layso_ai/<FAST_MODEL_ID>" }
  ]
}

先让默认 Agent 完成一次成功调用，再逐步添加多 Agent 与渠道配置，排错会更容易。

完整示例

以下示例包含一个 Provider、三种模型角色、默认模型与回退模型。请替换三个占位模型 ID；如果只使用一个模型，可删除另外两项及其引用。

json5

{
  models: {
    mode: "merge",
    providers: {
      layso_ai: {
        baseUrl: "https://api.layso.ai/v1",
        apiKey: "${LAYSO_API_KEY}",
        api: "openai-responses",
        models: [
          { id: "<PRIMARY_MODEL_ID>", name: "LAYSO AI Primary" },
          { id: "<FAST_MODEL_ID>", name: "LAYSO AI Fast" },
          { id: "<RESEARCH_MODEL_ID>", name: "LAYSO AI Research" }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "layso_ai/<PRIMARY_MODEL_ID>",
        fallbacks: ["layso_ai/<FAST_MODEL_ID>"]
      },
      models: {
        "layso_ai/<PRIMARY_MODEL_ID>": { alias: "primary" },
        "layso_ai/<FAST_MODEL_ID>": { alias: "fast" },
        "layso_ai/<RESEARCH_MODEL_ID>": { alias: "research" }
      }
    }
  }
}

模型选择建议

角色	选择重点	适合任务
主模型	综合能力、工具调用、稳定性	日常对话、代码、跨工具任务
研究模型	长上下文、推理能力	复杂分析、长文档、多步骤研究
快速模型	响应速度、价格	分类、摘要、简单问答和高频任务

不要照搬其他平台的模型别名。请在 LAYSO AI 模型与价格页面选择当前可用模型，并把完整 ID 写入 Provider。

接入消息渠道

模型调用验证成功后，再运行配置向导添加 Telegram、WhatsApp 或 Slack 等渠道：

bash

openclaw onboard

按照向导完成渠道凭据、账号绑定和权限配置。渠道接入成功后，可使用下面的命令检查状态：

bash

openclaw channels status --probe
openclaw gateway status --deep

图片位置 04连接 Telegram、WhatsApp 或 Slack/screenshots/openclaw/04-channel-connected.png建议比例 16:9 · 建议尺寸 1600 × 900

故障排除

`401 / 403` 认证失败

打开 ~/.openclaw/.env，确认 LAYSO_API_KEY 完整且没有引号外的空格或换行。
重新启动 Gateway，让后台服务重新读取环境变量。
不要把真实 Key 直接写进 openclaw.json。

`404` 或协议不匹配

检查 api 与 baseUrl 是否成对：

openai-responses / openai-completions 使用 https://api.layso.ai/v1。
anthropic-messages 使用 https://api.layso.ai，不要添加 /anthropic 或 /v1。
google-generative-ai 使用 https://api.layso.ai，不要添加 /gemini 或 /v1beta。

找不到模型

确认以下三处完全一致：

models.providers.layso_ai.models[].id 中登记的模型 ID。
agents.defaults.model.primary 中的 <MODEL_ID>。
模型与价格页面显示的完整模型 ID。

配置修改没有生效

bash

openclaw config validate
openclaw gateway restart
openclaw models status

如果出现 config reload skipped 或 Invalid config，先修复 JSON5 语法和未知字段，再重新启动 Gateway。

消息渠道没有回复

bash

openclaw channels status --probe
openclaw gateway status --deep
openclaw logs --follow

先确认模型在 Dashboard 中能够调用，再检查渠道配对、白名单和权限。

Token 消耗过高

日常任务使用更快、更经济的模型。
仅为复杂任务切换研究模型。
缩短不必要的上下文和附件。
在 LAYSO AI 任务明细中逐笔查看模型、Token 与扣费。

安全与计费

~/.openclaw/.env 只保存在本机，不要提交到 Git。
不要在截图、日志、聊天记录或公开配置示例中暴露完整 API Key。
一个 LAYSO AI API Key 可以访问全平台模型。
每个成功请求都有逐笔扣费明细，失败任务不会产生扣费。

替换占位图片

将截图放入 docs/public/screenshots/openclaw/，再把对应占位块替换为 Markdown 图片。例如：

![OpenClaw 配置向导](/screenshots/openclaw/02-onboarding.png)

OpenClaw 配置 ​

为什么使用 LAYSO AI？ ​

安装 ​

macOS / Linux / WSL2 ​

Windows PowerShell ​

验证安装 ​

快速开始 ​

第 1 步：获取 API Key 和模型 ID ​

第 2 步：保存 API Key ​

macOS / Linux / WSL2 ​

Windows PowerShell ​

第 3 步：运行配置向导 ​

第 4 步：打开配置文件 ​

第 5 步：添加 LAYSO AI Provider ​

第 6 步：验证并打开控制台 ​

完整配置 ​

Provider 协议与地址 ​

Models 配置 ​

Agent 默认模型与回退 ​

多 Agent 分工 ​

完整示例 ​

模型选择建议 ​

接入消息渠道 ​

故障排除 ​

401 / 403 认证失败 ​

404 或协议不匹配 ​

找不到模型 ​

配置修改没有生效 ​

消息渠道没有回复 ​

Token 消耗过高 ​

安全与计费 ​

替换占位图片 ​

OpenClaw 配置

为什么使用 LAYSO AI？

安装

macOS / Linux / WSL2

Windows PowerShell

验证安装

快速开始

第 1 步：获取 API Key 和模型 ID

第 2 步：保存 API Key

macOS / Linux / WSL2

Windows PowerShell

第 3 步：运行配置向导

第 4 步：打开配置文件

第 5 步：添加 LAYSO AI Provider

第 6 步：验证并打开控制台

完整配置

Provider 协议与地址

Models 配置

Agent 默认模型与回退

多 Agent 分工

完整示例

模型选择建议

接入消息渠道

故障排除

`401 / 403` 认证失败

`404` 或协议不匹配

找不到模型

配置修改没有生效

消息渠道没有回复

Token 消耗过高

安全与计费

替换占位图片