My Docs

Appearance

OpenClaw 配置教程 ​

OpenClaw 是什么？ ​

OpenClaw 是一个功能强大的 AI Agent 系统，专为开发者设计。它比 OpenCode 更强大，支持更复杂的任务和更高级的定制。

适合人群：

  • 有一定编程经验的开发者
  • 需要高度定制化 AI Agent 的用户
  • 愿意花时间配置复杂系统的高级用户

不适合人群：

官方网站：https://openclaw.ai/

前置要求（重要！） ​

在开始之前，请确保：

  • ✅ 已获取 Codex API Key（参考 快速上手教程）
  • ✅ 已安装 Node.js 22 或更高版本（注意：必须是 22+，不是 16+）
  • ✅ 熟悉命令行操作
  • ✅ 了解 JSON 配置文件格式
  • ✅ （Windows 用户）建议使用 WSL2（Windows Subsystem for Linux）

检查 Node.js 版本 ​

在终端运行：

bash
node --version

如果版本低于 22，请访问 https://nodejs.org/ 下载最新版本。

什么是 WSL2？（Windows 用户必读） ​

WSL2 是 Windows 的 Linux 子系统，可以让你在 Windows 上运行 Linux 环境。

为什么推荐 WSL2？

  • OpenClaw 在 Linux 环境下更稳定
  • 避免 Windows 路径和权限问题
  • 配置更简单

如何安装 WSL2？

  1. 以管理员身份打开 PowerShell
  2. 运行：wsl --install
  3. 重启电脑
  4. 安装完成后，在 WSL2 中继续配置 OpenClaw

不想用 WSL2？ 也可以直接在 Windows 上配置，但可能会遇到更多问题。

第一步：安装 OpenClaw ​

macOS / Linux / WSL2 用户 ​

运行一键安装脚本：

bash
curl -fsSL https://openclaw.ai/install.sh | bash

Windows 用户（不使用 WSL2） ​

在 PowerShell 中运行：

powershell
iwr -useb https://openclaw.ai/install.ps1 | iex

验证安装 ​

安装完成后，运行以下命令检查：

bash
openclaw --version      # 查看版本
openclaw doctor         # 检查系统状态
openclaw status         # 查看运行状态
openclaw dashboard      # 打开控制面板

如果所有命令都能正常运行，说明安装成功！

第二步：准备配置文件 ​

配置文件位置 ​

OpenClaw 的配置文件名为 openclaw.json。

推荐放置位置（这样升级/重装不会丢失配置）：

  • Linux / macOS / WSL2：~/.openclaw/openclaw.json
  • Windows（不使用 WSL2）：C:\Users\你的用户名\.openclaw\openclaw.json

注意：

  • ~ 代表你的用户主目录（Home 目录）
  • Windows 的用户主目录通常是 C:\Users\你的用户名

使用环境变量指定配置文件（可选） ​

如果你想把配置文件放在其他位置，可以设置环境变量：

PowerShell（Windows）：

powershell
$env:OPENCLAW_CONFIG_PATH = “C:\path\to\openclaw.json”
openclaw doctor

Bash（Linux / macOS / WSL2）：

bash
export OPENCLAW_CONFIG_PATH=”/path/to/openclaw.json”
openclaw doctor

第三步：配置 openclaw.json ​

下载配置文件模板 ​

关键配置项说明 ​

OpenClaw 的配置文件比较复杂，以下是必须正确配置的关键项：

1. API 类型（必须） ​

json
“api”: “openai-responses”

说明：必须使用 openai-responses 格式，不能用其他格式。

2. 认证方式（必须） ​

json
“auth”: “api-key”

说明：必须设置为 api-key，否则鉴权会失败。

3. 推理模式（推荐） ​

json
“reasoning”: true

说明：启用推理模式，让模型能够进行深度思考。对于 gpt-5.3-codex 等高级模型建议开启。

完整配置示例 ​

下面是一个完整的配置示例（可以直接使用）：

