OpenClaw配置指南

> 环境:Windows 10 / Node v24.19.0 / OpenClaw 2026.7.1-2
---

## 1. 背景说明

- **OpenClaw**(github.com/openclaw/openclaw)是一个开源的个人 AI 助手,运行在你自己的设备上,可以接入 Telegram / WhatsApp / Discord 等聊天渠道。基于 Node.js,MIT 协议。
- **Hermes Agent**(github.com/NousResearch/hermes-agent)是 Nous Research 出品的 AI 代理,也就是你现在正在对话的这个。
- 两者是**完全独立的平行项目**,没有继承关系。它们的共同点是都支持"OpenAI 兼容"的任意 API 端点,所以可以配置成共享同一个模型后端。
- 本机上的模型后端是一个本地代理(relay),监听 `http://127.0.0.1:3456/v1`,提供 OpenAI 兼容接口(模型列表里包含 deepseek-v4-flash-free、DeepSeek-V4-Pro、GLM-5.2 等)。

```
┌──────────┐      ┌──────────────┐      ┌─────────────┐
│  Hermes  │─────▶│  本地代理     │─────▶│  模型服务    │
│ (Python) │      │ 127.0.0.1:3456│      │ (各家 LLM)  │
└──────────┘      └──────────────┘      └─────────────┘
┌──────────┐      ┌──────────────┘
│ OpenClaw │─────▶│  (同一个代理,同一个密钥)
│ (Node.js)│      └
└──────────┘
```

---

## 2. 前置检查

```bash
# 1. 检查 Node 版本(OpenClaw 需要 Node 22.22.3+ / 24.15+ / 25.9+)
node -v          # 本机: v24.19.0 ✓

# 2. 检查 OpenClaw 是否已安装
openclaw --version   # 本机: 2026.7.1-2 (0790d9f)

# 3. 确认本地代理在运行,并拿到可用模型列表
export KEY=$(grep -E '^HERMES_CUSTOM_127_0_0_1_3456_API_KEY=' "$HERMES_HOME/.env" | head -1 | cut -d= -f2-)
curl -s http://127.0.0.1:3456/v1/models -H "Authorization: Bearer $KEY"

# 4. 查看 OpenClaw 配置文件路径(默认 ~/.openclaw/openclaw.json)
openclaw config file
```

> 注意:这里的 `$HERMES_HOME` 是 Hermes 的配置目录(本机为 `C:\Users\fqq13\AppData\Local\hermes`),密钥存在它的 `.env` 文件里。
> 如果本地代理(3456 端口)没在运行,Hermes 和 OpenClaw 都会连不上模型——先把它启动。

---

## 3. 配置步骤

### 3.1 关键知识点:配置是"事务性"写入

`openclaw config set` 每写一步都会对**整份配置**做 schema 校验,任何一步不合法就**整体回滚**。
因此自定义 provider 必须**一次性**把完整对象写进去,不能分字段逐步写。

例如下面这种写法会失败(中间态缺少 baseUrl/models,校验不过):

```bash
# ❌ 错误示范:分步写,中间态校验失败,全部回滚
openclaw config set models.providers.ccr.baseUrl "http://127.0.0.1:3456/v1"
openclaw config set models.providers.ccr.api "openai-completions"
```

### 3.2 一次性注册 provider(正确做法)

```bash
# 从 Hermes 的 .env 取出密钥(不要明文写死在命令里)
export KEY=$(grep -E '^HERMES_CUSTOM_127_0_0_1_3456_API_KEY=' "$HERMES_HOME/.env" | head -1 | cut -d= -f2-)

# 生成完整的 provider JSON(用 python 避免转义问题)
python - "$KEY" <<'EOF'
import json, sys
provider = {
    "baseUrl": "http://127.0.0.1:3456/v1",
    "api": "openai-completions",            # OpenAI 兼容适配器
    "apiKey": sys.argv[1],
    "models": [
        {"id": "OpenCode Public (Chat Completions)/deepseek-v4-flash-free", "name": "DeepSeek V4 Flash Free"},
        {"id": "modelscope/deepseek-ai/DeepSeek-V4-Pro", "name": "DeepSeek V4 Pro"},
        {"id": "modelscope/ZhipuAI/GLM-5.2", "name": "GLM-5.2"},
        {"id": "DeepSeek/deepseek-v4-flash", "name": "DeepSeek V4 Flash"},
        {"id": "modelscope/stepfun-ai/Step-3.7-Flash", "name": "Step-3.7 Flash"}
    ]
}
json.dump(provider, open(r'C:\Users\fqq13\ccr-provider.json', 'w', encoding='utf-8'), ensure_ascii=False)
EOF

# 一次性写入(--strict-json 解析 JSON,--merge 合并进现有配置)
openclaw config set models.providers.ccr --strict-json --merge "$(cat ~/ccr-provider.json)"

# 验证(密钥会被自动打码成 __OPENCLAW_REDACTED__)
openclaw config get models.providers.ccr.baseUrl
openclaw config get models.providers.ccr.apiKey
```

字段说明:

| 字段 | 值 | 说明 |
|---|---|---|
| `models.providers.<id>` | `ccr` | 自定义 provider 的 ID,随便起 |
| `baseUrl` | `http://127.0.0.1:3456/v1` | OpenAI 兼容端点(必须以 /v1 结尾) |
| `api` | `openai-completions` | 适配器类型,OpenAI 兼容接口用这个 |
| `apiKey` | `sk-ccr-...` | 代理的密钥(自动打码显示) |
| `models[]` | id + name | 模型清单,id 必须是代理 /v1/models 里真实存在的 ID |

