← 返回博客

OpenClaw Windows 安装与配置：从零到精通的完整操作手册

AI OpenClaw Windows 效率工具 配置教程 自动化办公

这是一份 Windows 环境下 OpenClaw 的完整操作手册，从系统要求到高级配置，从一键安装到多 Agent 路由，一站式覆盖。

一、环境准备

1.1 系统要求

项目要求说明
操作系统Windows 10/11 或 Windows Server 2019+支持 x64 和 ARM64
内存≥ 4GB RAM推荐 8GB+，本地模型需 16GB+
磁盘≥ 2GB 可用空间含 Node.js + OpenClaw + 工作区
网络可访问外网模型 API 调用需要网络（本地模型除外）
终端PowerShell 5.1+ / PowerShell 7+推荐 Windows Terminal
浏览器Edge / Chrome / Brave浏览器工具需要 Chromium 内核

WSL2 可选： Windows 上同时支持原生 Windows 和 WSL2 两种模式。WSL2 运行更稳定（尤其 WhatsApp/Telegram 通道和 Docker 沙箱），但原生 Windows 已完全可用。本文以 原生 Windows 为主。

1.2 安装 Node.js

OpenClaw 基于 Node.js 运行，推荐 Node.js 24（Node 22.19+ 也支持）。

方法 A：使用官方安装包

访问 nodejs.org，下载 Windows 安装包（.msi），按向导完成安装。

方法 B：使用 winget（推荐）

winget install OpenJS.NodeJS.LTS

方法 C：使用 Scoop

scoop install nodejs

验证安装：

node --version
# 应输出类似: v22.22.2 或 v24.x.x

npm --version
# 应输出类似: 10.x.x

注意： 如果 node 命令找不到，请确认已加入 PATH。关闭并重新打开 PowerShell 终端后再试。

1.3 安装 Git（可选）

Git 不是必需的，但推荐安装——技能管理、源码安装和版本控制都需要它。

winget install Git.Git
git --version
# git version 2.x.x.windows.x

二、安装 OpenClaw

2.1 PowerShell 一键安装

这是 最简单 的方式，自动安装所有依赖：

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

安装脚本会自动检查 Node.js、使用 npm 全局安装 OpenClaw、创建基础目录结构，并提示运行 onboarding。

2.2 npm 手动安装

如果一键安装遇到问题，可以手动安装：

npm install -g openclaw

如需使用开发版本：

npm install -g openclaw@beta

2.3 验证安装

openclaw --version
# 2026.x.x

openclaw status
# 显示当前运行状态

安装目录： Windows 上 OpenClaw 的数据默认存放在 %USERPROFILE%\.openclaw\ 目录（即 C:\Users\你的用户名\.openclaw\）。

三、初始化引导（Onboarding）

安装完成后，需要运行 onboarding 进行首次配置：

openclaw onboard --install-daemon

向导会依次引导你完成：

① 选择模型提供商 → ② 输入 API Key → ③ 配置 Gateway → ④ 设置工作区 → ⑤ 可选：配置通道

完成后 Gateway 自动启动，可访问 http://127.0.0.1:18789 打开 Control UI 仪表盘。

跳过引导： 如果只想创建基础配置而不走完整流程，可以用 openclaw setup 代替 openclaw onboard。

四、openclaw.json 配置文件详解

4.1 文件位置与格式

配置文件路径：

%USERPROFILE%\.openclaw\openclaw.json
# 例如: C:\Users\TheDoctor\.openclaw\openclaw.json

环境变量 OPENCLAW_CONFIG_PATH 可指向自定义路径。

  • 使用 JSON5 格式——支持注释（// 和 /* */）、尾逗号
  • 普通 JSON 格式也完全兼容
  • 文件保存后 Gateway 会 自动热重载，无需重启（大部分字段）

严格校验： OpenClaw 对配置进行严格 schema 校验。任何未知字段或类型错误都会导致 Gateway 拒绝启动。只有 $schema 根键是例外。

4.2 配置树形结构

C:\Users\用户名\.openclaw\
├── openclaw.json          ← 主配置文件
├── .env                   ← 环境变量文件（可选）
├── workspace\             ← Agent 工作区
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── MEMORY.md
│   └── memory\
├── agents\                ← Agent 数据
│   └── default\
│       ├── auth-profiles.json ← 认证密钥存储
│       └── sessions\          ← 会话记录
├── skills\                ← 已安装的技能
├── extensions\            ← 插件扩展
├── sessions\              ← 全局会话数据
├── cron\                  ← 定时任务数据
└── logs\                  ← 日志文件

