安装与配置

这篇文档按“先跑通、再细化”的顺序编排。
目标很简单：先装好 OpenClaw，再把服务器跑通，最后学会查 openclaw.json 字段。

你选择哪种安装方式？

你的环境	推荐方式	使用特点
macOS	安装脚本 + 向导	支持度最高，体验最好
Windows	WSL2 + 安装脚本	官方推荐路径，稳定性更高
Linux	安装脚本 + systemd	适合长期运行
Docker	docker-setup.sh	环境隔离、迁移方便

安装前准备（4 件事）

1. 准备一个可联网环境（首次安装需要下载依赖）。
2. 确认你有终端权限（macOS Terminal / Windows PowerShell / Linux shell）。
3. 先不改复杂配置，先跑通默认配置。
4. 记住配置文件路径：~/.openclaw/openclaw.json（Docker 以容器内路径为准）。

一、macOS 安装（最简单）

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

如果你看到 openclaw: command not found，先执行：

npm prefix -g
echo "$PATH"

把 npm 全局 bin 加到 PATH 后重开终端再试。

二、Windows 安装（推荐 WSL2）

方式 A（推荐）：WSL2 + Ubuntu

PowerShell（管理员）先执行：

wsl --install

安装完成后进入 Ubuntu，再执行：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

如果 WSL 里 gateway install 失败，通常是没有启用 systemd。
在 WSL 里写入：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后在 PowerShell 执行 wsl --shutdown，再重新打开 Ubuntu。

方式 B：PowerShell 直接安装

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

官方更推荐方式 A（WSL2），稳定性更好。

三、Linux 安装

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

如果是远程主机（VPS），在你本地电脑开端口转发：

ssh -N -L 18789:127.0.0.1:18789 <user>@<host>

然后本地浏览器访问 http://127.0.0.1:18789/。

四、Docker 安装

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

完成后浏览器打开 http://127.0.0.1:18789/。
如果需要再次拿到 dashboard 链接：

docker compose run --rm openclaw-cli dashboard --no-open

五、openclaw onboard --install-daemon 全流程逐步解释（重点）

这个命令会启动 OpenClaw 的交互式向导，并在最后安装守护进程（daemon），让 Gateway 网关能后台常驻。
如果你是第一次使用，建议直接运行：

openclaw onboard --install-daemon

下面是你会遇到的每一步。

第 0 步：已有配置检测（保留 / 修改 / 重置）

你可能会看到：系统检测到已有 ~/.openclaw/openclaw.json。
向导会让你选：

• 保留：继续用现有配置。
• 修改：在现有基础上改。
• 重置：清理旧配置重新来。

小白建议：
如果你是第一次装，通常不会看到这步；如果看到，先选“修改”，不要急着“重置”。

第 1 步：选择向导模式（快速开始 / 高级）

你会看到两种模式：

• 快速开始：自动带默认值，最省心。
• 高级：每一步都让你细选。

小白建议：
第一次用选“快速开始”。

第 2 步：模型与认证（最关键的一步）

向导会问你用哪家模型提供商（Provider）、用什么认证方式，例如：

• Anthropic API Key
• OpenAI API Key / OpenAI 订阅
• 其他模型提供商（如自定义兼容端点）
• 跳过（不推荐）

这一步本质是在回答两个问题：

1. 你让 OpenClaw 用哪家大模型？
2. 用什么凭据去调用它？

小白建议：

1. 如果你已有可用 API Key，就选对应模型提供商并填入。
2. 暂时不确定时，不要一次填多个 key，先配一个能用的。
3. 配完后，后面可以再用 openclaw configure 补充。

中国大陆推荐怎么选（这一步请重点看）

截至 2026-02-22，在 OpenClaw 的 onboard 认证选项里，下面几组更适合中国大陆新手优先尝试。

