一、环境准备

1.1 检查前置依赖

打开 PowerShell（普通用户权限即可），执行以下命令检查环境：

1
2
3
4
# 检查 Node.js 版本（要求 ≥ 20.0.0）
node -v
# 检查 npm 版本
npm -v
  • 如果提示 node: command not found：去 Node.js 官网 下载 LTS 版本安装，默认下一步即可。
  • 安装完成后重启 PowerShell，再次检查版本。

1.2 安装 OpenClaw-CN

执行以下通用安装命令（国内镜像，稳定可靠）：

1
2
3
4
5
# 1. 切换 npm 国内镜像（解决下载慢/超时）
npm config set registry https://registry.npmmirror.com

# 2. 全局安装 OpenClaw-CN
npm install -g openclaw-cn@latest

1.3 验证安装成功

1
openclaw-cn --version

✅ 成功标志：输出类似 openclaw-cn/0.1.8-fix.3 的版本号。

❌ 失败处理：

  • 提示 command not found：把 C:\Users\你的用户名\AppData\Roaming\npm 加入系统环境变量 PATH，重启 PowerShell。
  • 权限错误：用管理员权限打开 PowerShell 重新执行安装命令。

二、基础配置（核心流程，必做）

2.1 初始化配置（交互式向导，通用无坑）

执行以下命令，进入交互式配置向导（所有版本通用，无参数坑）：

1
openclaw-cn configure

按提示一步步操作：

  1. 检测到现有配置：直接回车（保留现有配置，或选择更新）。
  2. 网关将在哪里运行？：选择「本地（此设备）」→ 回车。
  3. 选择要配置的部分：选择「模型」→ 回车。
  4. 模型 / 认证提供商：用上下键选择你要使用的模型（如 Moonshot AI (Kimi K2.5)）→ 回车。
  5. 认证方法：选择对应 API Key 方式（如 Kimi API key (.cn)）→ 回车。
  6. 输入 API Key：粘贴你在对应平台创建的 Key（如 Kimi 的 sk-xxx）→ 回车。
  7. 选择模型：默认推荐模型（如 moonshot/kimi-k2.5）→ 一路回车完成配置。

2.2 启动网关（基础运行模式）

方式 1：前台运行（调试 / 新手首选，看实时日志）

1
openclaw-cn gateway

✅ 成功标志：日志输出 Gateway ready on ws://127.0.0.1:18789，且持续运行。

  • 关闭终端即停止网关，适合调试。

方式 2：后台运行（长期使用）

1
2
3
4
5
6
7
8
9
10
11
# 启动后台网关
openclaw-cn gateway start

# 查看网关状态
openclaw-cn gateway status

# 停止网关
openclaw-cn gateway stop

# 重启网关（修改配置后必执行）
openclaw-cn gateway restart

2.3 访问 Web 控制台

  1. 打开浏览器，访问：http://127.0.0.1:18789（或带 Token 的链接 http://127.0.0.1:18789/?token=你的网关Token）。

  2. 进入「对话」页面，发送测试指令：

    1
    你好，帮我写一行 Python 代码打印 Hello World

✅ 成功标志：AI 正常返回代码，且 Kimi 平台计费明细显示少量消耗。

三、核心问题排查（90% 问题速解）

3.1 网关无法启动

问题 原因 解决方案
listen EADDRINUSE 18789 端口被占用 执行 netstat -anofindstr :18789找到占用进程 PID，执行taskkill /F/PID 进程 ID 杀死进程，重新启动网关。
启动后无响应 配置文件损坏 执行 openclaw-cn configure 重新走一遍配置向导，或 openclaw-cn setup --reset config 重置配置。
模型调用失败 API Key 错误 / 网络 重新执行 openclaw-cn configure 核对 API Key；检查网络是否能访问对应模型平台（如 Kimi 国内直连，无需科学上网）。

3.2 Web 控制台无法访问

  • 确认网关正在运行：openclaw-cn gateway status。
  • 确认访问地址是 127.0.0.1:18789（不要用 localhost 或外网 IP）。
  • 检查防火墙是否允许 18789 端口访问（默认允许，若被拦截需手动放行）。

3.3 命令参数错误（如 unknown option '--provider'）

  • 原因：当前版本不支持该参数，所有版本通用的写法是直接运行 openclaw-cn configure，用交互式向导配置，不要加任何额外参数。

  • 正确操作

    1
    2
    # 永远用这个命令配置，无参数坑
    openclaw-cn configure

四、拓展内容（进阶可选）

4.1 安全文件夹：限制 OpenClaw 仅在指定目录干活（可选）

操作步骤：

  1. 创建安全文件夹：C:\Users\你的用户名\Claw_Safe_Workspace。
  2. 执行配置向导，选择「工作区」→ 输入安全文件夹路径 → 回车。
  3. 重启网关：openclaw-cn gateway restart。
  4. 验证：让 OpenClaw 尝试访问 C:\Windows 目录，会被拒绝访问，仅能在安全文件夹内操作。

4.2 多模型 API 配置（可选，成本优化）

基础方法（通用）：

  1. 执行 openclaw-cn configure，选择「模型」→ 切换到其他模型（如 deepseek），输入对应 API Key。
  2. 重启网关后，在对话中用 [使用Kimi]/[使用DeepSeek] 前缀指定模型。

进阶：自动路由规则（高版本支持）

编辑配置文件 %USERPROFILE%\.openclaw\router.yaml，定义任务 - 模型映射，重启网关后自动分工。

4.3 本地免费模型：Ollama 集成（可选，永久 0 成本）

操作步骤：

  1. 安装 Ollama：winget install Ollama.Ollama。
  2. 拉取模型：ollama pull deepseek-r1:7b。
  3. 执行 openclaw-cn configure，选择「Ollama」→ API Key 填 ollama → 模型填 deepseek-r1:7b → 回车。
  4. 重启网关，即可用本地模型免费干活。