4.3 顶级配置区块

区块用途热重载
gateway网关服务（端口、绑定地址、认证、TLS）需重启
agentsAgent 配置（模型、工作区、心跳、技能、沙箱）✅ 热加载
models模型提供商定义（自定义 API、base URL、模型列表）✅ 热加载
channels消息通道（WhatsApp、Telegram、Discord 等）✅ 热加载
tools工具权限（允许/禁止的工具列表、执行策略）✅ 热加载
env内联环境变量（API Key 等）✅ 热加载
auth认证配置（API Key 认证档案、顺序、退避）✅ 热加载
cron定时任务系统✅ 热加载
skills技能管理（加载目录、安装偏好、独立配置）✅ 热加载
hooksWebhook 端点与映射✅ 热加载
logging日志级别、输出格式、文件路径✅ 热加载
session会话生命周期（范围、重置、维护）✅ 热加载
mcpMCP 服务器定义✅ 热加载
plugins插件系统（加载、启用、配置）需重启
browser浏览器自动化控制✅ 热加载
uiControl UI 外观（主题色、名称、头像）✅ 热加载
messages消息格式化、投递策略、队列管理✅ 热加载
discovery局域网发现（mDNS / DNS-SD）需重启
acpACP 运行时配置✅ 热加载
update自动更新配置✅ 热加载
secrets安全凭证提供者配置✅ 热加载

五、核心配置项逐条解析

5.1 gateway — 网关服务

Gateway 是 OpenClaw 的核心服务进程，负责 WebSocket/HTTP 通信、通道管理、工具调用路由。

{
  "gateway": {
    // 运行模式："local"（本地运行）或 "remote"（连接远程网关）
    "mode": "local",

    // 监听端口，默认 18789
    "port": 18789,

    // 网络绑定方式：
    // "loopback" — 仅本机访问（127.0.0.1），最安全（默认）
    // "lan"      — 监听所有网卡（0.0.0.0），局域网可访问
    // "tailnet"  — 仅 Tailscale 网络
    // "custom"   — 自定义地址（配合 customBindHost）
    "bind": "loopback",

    // 认证配置
    "auth": {
      // 认证模式："none" | "token" | "password" | "trusted-proxy"
      "mode": "token",
      "token": "your-secure-token",
      "allowTailscale": true,

      // 防暴力破解限速
      "rateLimit": {
        "maxAttempts": 10,
        "windowMs": 60000,
        "lockoutMs": 300000,
        "exemptLoopback": true
      }
    },

    // Tailscale 集成
    "tailscale": {
      "mode": "off",  // "off" | "serve" | "funnel"
      "resetOnExit": false
    },

    // Control UI 仪表盘
    "controlUi": {
      "enabled": true,
      "basePath": "/"
    },

    // TLS / HTTPS（可选）
    "tls": {
      "enabled": false,
      "autoGenerate": false
    },

    // 配置热重载模式
    "reload": {
      "mode": "hybrid",  // "hybrid" | "hot" | "restart" | "off"
      "debounceMs": 300
    }
  }
}

Docker 注意： 如果使用 Docker，默认 loopback 绑定会在容器内监听 127.0.0.1，外部无法访问。需设置 bind: "lan" 或使用 --network host。

5.2 agents — Agent 配置

定义 Agent 的身份、模型、工作区、心跳等运行时行为。

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["openai/gpt-5.4"]
      },
      "models": {
        "anthropic/claude-sonnet-4-6": { "alias": "Sonnet" },
        "openai/gpt-5.4": { "alias": "GPT" }
      },
      "thinkingDefault": "low",
      "reasoningDefault": "off",
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "directPolicy": "allow"
      },
      "sandbox": {
        "mode": "off",
        "scope": "agent"
      },
      "timeoutSeconds": 600,
      "mediaMaxMb": 5
    },
    "list": [
      {
        "id": "main",
        "default": true,
        "identity": {
          "name": "TARDIS",
          "theme": "Sentient Time Machine",
          "emoji": "🚀"
        }
      }
    ]
  }
}