推荐优先级	认证选项	适合场景	推荐原因（小白版）
1	volcengine-api-key	你有火山引擎账号	v2026.2.21 新增官方支持，向导可直接选，默认模型会自动写入
2	minimax-api-key-cn	你在中国大陆使用 MiniMax	专门的 CN 端点选项，链路更贴近大陆环境
3	zai-api-key（或 zai-cn / zai-coding-cn）	你要用 GLM 系列	向导支持 Z.AI 端点选择，可直接选 CN/Coding CN
4	moonshot-api-key-cn	你要用 Kimi	Moonshot 在向导里有 .cn 选项，配置更直接
5	byteplus-api-key	你用 BytePlus 体系	v2026.2.21 新增官方支持，可走同样的向导流程

如果你是第一次配置，我建议按这个顺序做：

1. 先在向导里选择一个你已经有 key 的模型提供商（Provider）。
2. 只配一个模型提供商，先跑通。
3. 跑通后再加第二个模型提供商做兜底。

非交互场景（可复制）：

# 火山引擎
openclaw onboard --non-interactive --accept-risk \
  --auth-choice volcengine-api-key \
  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"

# MiniMax（中国大陆端点）
openclaw onboard --non-interactive --accept-risk \
  --auth-choice minimax-api-key-cn \
  --minimax-api-key "$MINIMAX_API_KEY"

# Z.AI（CN）
openclaw onboard --non-interactive --accept-risk \
  --auth-choice zai-cn \
  --zai-api-key "$ZAI_API_KEY"

# Moonshot（.cn）
openclaw onboard --non-interactive --accept-risk \
  --auth-choice moonshot-api-key-cn \
  --moonshot-api-key "$MOONSHOT_API_KEY"

重要说明：

• 你在交互向导里不用记这些参数名，直接按菜单选就行。
• minimax-api 和 minimax-api-key-cn 是两个不同选项，前者偏通用，后者是 CN 端点。
• Z.AI 可以自动探测端点；你也可以手工选 zai-cn 或 zai-coding-cn。
• 火山引擎 / BytePlus 是 v2026.2.21 这一版里新增接入的重点之一。

第 3 步：选择工作区（workspace）

向导会问你的工作区放哪里，默认通常是：

~/.openclaw/workspace

这目录用于放智能体运行文件与相关内容。

小白建议：
第一次用默认路径即可，不要改到权限复杂的目录。

第 4 步：Gateway 网关参数（端口 / 绑定 / 认证）

你会配置：

• gateway.port（默认常见是 18789）
• gateway.bind（如 loopback）
• gateway.auth（如 token）
• 是否启用 Tailscale 相关暴露（远程访问方案）

Tailscale 是什么？

Tailscale 可以理解成“给你自己的设备拉一条私有内网”。
它会把你的电脑、手机、服务器放到同一个私有网络（Tailnet）里，这样你可以跨网络访问自己的服务，而不用直接把端口暴露到公网。

对 OpenClaw 来说，它的作用是：

1. 让你在外网也能访问自己的 Gateway 网关。
2. 尽量减少“直接开公网端口”的风险。
3. 让远程连接过程更简单（尤其是多设备场景）。

在向导里，你常见会看到这类选项：

• off：关闭 Tailscale（只本机或你已有其他网络方案）。
• serve：通过 Tailnet 私网访问（通常更推荐）。
• funnel：公开暴露到公网（风险更高，需更严格认证）。

这一步决定“谁能连上你的网关”。

建议顺序（重要）：

1. bind 先用 loopback（仅本机可访问）。
2. 认证先保留 token，不要一开始就关认证。
3. tailscale.mode 第一次安装先选 off，明确需要远程访问时再切到 serve。
4. 没有安全经验时，不建议一开始用 funnel。

第 5 步：渠道配置（可选）

向导会问你要不要配置渠道，例如：

• Telegram
• WhatsApp
• Discord
• 其他渠道

每个渠道会再问对应 token / key / 账号信息。

小白建议：

1. 第一次先跳过大部分渠道。
2. 最多先配一个你最常用的渠道。
3. 不配渠道也能先通过 openclaw dashboard 在浏览器聊天。

第 6 步：安装守护进程（daemon）

因为你用了 --install-daemon，这一步会自动执行后台服务安装：