### 3.3 设置默认模型

```bash
openclaw models set "ccr/OpenCode Public (Chat Completions)/deepseek-v4-flash-free"
```

> 模型引用格式是 `provider/模型ID`(按第一个 `/` 切分)。模型 ID 里自带 `/` 也没关系,
> 例如 `ccr/modelscope/deepseek-ai/DeepSeek-V4-Pro` 会被解析为 provider=`ccr` + 模型=`modelscope/deepseek-ai/DeepSeek-V4-Pro`。

### 3.4 校验配置

```bash
openclaw config validate
# 输出: Config valid: ~\.openclaw\openclaw.json
```

### 3.5 真实调用验证

```bash
openclaw agent --local --agent main -m "用一句话介绍你自己"
```

看到模型正常回复即成功。日志里能看到完整链路:

```
[provider-transport-fetch] [model-fetch] start provider=ccr api=openai-completions
  model=OpenCode Public (Chat Completions)/deepseek-v4-flash-free
  method=POST url=http://127.0.0.1:3456/v1/chat/completions
[provider-transport-fetch] [model-fetch] response ... status=200
```

---

## 4. 日常使用

### 4.1 交互式聊天(本地 TUI)

```bash
openclaw chat
```

终端里直接开聊,支持斜杠命令(如 `/model` 切换模型)。不需要网关。

### 4.2 一句话问答(脚本友好)

```bash
openclaw agent --local --agent main -m "你的问题"
```

> 必须指定会话:`--agent main` 或 `--session-key agent:main:xxx`,否则会报
> `Pass --to <E.164>, --session-key, --session-id, or --agent to choose a session`。

### 4.3 模型管理

```bash
openclaw models status          # 当前默认模型 + 认证状态
openclaw models list            # 列出可用模型
openclaw models set "ccr/modelscope/deepseek-ai/DeepSeek-V4-Pro"    # 切换模型
openclaw models fallbacks add "ccr/modelscope/deepseek-ai/DeepSeek-V4-Pro"   # 加兜底模型
```

### 4.4 接入聊天平台(Telegram / WhatsApp / Discord ...)

```bash
openclaw gateway start                  # 启动网关(默认没启动)
openclaw configure --section channels   # 交互式添加渠道
openclaw doctor                         # 健康检查
```

### 4.5 其他有用命令

```bash
openclaw config file        # 配置文件路径
openclaw config get <path>  # 读配置(密钥自动打码)
openclaw config validate    # 校验配置
openclaw backup create      # 备份状态
openclaw doctor             # 健康检查 + 修复
```

---

## 5. 踩过的坑(FAQ)

1. **`config set` 分步写会回滚**
   自定义 provider 必须一次性完整写入(见 3.1/3.2)。报错示例:
   `custom model providers must declare baseUrl` / `must declare models`。

2. **首次运行报 `No API key found for provider "openai"`**
   那是没配置任何 provider 时的默认行为(它默认找 openai/gpt-5.5 的密钥)。配置好 ccr 并 `models set` 后就解决了。

3. **`openclaw agent` 报 session 错误**
   需要显式传 `--agent main` 或 `--session-key`。

4. **git-bash 的 `/tmp` 路径 Windows 原生 Python 不认**
   临时文件请写到 `~/` 或 Windows 可见路径。

5. **本地代理必须保持运行**
   3456 端口的代理进程(Hermes 也在用)不能关,否则 OpenClaw 无法调用模型。
   检查:`netstat -ano | grep 3456`,应看到 LISTENING。

---

## 6. 当前配置快照

```json
{
  "models": {
    "providers": {
      "ccr": {
        "baseUrl": "http://127.0.0.1:3456/v1",
        "api": "openai-completions",
        "apiKey": "(已打码 sk-ccr-...)",
        "models": [
          { "id": "OpenCode Public (Chat Completions)/deepseek-v4-flash-free", "name": "DeepSeek V4 Flash Free" },
          { "id": "modelscope/deepseek-ai/DeepSeek-V4-Pro", "name": "DeepSeek V4 Pro" },
          { "id": "modelscope/ZhipuAI/GLM-5.2", "name": "GLM-5.2" },
          { "id": "DeepSeek/deepseek-v4-flash", "name": "DeepSeek V4 Flash" },
          { "id": "modelscope/stepfun-ai/Step-3.7-Flash", "name": "Step-3.7 Flash" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "ccr/OpenCode Public (Chat Completions)/deepseek-v4-flash-free" }
    }
  }
}
```

配置文件:`C:\Users\fqq13\.openclaw\openclaw.json`(每次修改自动生成 `.bak` 备份)
认证状态:`openclaw models status` 可查,密钥存储在 `~\.openclaw\agents\main\agent\models.json`。

---

## 7. 扩展:添加更多模型

```bash
# 1. 查代理上有哪些模型可用
export KEY=$(grep -E '^HERMES_CUSTOM_127_0_0_1_3456_API_KEY=' "$HERMES_HOME/.env" | head -1 | cut -d= -f2-)
curl -s http://127.0.0.1:3456/v1/models -H "Authorization: Bearer $KEY" | python -m json.tool

# 2. 把想要的模型 id 加进 providers.ccr.models 数组(整体重写,保持原子性)
# 3. openclaw models set "ccr/<模型ID>" 切换过去
```