本教程为从0到1全流程，覆盖Zeabur部署、初始化避坑、OpenRouter完整配置、公网访问、功能验证、报错排查全环节，新手可全程跟着操作。

一、前置准备（必须先完成）

1. Zeabur账号：注册并登录Zeabur平台（https://zeabur.com），支持GitHub/邮箱登录。
2. OpenRouter API Key：

• 访问OpenRouter官网（https://openrouter.ai）注册登录
• 进入API Keys页面，创建新密钥，密钥以 sk-or- 开头，仅显示一次，务必妥善保存
  3. 合规提醒：OpenRouter为境外AI服务平台，未在中国大陆地区提供直接服务，请您通过合法合规的渠道了解和使用相关服务，严格遵守国家相关法律法规。

步骤1：创建服务

1. 登录Zeabur控制台，进入「项目」，点击「新建项目」，自定义项目名称（如 openclaw-demo ）
2. 进入项目后，点击「添加服务」，选择「镜像部署」
3. 在镜像地址栏输入官方镜像： ghcr.io/openclaw-ai/openclaw:latest ，点击「部署」

步骤2：基础配置（部署前/部署后均可修改）

1. 端口配置：进入服务「设置」→「网络」，添加端口映射：

• 容器端口： 18789 
• 勾选「启用公网访问」，Zeabur会自动生成公网访问地址
  2. 环境变量（可选，提前配置更省事）：进入「设置」→「环境变量」，添加：
  键 值 说明
   OPENROUTER_API_KEY   sk-or-你的OpenRouter密钥  提前写入密钥，后续无需手动配置
  3. 点击「保存」，等待服务重启并部署完成（状态变为「运行中」）

步骤3：进入容器终端

部署完成后，点击服务右上角的「终端」，即可进入OpenClaw的命令行界面，后续所有操作均在此终端执行。

三、OpenClaw 初始化向导（关键避坑环节）

首次进入终端，会自动启动初始化向导，严格按以下说明选择，避免踩坑：

1. 安全提示：选择 Yes ，确认本地网关模式
2. 模型提供商选择：直接选择 skip for now （跳过，后续我们手动配置OpenRouter）
3. 技能依赖安装：勾选 Skip for now (Continue without installing dependencies) ，直接跳过所有技能安装（后续可按需安装）
4. 节点包管理器选择：默认 npm ，直接回车即可
5. goplaces API Key设置：选择 No ，无需配置
6. Web搜索配置：选择 Skip for now ，后续可按需开启
7. 等待向导执行完成，出现 Onboarding complete. Use the dashboard link above to control OpenClaw. 即初始化完成。

四、OpenRouter 完整接入配置（2种方法二选一）

方法一：命令行分步配置（推荐，新手友好）

按以下顺序执行命令，避免出现配置校验报错，复制时请替换为你的真实密钥。

1. 配置OpenRouter API基础地址（必填，缺失会报错）

openclaw config set models.providers.openrouter.baseUrl "https://openrouter.ai/api/v1"

2. 配置API协议类型（必填，OpenRouter兼容OpenAI格式）

openclaw config set models.providers.openrouter.api "openai-completions"

3. 配置你的OpenRouter API Key

openclaw config set models.providers.openrouter.apiKey "sk-or-你的OpenRouter密钥"

4. 设置默认使用的OpenRouter模型（必填，否则无法正常对话）
新手推荐先用免费模型，可替换为OpenRouter支持的任意模型ID

openclaw config set agents.defaults.model.primary "openrouter/meta-llama/llama-3.1-8b-instruct:free"

5. 重启网关，让所有配置生效

openclaw gateway restart

方法二：配置文件一键覆盖(推荐方法一不行的)

如果命令行持续出现 Config validation failed 报错，直接用此方法，一次性写入完整配置。

1. 终端执行命令，打开配置文件

nano ~/.openclaw/openclaw.json

2. 复制以下完整配置，全量替换文件内原有内容，仅需修改 apiKey 为你的真实密钥

{
  "gateway": {
    "auth": {
      "token": "自动生成，无需修改，保留原有值即可"
    }
  },
  "env": {},
  "models": {
    "mode": "merge",
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-你的OpenRouter密钥",
        "api": "openai-completions"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/meta-llama/llama-3.1-8b-instruct:free",
        "fallbacks": []
      }
    }
  }
}

3. 保存退出：按 Ctrl+O ，回车确认保存，再按 Ctrl+X 退出编辑器
4. 重启网关生效

openclaw gateway restart

五、公网访问 Web 控制面板

Zeabur容器内的 127.0.0.1:18789 无法直接在手机/电脑浏览器访问，按以下步骤配置公网访问：

1. 进入Zeabur服务的「设置」→「网络」，确认已开启 18789 端口的公网访问，复制Zeabur生成的公网地址（格式如 xxx.zeabur.app ）
2. 终端执行命令，获取你的控制面板访问Token

openclaw config get gateway.auth.token

3. 浏览器访问完整地址：

https://你的Zeabur公网地址/#token=你获取到的Token

4. 正常打开页面即访问成功，无需额外配置。

六、配置验证与功能测试

1. 命令行验证配置完整性

终端执行以下命令，查看OpenRouter配置是否完整

openclaw config get models.providers.openrouter

正常输出应包含 baseUrl 、 api 、 apiKey 三个字段，无 undefined 提示，即配置有效。

2. 网关状态检查

openclaw status

输出 Gateway: reachable 即网关运行正常。

3. Web UI对话测试

打开公网控制面板，进入聊天页面，发送测试消息，如 你好，当前使用的是什么模型？ ，收到正常回复即接入成功。

七、常见问题与报错解决方案

1. 报错 Config validation failed: models.providers.openrouter.baseUrl: Invalid input: expected string, received undefined 

• 原因：仅设置了 apiKey ，缺失必填的 baseUrl 配置
• 解决：严格按教程的命令顺序，先执行 baseUrl 配置命令，再配置 apiKey ，或直接用方法二覆盖配置文件。

1. 网关重启失败，服务无响应

• 原因：配置文件JSON语法错误（逗号缺失、引号不匹配）
• 解决：检查 openclaw.json 文件的JSON格式，确保无语法错误，或直接复制教程的完整配置替换。

1. 模型调用报错 model not found 

• 原因：默认模型ID错误，或模型ID格式不对
• 解决：模型ID必须完整，格式为 openrouter/模型完整ID ，可在OpenRouter官网查看模型的完整ID，替换后重启网关。

1. 无法访问公网控制面板

• 原因：端口未正确映射，或公网访问未开启
• 解决：检查Zeabur服务的网络配置，确认 18789 端口已开启公网访问，地址格式正确，Token无误。

1. API Key无效报错

• 原因：密钥复制错误、多了空格/换行，或密钥权限不足、已过期
• 解决：在OpenRouter官网重新生成API Key，确保完整复制，无多余字符，重新配置后重启网关。

八、进阶可选配置

安装常用技能

安装会话日志（便于排查问题）

openclaw skill install session-logs

安装ClawHub技能市场

openclaw skill install clawhub

安装语音转文字（配合模型实现语音交互）

openclaw skill install openai-whisper

设置模型备用

当主模型调用失败时，自动切换到备用模型

openclaw config set agents.defaults.model.fallbacks "openrouter/anthropic/claude-3-haiku:free"

开启Web搜索功能

openclaw configure --section web

按向导提示配置搜索提供商，即可让模型支持联网搜索。

感谢阅读