5.3 models — 模型提供商

定义自定义/自建模型提供商。

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-xxx",
        "api": "openai-completions",
        "models": [{
          "id": "qwen3.6-plus",
          "name": "Qwen 3.6 Plus",
          "reasoning": false,
          "input": ["text", "image"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 1000000,
          "maxTokens": 65536,
          "compat": { "thinkingFormat": "deepseek" }
        }]
      },
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [{
          "id": "qwen2.5:7b",
          "name": "Qwen 2.5 7B",
          "reasoning": false,
          "input": ["text"],
          "cost": { "input": 0, "output": 0 },
          "contextWindow": 32768,
          "maxTokens": 4096
        }]
      }
    }
  }
}

5.4 channels — 消息通道

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-DEF...",
      "dmPolicy": "pairing",
      "allowFrom": ["123456789"],
      "groups": { "*": { "requireMention": true } }
    },
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+86138xxxxxxxx"]
    },
    "discord": {
      "enabled": true,
      "token": "BOT_TOKEN_HERE",
      "dm": { "enabled": true, "allowFrom": ["USER_ID"] },
      "guilds": {
        "123456789": {
          "slug": "my-server",
          "channels": {
            "general": { "allow": true },
            "help": { "allow": true, "requireMention": true }
          }
        }
      }
    }
  }
}

DM 策略说明：

策略行为
"pairing"陌生用户需要输入一次性配对码才能对话（默认，推荐）
"allowlist"仅允许 allowFrom 列表中的用户
"open"所有人可 DM（需配合 allowFrom: [”*”]）
"disabled"忽略所有 DM

5.5 tools — 工具权限

{
  "tools": {
    "allow": ["exec", "process", "read", "write", "edit"],
    "deny": ["browser", "canvas"],
    "exec": {
      "backgroundMs": 10000,
      "timeoutSec": 1800,
      "cleanupMs": 1800000
    },
    "elevated": {
      "enabled": true,
      "allowFrom": { "webchat": ["session:main"] }
    }
  }
}

5.6 env — 环境变量

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-...",
    "vars": {
      "GROQ_API_KEY": "gsk-..."
    },
    "shellEnv": {
      "enabled": true,
      "timeoutMs": 15000
    }
  }
}

在配置中通过 ${VAR_NAME} 引用。只匹配大写字母和下划线 [A-Z_][A-Z0-9_]*，缺失变量会报错。用 $${VAR} 转义字面值。

5.7 auth — 认证配置

{
  "auth": {
    "profiles": {
      "anthropic:default": { "provider": "anthropic", "mode": "api_key" },
      "anthropic:work": { "provider": "anthropic", "mode": "api_key" },
      "openai:personal": { "provider": "openai", "mode": "api_key" }
    },
    "order": {
      "anthropic": ["anthropic:default", "anthropic:work"],
      "openai": ["openai:personal"]
    },
    "cooldowns": {
      "billingBackoffHours": 5,
      "authPermanentBackoffMinutes": 10,
      "failureWindowHours": 24
    }
  }
}

5.8 ~ 5.16 其他核心配置

简要列出剩余核心配置项：

  • cron — 定时任务系统（enabled、maxConcurrentRuns、sessionRetention）
  • skills — 技能管理（allowBundled、load.extraDirs、install.preferBrew、entries）
  • hooks — Webhook 端点（token、path、mappings）
  • logging — 日志配置（level、file、consoleStyle、redactSensitive）
  • session — 会话管理（dmScope、threadBindings、reset）
  • mcp — MCP 服务器（sessionIdleTtlMs、servers）
  • plugins — 插件系统（enabled、allow/deny、entries）
  • browser — 浏览器控制（enabled、headless、tabCleanup）
  • ui — 界面外观（seamColor、assistant.name、assistant.avatar）

六、配置编辑的 4 种方式

方式 1：交互向导（新手推荐）

openclaw onboard     # 首次引导（完整流程）
openclaw configure   # 修改已有配置（定向修改）

交互式问答，逐项引导。适合第一次使用或不熟悉配置格式的情况。

方式 2：CLI 单行命令（精确修改）

# 读取某个字段
openclaw config get agents.defaults.workspace

# 设置某个字段
openclaw config set agents.defaults.heartbeat.every "2h"