• macOS：安装 LaunchAgent
• Linux / WSL2：安装 systemd 用户服务

这一步的意义是：你退出终端后服务还能继续运行。

小白建议：

1. 看到权限请求就按提示授权。
2. Linux / WSL2 如果提示 systemd 问题，先修好 systemd 再重跑向导。

第 7 步：健康检查（health check）

向导会尝试启动 Gateway 网关并检查状态，常见会触发：

• openclaw health
• 或等效状态检查

小白建议：
这一步必须通过，没通过就先别继续折腾渠道和高级配置。

第 8 步：Skills 安装（推荐但可选）

向导会扫描可用 Skills，并提示安装可选依赖。
通常会让你选包管理器（例如 npm / pnpm）。

小白建议：
第一次先装推荐项即可，先保证核心链路可用。

第 9 步：结束与下一步

向导会给你总结信息，通常下一步是：

openclaw gateway status
openclaw dashboard

如果页面能打开并能发消息，说明你的基础安装已经成功。

一句话理解 --install-daemon

• 不加它：只做引导，不一定安装后台常驻服务。
• 加了它：引导结束后会尽量把后台服务也装好，适合日常稳定运行。

运行后到底改了哪些文件？

常见会写入（按你的选择）：

• ~/.openclaw/openclaw.json（主配置）
• ~/.openclaw/.env（部分密钥环境变量）
• ~/.openclaw/credentials/...（OAuth 或渠道凭据）
• ~/.openclaw/workspace/...（工作区初始化文件）

常见卡点与处理

卡点	常见原因	处理方式
向导中止并提示先修配置	旧配置字段无效	先执行 openclaw doctor 再重跑
daemon 安装失败	systemd / 权限问题	修复 systemd 或权限后重跑 openclaw onboard --install-daemon
模型检查失败	API key 无效或模型名不对	重新选择模型提供商并校验 API key
渠道连不上	token 或配置不完整	先关闭该渠道，跑通主链路后再单独配置

六、10 分钟完成基础服务器配置

1) 找到配置文件

• 默认：~/.openclaw/openclaw.json
• 自定义路径：OPENCLAW_CONFIG_PATH=/your/path/openclaw.json
• 格式：JSON5（支持注释和尾逗号）

2) 先放一个最小可运行配置

{
  gateway: {
    mode: "local",
    bind: "lan",
  },
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4.1-mini",
      },
    },
  },
}

3) 快速检查是否生效

openclaw gateway status
openclaw doctor
openclaw dashboard

如果 doctor 报配置字段错误，说明 openclaw.json 里有拼写或类型问题，按提示修复即可。

如果你需要完整字段字典（含 gateway 全量字段）和高频字段速查，请查看：详细配置指南。

---

七、给小白的配置建议（避免踩坑）

1. gateway.mode 先固定成 local，先把本机跑通，再做远程。
2. gateway.bind 先用 loopback，不要一开始就 lan。
3. 先开最少渠道（例如只开一个 telegram 或 discord），逐步加。
4. API key 优先走环境变量，不要到处复制到文件里。
5. 每次改完配置就执行一次 openclaw doctor。

八、常见报错与处理

现象	原因	处理
Gateway 启动被拒	gateway.mode 不是 local（且未允许未配置启动）	把 gateway.mode 设为 local
访问返回 401	认证方式不匹配 / token 错	检查 gateway.auth.* 与客户端凭据
连接后反复 pairing required	设备配对未通过或 token 不一致	重新配对并确认设备状态
Docker 下权限错误（EACCES）	宿主机挂载目录权限不对	修正目录属主与权限

九、资料来源（官方一手）

• Getting Started
• Install
• Platforms
• Windows（WSL2）
• Linux
• macOS
• Docker
• Onboarding Wizard（CLI）
• CLI Onboarding Reference
• Gateway Configuration
• Configuration Reference（完整字段）
• MiniMax Provider
• Moonshot Provider
• Z.AI Provider
• OpenClaw GitHub 仓库
• OpenClaw Releases
• v2026.2.21 Release

核对时间：2026-02-22