# 给配置助手的任务

我是新手，正在 Windows 上配置 OpenClaw，使用 Vmvia API。请先阅读这份教程：https://doc.vmvia.com/simple/openclaw-windows

请先确认我已经安装了什么、进行到哪一步。每次只指导一个步骤，写清楚在哪里操作、填什么、成功后会看到什么，等我反馈再继续。遇到错误先根据教程排查，不要猜测不存在的模型、分组或界面选项。已有配置先备份并只合并必要字段。API Key 用 sk-xxx 占位，由我在本机填写。

如果无法读取链接，请明确告诉我，让我粘贴完整教程。你没有本机操作能力时，请指导我执行，不要声称已经替我修改成功。

---

# OpenClaw · Windows 配置教程

先完成一步，再继续下一步。已经完成的安装步骤可以跳过。

> 配置资料核对日期：2026-09-28。分组和模型可能调整，当前可用情况以 [Vmvia 模型广场](https://www.vmvia.com/pricing) 为准。

## 这份教程会帮你完成什么

安装并连接 Vmvia API，最后发送一条消息确认可以使用。所有 API Key 示例都是占位值 `sk-xxx`，实际 Key 只在你自己的软件中填写。

| 要填写的内容 | 本教程使用的值 |
| --- | --- |
| 工具 | OpenClaw |
| 系统 | Windows（OpenClaw 在 WSL2 / Ubuntu 内运行） |
| 令牌分组 | `codex`（倍率 0.2x） |
| Base URL | `https://www.vmvia.com/v1` |
| 模型 | `gpt-5.6-sol` |

## 1. 安装并打开工具

OpenClaw 在本教程中使用 **WSL2 / Ubuntu**。如果还没有 WSL，以管理员身份打开 PowerShell，执行下面的命令，按提示完成安装或重启：

```powershell
wsl --install
```

之后从开始菜单打开 Ubuntu，完成首次用户名和密码设置。后续 OpenClaw 命令都在 **Ubuntu 终端**执行。

从 [Node.js 官网](https://nodejs.org/en/download) 安装当前 LTS 版本，选择 Linux / Ubuntu 安装方式，在 WSL 内安装。重新打开终端并检查：

```bash
node -v
npm -v
```

然后安装 OpenClaw：

```bash
npm install -g openclaw@latest
openclaw --version
```

**完成标志**：版本检查能显示版本号，没有「找不到命令」的提示。

## 2. 准备 Vmvia API Key

**先看模型广场，再创建密钥。** 打开 [Vmvia 模型广场](https://www.vmvia.com/pricing)，用左侧「分组」筛选 `codex`，确认它当前支持的模型；后面填写 `model` 时，直接复制模型卡片上的完整名称，避免写错模型导致调用失败。

1. 登录 [Vmvia 控制台](https://www.vmvia.com/console/token)，进入「令牌」页面。
2. 新建或编辑一个令牌，分组选择 `codex`。**不要选 `default`**，该分组没有可用模型。
3. **关闭「模型限制」**，限制可调用模型有时会引发未知异常。
4. 保存并复制 API Key，稍后填入本机的软件。

本教程使用 `codex` 分组（倍率 0.2x）。如果更看重稳定性，可以选 `codex-wending`（倍率 0.35x），两者可用模型相同。主模型选 `gpt-5.6-sol`；`gpt-6-astra`、`gpt-6-sol` 也在该分组内，可按需切换。

**完成标志**：手中有一个 `codex` 分组的 API Key，令牌的模型限制已关闭。

## 3. 初始化 OpenClaw

在终端中执行：

```bash
openclaw onboard --install-daemon
```

1. 选择 QuickStart，按引导完成本机网关初始化。
2. 供应商尚未配置时先跳过，下一步接入 Vmvia。
3. 先完成本地网关配置，再根据需要添加飞书或其他通知渠道。
4. 如果引导展示了本地控制台地址，使用它打开页面；默认端口是 `18789`。

**完成标志**：初始化完成，本机已生成 OpenClaw 配置文件。

## 4. 填入 Vmvia 连接配置

打开 `~/.openclaw/openclaw.json`。先备份文件，再把下面的 `agents.defaults.model` 和 `models.providers` 字段合并到现有 JSON 中。**保留已有 gateway、channels 和认证配置。**

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "vmvia-codex/gpt-5.6-sol"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "vmvia-codex": {
        "api": "openai-responses",
        "apiKey": "sk-xxx",
        "baseUrl": "https://www.vmvia.com/v1",
        "headers": {
          "Authorization": "Bearer sk-xxx",
          "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal"
        },
        "models": [
          {
            "id": "gpt-5.6-sol",
            "name": "gpt-5.6-sol"
          }
        ]
      }
    }
  }
}
```

把两处 `sk-xxx` 都替换成自己的同一个 Vmvia API Key。

`User-Agent` 是外接调用必需的请求头，按示例保留；缺少它可能出现 `403 block`。

保存后执行：

```bash
openclaw gateway restart
```

**完成标志**：网关能够重新启动，模型指向 Vmvia Codex provider。

## 5. 发一条消息验证

执行下面的命令打开控制台，再在聊天页面发送：**请只回复「配置成功」**。

```bash
openclaw dashboard
```

**完成标志**：收到正常回复，没有 API Key 无效、模型不可用或连接失败的报错。

## 没成功时，先看这里

| 你看到的现象 | 先做什么 |
| --- | --- |
| 找不到命令 | 关闭并重新打开终端，再检查版本；Windows 下确认打开的是本教程指定的终端。 |
| API Key 无效 / 401 | 检查 Key 是否复制完整、是否过期，确认已启用正确的 Vmvia 配置。不要把完整 Key 发到聊天里。 |
| 模型不可用 | 检查令牌分组、模型名称和模型限制；以本教程的配置表和模型广场为准。 |
| 403 block | 确认保留了本教程的 User-Agent 请求头。 |
| 连接失败 / 一直等待 | 换一个可用网络，检查代理；主站不通时把地址换成国内优化线路 `https://api.vmvia.com`。记录完整错误文字，不要同时修改多个设置。 |

## 配好了，接下来

可以开始使用，也可以进入 [OpenClaw 详细手册](https://doc.vmvia.com/openclaw) 查看更多配置。后续报错请保留错误原文、系统和工具版本，按 [报错手册](https://doc.vmvia.com/errors) 排查。