# 删除某个字段
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

# 设置 JSON 值（带合并）
openclaw config set agents.defaults.models '{"bailian/qwen3.6-plus":{"alias":"Qwen"}}' --strict-json --merge

方式 3：Control UI 表单（可视化）

打开 http://127.0.0.1:18789，点击 Config 标签页：

  • 从 schema 自动生成表单，每个字段都有标题和说明
  • 插件和通道的 schema 自动合并显示
  • 底部有 Raw JSON 编辑器作为备用

方式 4：直接编辑文件（高级用户）

用任何编辑器直接打开 %USERPROFILE%\.openclaw\openclaw.json，保存后 Gateway 自动热重载。

七、配置校验与诊断

7.1 校验命令

命令用途
openclaw config validate校验当前配置是否符合 schema
openclaw config schema打印完整的 JSON Schema
openclaw doctor全面诊断：配置 + 环境 + 网络 + 认证 + 安全
openclaw doctor --fix自动修复已知问题（需确认）
openclaw doctor --yes自动修复且无需确认

7.2 校验失败时怎么办

当配置校验失败时：

  1. Gateway 拒绝启动（或跳过热重载，保持上次运行配置）
  2. 只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  3. 运行 openclaw doctor 查看具体错误信息
  4. 运行 openclaw doctor --fix 自动修复或恢复上次可用的配置

安全机制： Gateway 每次成功启动后会保存一份「最近可用配置」的备份。

7.3 热重载 vs 需要重启的变更

类别字段重启？
通道channels.*✅ 不需要
Agent & 模型agent, agents, models, routing✅ 不需要
自动化hooks, cron, agent.heartbeat✅ 不需要
会话 & 消息session, messages✅ 不需要
工具 & 媒体tools, browser, skills, mcp✅ 不需要
UI & 日志ui, logging, identity, bindings✅ 不需要
网关服务gateway.*（端口、绑定、认证、TLS、HTTP）❌ 需要重启
基础设施discovery, plugins❌ 需要重启

gateway.reload 和 gateway.remote 是例外——修改它们 不会 触发重启。

八、高级配置功能

8.1 $include 配置拆分

当配置文件变大时，可以用 $include 拆分成多个文件：

// ~/.openclaw/openclaw.json
{
  "gateway": { "port": 18789 },
  "agents": { "$include": "./agents.json5" },
  "channels": {
    "$include": ["./channels-telegram.json5", "./channels-discord.json5"]
  }
}
特性说明
单文件替换替换包含对象的整个内容
数组深合并按顺序深度合并，后面的覆盖前面的
嵌套 include最多支持 10 层嵌套
相对路径相对于包含文件所在的目录解析
安全限制默认只能引用 openclaw.json 同目录下的文件

8.2 SecretRef 安全凭证

当不希望将 API Key 直接写在配置文件中时，使用 SecretRef 对象：

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "OPENAI_API_KEY"
        }
      }
    }
  },
  "secrets": {
    "providers": {
      "default": { "source": "env" },
      "filemain": {
        "source": "file",
        "path": "~/.openclaw/secrets.json",
        "mode": "json"
      }
    }
  }
}
来源id 格式说明
env[A-Z][A-Z0-9_]{0,127}从环境变量读取
fileJSON Pointer，如 /providers/openai/apiKey从 JSON 文件读取
exec绝对路径命令执行命令从 stdin/stdout 获取

8.3 messages — 消息投递

{
  "messages": {
    "messagePrefix": "[OpenClaw]",
    "visibleReplies": "automatic",
    "ackReaction": "👀",
    "groupChat": {
      "visibleReplies": "message_tool",
      "unmentionedInbound": "room_event"
    },
    "queue": {
      "mode": "followup",
      "debounceMs": 500,
      "cap": 20,
      "drop": "summarize"
    }
  }
}

8.4 update — 自动更新

{
  "update": {
    "channel": "stable",
    "checkOnStart": true,
    "auto": {
      "enabled": false,
      "stableDelayHours": 6,
      "stableJitterHours": 12
    }
  }
}

8.5 discovery — 局域网发现

{
  "discovery": {
    "mdns": { "mode": "minimal" },
    "wideArea": { "enabled": true }
  }
}

8.6 acp — ACP 运行时

