OpenClaw部署教程

OpenClaw 部署与配置核心手册

一、环境准备

  • 操作系统：Windows 10/11（建议使用 WSL2 以获得更好兼容性）
  • Node.js：版本 ≥ 22（必选）
node --version # 检查版本
  • 权限：以管理员身份运行 PowerShell

二、安装 OpenClaw

一键安装脚本

iwr -useb https://openclaw.ai/install.ps1 | iex
  • 安装后关闭并重新打开 PowerShell，使命令生效
  • 验证安装：
openclaw --version //有时候会提示版本更新，尽可能保证最新版本

三、初始化配置向导

运行向导并安装服务

openclaw onboard --install-daemon

关键选项

步骤 选择 说明
安全警告 Yes 确认了解风险
配置模式 QuickStart 快速生成基础配置
模型提供商 Skip for now 稍后手动添加硅基流动
通信渠道 Skip for now 暂不配置聊天平台
技能配置 No 暂不启用扩展技能
钩子 至少选一个（如 boot-md） 界面要求至少一项
Gateway 服务 Restart 应用配置并重启

四、手动添加硅基流动模型

配置文件位置

OpenClaw 使用两个核心配置文件：

  • 主配置文件：C:\Users\<用户名>\.openclaw\openclaw.json
  • 认证文件：C:\Users\<用户名>\.openclaw\agents\main\agent\auth-profiles.json

1. 编辑 openclaw.json

添加 models 块（注意 JSON 格式，前后加逗号）：

"models": {
"providers": {
"siliconflow": {
"baseUrl": "https://api.siliconflow.cn/v1",
"apiKey": "你的真实硅基流动 API 密钥",
"api": "openai-completions",
"models": [
{"id": "deepseek-ai/DeepSeek-V3.2",//这里以deepseek为例，可以替换为自己目标模型
"name": "DeepSeek-V3.2"
},
// 如有 Pro 版
{"id": "Pro/deepseek-ai/DeepSeek-V3.2",
"name": "DeepSeek-V3.2 Pro"
}]
}}},

同时确保 agents.defaults.model.primary 设置为正确的模型 ID（含提供商前缀）：

"agents": {
"defaults": {
"model": {
"primary": "siliconflow/deepseek-ai/DeepSeek-V3.2" // 或 siliconflow/Pro/...
}}}```

### 2. 编辑 `auth-profiles.json`
确保文件内容只包含需要使用的提供商密钥：
```json
{"siliconflow": {
"apiKey": "你的真实硅基流动 API 密钥"
}}```
删除其他无关的 provider（如 `anthropic`、`google` 等）。

## 五、服务管理常用命令
| 命令 | 说明 |
|------|------|
| `openclaw gateway start` | 后台启动 Gateway 服务 |
| `openclaw gateway stop` | 停止服务 |
| `openclaw gateway restart` | 重启服务 |
| `openclaw gateway run` | 前台运行（调试用，Ctrl+C 停止） |
| `openclaw gateway status` | 查看服务状态（应显示 `RPC probe: ok`） |
| `openclaw status` | 查看整体运行状态 |
| `openclaw models list` | 列出已加载模型 |
| `openclaw logs --follow` | 实时查看日志 |
| `openclaw doctor` | 运行诊断 |
| `openclaw doctor --fix` | 自动修复常见问题 |
| `openclaw dashboard` | 打开 Web 操作界面 |

## 六、常见问题与解决
### 1. 端口占用（`Port 18789 is already in use`）
```powershell
netstat -ano | findstr :18789
taskkill /PID <进程ID> /F
openclaw gateway restart

2. 令牌不匹配（unauthorized: gateway token mismatch）

# 获取当前令牌
openclaw config get gateway.auth.token
# 设置 remote.token 为相同值
openclaw config set gateway.remote.token "令牌值"
openclaw gateway restart

或直接运行 openclaw doctor --fix 自动修复。

3. 模型显示 missing 标签

  • 确认 openclaw.json 中已添加 models.providers 配置
  • 确认 auth-profiles.json 中包含对应提供商密钥且格式正确
  • 重启 Gateway
  • 如果仍显示，可忽略，只要 openclaw gateway run 日志中 agent model 正确加载即可

4. 添加了 Pro 模型但提示 Unknown model

  • 检查模型 ID 是否与 models.providers.siliconflow.models 中定义的 id 完全一致
  • 硅基流动上 Pro 版的正确 ID 可能是 Pro/deepseek-ai/DeepSeek-V3.2，以官方文档为准

5. 配置文件修改后未生效

  • 确保修改的是 openclaw.json，而非 config.yaml（OpenClaw 优先读取前者）
  • 修改后必须重启 Gateway：openclaw gateway restart

6. Windows 原生环境兼容性问题

如果反复遇到奇怪错误，建议安装 WSL2 并在 Linux 环境中运行 OpenClaw：

wsl --install # 安装 WSL2
# 重启后在 WSL 中安装 OpenClaw

七、核心配置示例（完整 openclaw.json 结构）

{"meta": { ... }, // 自动生成，勿动
"wizard": { ... }, // 自动生成，勿动
"agents": {
"defaults": {
"model": {
"primary": "siliconflow/deepseek-ai/DeepSeek-V3.2"
},
"workspace": "C:\\Users\\<用户名>\\.openclaw\\workspace",
"memorySearch": {
"enabled": false
}}},
"models": {
"providers": {
"siliconflow": {
"baseUrl": "https://api.siliconflow.cn/v1",
"apiKey": "sk-xxxxxxxxxx",
"api": "openai-completions",
"models": [
{"id": "deepseek-ai/DeepSeek-V3.2",
"name": "DeepSeek-V3.2"
}]
}}},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"auth": {
"mode": "token",
"token": "xxxx" //三、初始化配置向导 会生成
},
"remote": {
"token": "xxx"
}}}

八、验证成功标志

  • 运行 openclaw gateway run 后看到 listening on ws://127.0.0.1:18789
  • openclaw gateway status 显示 RPC probe: ok
  • openclaw models list 中目标模型存在（即使有 missing 标签也无妨，只要 gateway run 日志中 agent model 正确即可）
  • 打开 openclaw dashboard 能正常对话，模型正确回复