json
{
  “models”: {
    “mode”: “merge”,
    “providers”: {
      “codex-vip”: {
        “baseUrl”: “https://api-vip.codex-for.me/v1”,
        “apiKey”: “你的API Key”,
        “auth”: “api-key”,
        “api”: “openai-responses”,
        “models”: [
          {
            “id”: “gpt-5.3-codex”,
            “name”: “GPT 5.3 Codex”,
            “api”: “openai-responses”,
            “reasoning”: true,
            “input”: [“text”, “image”],
            “contextWindow”: 200000,
            “maxTokens”: 8192
          },
          {
            “id”: “gpt-5.2”,
            “name”: “GPT-5.2”,
            “api”: “openai-responses”,
            “reasoning”: false,
            “input”: [“text”]
          }
        ]
      }
    }
  },
  “agents”: {
    “defaults”: {
      “model”: {
        “primary”: “codex-vip/gpt-5.3-codex”
      }
    }
  }
}

配置步骤 ​

  1. 创建配置目录

    Linux / macOS / WSL2：

    bash
    mkdir -p ~/.openclaw

    Windows PowerShell：

    powershell
    New-Item -ItemType Directory -Force -Path “$env:USERPROFILE\.openclaw”

  2. 保存配置文件

    将上面的配置示例保存为 openclaw.json，放到配置目录中。

  3. 修改 API Key

    用文本编辑器打开 openclaw.json，找到：

    json
    “apiKey”: “你的API Key”

    替换成你在 快速上手教程 中获取的真实 API Key。

  4. 检查配置

    运行：

    bash
    openclaw doctor

    如果提示配置正确，说明配置成功！

第四步：开始使用 ​

配置完成后，运行：

bash
openclaw

OpenClaw 会启动，你可以开始使用了！

常用命令 ​

bash
openclaw                # 启动 OpenClaw
openclaw --help         # 查看帮助
openclaw doctor         # 检查配置和系统状态
openclaw status         # 查看运行状态
openclaw dashboard      # 打开控制面板

配置遇到问题？使用 Codex 自动配置 ​

如果你在配置 OpenClaw 时遇到困难（Node 版本、权限、路径等问题），可以使用 Codex CLI 来帮你自动配置。

前提条件 ​

操作步骤 ​

  1. 启动 Codex CLI

    bash
    codex

  2. 让 AI 帮你配置

    在 Codex 中输入：

    请把用户目录下 .codex 的 API 配置写入 openclaw.json，注意使用 openai-responses 格式，并且要设置 auth 为 api-key，reasoning 为 true。

  3. 验证配置

    AI 完成配置后，运行：

    bash
    openclaw doctor

常见问题 ​

Q: 我的 Node.js 版本是 16/18/20，可以用吗？ ​

A: 不可以，OpenClaw 必须使用 Node.js 22 或更高版本。请升级 Node.js。

Q: 什么是用户主目录？ ​

A:

  • Windows：C:\Users\你的用户名
  • macOS：/Users/你的用户名
  • Linux：/home/你的用户名
  • 在命令行中用 ~ 代表

Q: 配置文件格式错误怎么办？ ​

A:

  1. 确保是有效的 JSON 格式（可以用 JSON 验证工具检查）
  2. 注意逗号、引号、括号是否匹配
  3. 可以重新下载配置文件模板

Q: 提示找不到配置文件？ ​

A:

  1. 检查文件路径是否正确
  2. 检查文件名是否为 openclaw.json（不是 .txt 或其他）
  3. 尝试使用环境变量 OPENCLAW_CONFIG_PATH 明确指定路径

Q: gateway.auth.token 是什么？ ​

A: 这是网关鉴权令牌，如果你没有启用网关功能，可以忽略。如果启用了，需要在配置文件中设置，不要使用示例值。

Q: OpenClaw 和 OpenCode 有什么区别？ ​

A:

  • OpenCode：更简单，适合日常使用，配置容易
  • OpenClaw：更强大，功能更多，但配置复杂，需要 Node.js 22+

新手建议先用 OpenCode，熟悉后再尝试 OpenClaw。

配置检查清单 ​

在开始使用前，请确认：

  • [ ] Node.js 版本 ≥ 22
  • [ ] OpenClaw 已成功安装（openclaw --version 能运行）
  • [ ] 配置文件已放在正确位置
  • [ ] api 设置为 ”openai-responses”
  • [ ] auth 设置为 ”api-key”
  • [ ] apiKey 已替换为真实的 API Key
  • [ ] 高级模型的 reasoning 设置为 true
  • [ ] openclaw doctor 检查通过

更多资源 ​