ACP（Agent Communication Protocol）允许 OpenClaw 作为 ACP 宿主，接入外部编码 Agent：

{
  "acp": {
    "enabled": true,
    "dispatch": { "enabled": true },
    "backend": "acpx",
    "defaultAgent": "main",
    "allowedAgents": ["main", "ops"],
    "maxConcurrentSessions": 10,
    "runtime": { "ttlMinutes": 30 }
  }
}

九、实用配置示例

9.1 最小可用配置

这是让 OpenClaw 跑起来的 最少配置：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

保存后启动 Gateway，即可通过 http://127.0.0.1:18789 访问 Control UI 聊天。

9.2 推荐配置（个人使用）

{
  "env": {
    "OPENCLAW_GATEWAY_TOKEN": "my-secure-token-123"
  },
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}",
      "allowTailscale": false
    },
    "controlUi": { "enabled": true },
    "reload": { "mode": "hybrid" }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": { "primary": "bailian/qwen3.6-plus" },
      "heartbeat": { "every": "30m", "target": "last" },
      "timeoutSeconds": 600
    },
    "list": [{
      "id": "main",
      "default": true,
      "identity": { "name": "TARDIS", "theme": "AI Assistant", "emoji": "🚀" }
    }]
  },
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "***",
        "api": "openai-completions",
        "models": [{
          "id": "qwen3.6-plus",
          "name": "Qwen 3.6 Plus",
          "reasoning": false,
          "input": ["text", "image"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 1000000,
          "maxTokens": 65536
        }]
      }
    }
  },
  "auth": {
    "profiles": {
      "bailian:default": { "provider": "bailian", "mode": "api_key" }
    },
    "order": { "bailian": ["bailian:default"] }
  },
  "cron": { "enabled": true }
}

9.3 本地模型配置（Ollama）

完全离线运行 AI 模型（无需 API Key）：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": { "primary": "ollama/qwen2.5:7b" }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [{
          "id": "qwen2.5:7b",
          "name": "Qwen 2.5 7B (Local)",
          "reasoning": false,
          "input": ["text"],
          "cost": { "input": 0, "output": 0 },
          "contextWindow": 32768,
          "maxTokens": 4096
        }]
      }
    }
  }
}

本地模型优势： 数据完全不出本机、零成本、无 API Key 管理。适合隐私敏感场景。劣势： 推理速度取决于本机 GPU/CPU，小模型能力有限。

9.4 多 Agent 路由配置

运行多个独立 Agent，通过通道/账号路由到不同 Agent：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": { "primary": "bailian/qwen3.6-plus" }
    },
    "list": [
      {
        "id": "home", "default": true,
        "workspace": "~/.openclaw/workspace-home",
        "identity": { "name": "Home", "emoji": "🏠" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "identity": { "name": "Work", "emoji": "💼" }
      }
    ]
  },
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "whatsapp", "accountId": "biz" } }
  ]
}

十、Windows 专属注意事项

10.1 路径处理

  • OpenClaw 内部使用 POSIX 风格路径（~/.openclaw/...）
  • Windows 上 ~ 自动展开为 C:\Users\用户名
  • 配置值中用 ~ 即可，不需要写完整 Windows 路径

10.2 PowerShell vs CMD

  • 推荐 PowerShell 7+（可通过 winget install Microsoft.PowerShell 安装）
  • 旧版 Windows PowerShell 5.1 也可用，但部分语法受限
  • CMD 下 &、| 等符号解析方式不同，建议用 PowerShell

10.3 环境变量设置

PowerShell 中设置临时变量：

$env:OPENCLAW_GATEWAY_TOKEN = "***"

永久设置用户级变量：

[Environment]::SetEnvironmentVariable("OPENCLAW_GATEWAY_TOKEN", "my-token", "User")

设置后需要重新打开终端才生效。也可以在 ~/.openclaw/.env 文件中定义。

10.4 防火墙

如果需要局域网访问，需在 Windows 防火墙中放行端口：

New-NetFirewallRule -DisplayName "OpenClaw Gateway" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

同时将配置中 gateway.bind 改为 "lan"。

10.5 Windows 服务（开机自启）

Onboarding 时加上 --install-daemon 参数会自动安装为系统服务：

openclaw onboard --install-daemon

服务管理：

openclaw gateway status    # 查看状态
openclaw gateway restart   # 重启
openclaw gateway stop      # 停止

服务名称通常为 openclaw-gateway。

10.6 沙箱限制

Windows 上 Docker 沙箱需要 WSL2 后端。如果未安装 WSL2，沙箱功能不可用。个人使用建议 sandbox.mode: "off"。

10.7 日志文件位置

默认日志在 %TEMP%\openclaw\openclaw-YYYY-MM-DD.log，即：

C:\Users\用户名\AppData\Local\Temp\openclaw\

查看日志：openclaw logs

十一、常见问题排查

Q1: openclaw 命令找不到

确认 Node.js 和 npm 已安装且加入 PATH：

node --version
npm --version

如果 npm 找不到 openclaw，尝试全局重新安装：

npm install -g openclaw

然后关闭并重新打开 PowerShell。

Q2: Gateway 启动失败 / Invalid config

运行诊断命令查看具体错误：

openclaw doctor

如果确认是配置问题，尝试自动修复：

openclaw doctor --fix

Q3: 修改配置后没生效

  • 检查 gateway.reload.mode，确认不是 "off"
  • 运行 openclaw gateway status 查看状态
  • 手动重启：openclaw gateway restart
  • 涉及 gateway.*、plugins、discovery 的变更必须重启才能生效

Q4: 模型调用失败 / 401 认证错误

  • 确认 API Key 正确：openclaw doctor
  • 检查 models.providers.*.apiKey 或 auth.profiles
  • 确认 baseUrl 地址可达（特别是内网/代理环境）
  • 查看日志：openclaw logs
  • 确认模型 ID 与 provider 定义中的 id 字段完全匹配

Q5: 浏览器工具无法使用

  • 确认已安装 Chromium 内核浏览器（Chrome / Edge / Brave）
  • 检查配置 browser.enabled: true
  • Windows 上推荐使用 Edge（系统自带，无需额外安装）
  • 如需指定浏览器：设置 browser.executablePath

Q6: 如何备份配置

openclaw backup create

手动备份整个目录：

Copy-Item -Path "$env:USERPROFILE\.openclaw" -Destination "D:\backup\openclaw-$(Get-Date -Format 'yyyyMMdd')" -Recurse

Q7: 如何完全卸载

openclaw uninstall

这会删除 ~/.openclaw 目录。建议先备份。

如需保留数据只卸载程序：

npm uninstall -g openclaw

Q8: PowerShell 安装脚本执行被阻止

Windows 默认的执行策略可能阻止脚本运行。临时放开：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

或者使用绕过策略执行：

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://openclaw.ai/install.ps1 | iex"

Q9: 服务安装失败 / 没有权限

安装 Windows 服务需要管理员权限。以管理员身份运行 PowerShell：

openclaw onboard --install-daemon

或者手动管理服务：

sc query openclaw-gateway
sc start openclaw-gateway
sc stop openclaw-gateway

Q10: npm install 下载很慢或失败

设置国内镜像源：

npm config set registry https://registry.npmmirror.com
npm install -g openclaw

如果仍然失败，检查网络代理设置：

npm config get proxy
npm config get https-proxy

附录：配置速查表

配置项默认值热重载说明
gateway.mode"local"需重启本地/远程模式
gateway.port18789需重启网关端口
gateway.bind"loopback"需重启网络绑定地址
gateway.auth.mode"token"需重启认证模式
gateway.reload.mode"hybrid"例外配置重载模式
agents.defaults.workspace"~/.openclaw/workspace"✅ 热加载工作区路径
agents.defaults.model.primary无✅ 热加载默认模型
agents.defaults.heartbeat.every"30m"✅ 热加载心跳间隔
cron.enabledfalse✅ 热加载启用定时任务
skills.allowBundled全部✅ 热加载内置技能白名单
logging.level"info"✅ 热加载日志级别
session.dmScope"main"✅ 热加载DM 会话作用域
browser.enabledtrue✅ 热加载启用浏览器自动化
ui.seamColor"#FF4500"✅ 热加载UI 主题色
plugins.enabledtrue需重启启用插件系统
discovery.mdns.mode"minimal"需重启局域网发现模式
mcp.sessionIdleTtlMs600000✅ 热加载MCP 会话空闲超时

本文基于 OpenClaw 2026.6.x 编写 · 最后更新 2026-06-02