> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.3_onboarding.md).

# 2.3 初始化向导与首轮配置

> **预计耗时**：5–10 分钟

安装完毕后，OpenClaw 需要了解三件事：你的部署环境（单机还是服务器）、模型供应商（Claude、OpenAI、还是本地模型）、以及工作目录位置。初始化向导会逐一询问这些问题，帮你生成一份可工作的 `openclaw.json` 配置。

本节贯彻一个核心哲学：**优先完成可工作的最小配置，再按需增强**。我们推荐的“黄金路径”是保守的——几乎所有选项都推荐“先跳过”，原因是初装时任何一个扩展配置失败都可能导致整个流程卡住。对于大多数人，先把基础链路验证可用（模型能回复、控制台能访问），再从容地逐个启用搜索、渠道、技能，这样的节奏体验会好很多。

## 2.3.1 运行初始化向导

执行以下命令启动向导。`openclaw onboard --install-daemon` 是当前较完整的一条初始化路径：它既完成交互式 onboarding，也会尝试安装托管 Gateway 服务（如 macOS 的 LaunchAgent、Linux/WSL2 的 systemd 用户服务，Windows 则优先尝试 Scheduled Tasks）。

```bash
openclaw onboard --install-daemon
```

当前官方 CLI 还提供 `openclaw setup` 这一条更“轻量”的初始化命令，用于先创建 `openclaw.json` 和工作区；如果要从 `setup` 入口进入同一套交互式引导，可使用 `openclaw setup --wizard`。换句话说，`setup` 负责“初始化配置与工作区”，`onboard` 负责“完整交互式引导”；本章聚焦首次上手，因此仍以 `openclaw onboard` 作为主线。

> **提示**：带与不带 `--install-daemon` 参数的主要区别在于是否自动配置系统的**后台守护进程**：
>
> * **带参数**（推荐）：不仅写入配置文件（默认 `~/.openclaw/openclaw.json`）并初始化智能体工作区目录（默认 `~/.openclaw/workspace`），还会自动注册并安装系统后台服务（如 macOS 的 LaunchAgent 或 Linux 的 systemd），保障 Gateway 服务在机器重启后也在后台持续运行，适合长期使用。
> * **不带参数**（仅运行 `openclaw onboard`）：完成引导和配置写入，但不会安装系统后台服务。更适合本地临时试用；本地健康检查通常要求已有 Gateway 正在运行，必要时先另开终端执行 `openclaw gateway run`。

## 2.3.2 向导配置项解析与避坑指南

在向导的系列提问中，实测验证出的一条对排错压力最小的“黄金路径”如下：

1. **Onboarding mode** 选 `QuickStart`：让你以最小配置量快速跑起来。默认绑定在本地 `127.0.0.1:18789` 并且关闭 Tailscale 外部暴露。
2. **模型与 Auth (Model/Auth)**：建议绑定 Anthropic API Key 或 OpenAI。若使用其他兼容供应商，可根据提示输入。
3. **搜索引擎 (Search provider)**：用于赋予 Agent 联网搜索的能力（如检索最新文档、新闻等）。向导会列出当前支持的搜索引擎选项（具体列表随版本更新，以向导实际显示为准）。如果暂时不想配置，也可以选择 `Skip for now`，但不配置会影响需要实时网络验证的任务。
4. **技能配置 (Skills)**：用于挂载官方或社区提供的基础能力包（例如专门处理版本控制的 `github`，或是针对游戏分发的 `gog`，以及常用的 `clawhub` 等）。为保证初始化环境干净，**强烈建议首次配置时选择 `Skip for now`**，等基础链路验证可用后，再根据需要通过控制台按需挂载特定的技能，从而避免一上来因为某个扩展包解析失败导致整个流程卡住。
5. **工作区 (Workspace)**：默认生成在 `~/.openclaw/workspace`，用于存放 Agent 的核心数据。建议保持默认。
6. **渠道 (Channels)** 选 `Skip for now`：这是极大降低挫败感的关键。先把自带的 Dashboard（控制台）验证可用，确认大模型和基础环境都没问题，后续再从容配置飞书或 WhatsApp 等渠道。

向导结束时会自动进行 Health check（健康检查）。如果使用 `--install-daemon`，它会走托管 Gateway 安装与启动路径；如果不使用该参数，应把它理解为“完成配置并在已有本地 Gateway 上校验链路”，而不是一律帮你安装或启动常驻后台服务。

> **注意**：如果初始化时未使用 `--install-daemon` 参数，后续在关闭终端或重启电脑后，通常需要你自行确保本地 Gateway 处于运行状态（例如手动运行 `openclaw gateway run` 或另行启动托管服务）。完成引导后，最快的首轮对话入口是 `openclaw dashboard`。

## 2.3.3 工作区产物概览

向导结束后，OpenClaw 会初始化默认工作区 `~/.openclaw/workspace`。但这里要区分“首次 bootstrap 时种下的文件”和“之后按需读取或按需生成的文件”，不能把它们都理解成首次一定存在、且每轮都会等量注入。

```
~/.openclaw/workspace/
├── AGENTS.md        # 工作区常驻指令
├── BOOTSTRAP.md     # 首次运行仪式文件（完成后删除）
├── IDENTITY.md      # 智能体身份信息
├── USER.md          # 用户档案与偏好
├── SOUL.md          # bootstrap 过程可补写的人格/风格文件
├── TOOLS.md         # 工具注册与配置
├── HEARTBEAT.md     # 心跳巡检清单
├── MEMORY.md        # 长期记忆索引（可选）
├── skills/          # 当前工作区的技能目录（可选）
└── memory/          # 会话或 hook 写入的记忆文件目录（可选）
```

更准确地说，这些文件不应被一概理解成“都会在每轮会话里等量注入”。按当前官方文档，它们的语义分别是：

* `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`：这些属于工作区 bootstrap 识别的核心文件；是否存在、是否有内容、是否在当前场景下注入，要看具体运行路径。
* `IDENTITY.md` 与 `USER.md`：在 bootstrap ritual 中创建或更新，用于定义智能体与用户侧的稳定上下文。
* `BOOTSTRAP.md`：只为全新工作区创建的一次性首跑仪式文件，用完即可删除。
* `BOOT.md`：不是默认 bootstrap 文件，也不是常规 prompt 注入文件；只有文件存在且启用 bundled `boot-md` hook 时，才会在 Gateway startup 阶段执行。
* `HEARTBEAT.md`：Heartbeat 的专用清单文件；文件存在时属于 workspace/bootstrap prompt 文件，轻量 heartbeat 模式会只保留它而跳过其它 workspace bootstrap 文件。
* `memory/`：记忆或 hook 写入目录，属于运行期数据面，不应理解成“每轮自动等量加载”。
* `MEMORY.md`：可选的长期记忆索引，更适合沉淀稳定事实。
* `skills/`：当前工作区的技能目录；`openclaw skills install` 默认也会把技能装到当前工作区的 `skills/` 下。

各文件的详细职责、读取时机与加载策略将在后续章节展开：人格配置见[第 3 章](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop.md)，心跳与定时任务见[第 8 章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/08_automation_ops/8.3_heartbeat.md)，上下文管理见[第 6 章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/06_context_memory.md)。

> \[!TIP] 这些文件都是普通 Markdown，可以随时用任何编辑器修改。若你修改了 `AGENTS.md`、`SOUL.md` 等工作区指令文件，通常从下一次新会话开始生效；无需把“是否生效”理解成必须重启 Gateway。

## 2.3.4 首轮验收标准

如果使用了 `--install-daemon`，向导结束后 Gateway 通常已经在后台运行；如果没有安装守护进程，请先手动启动本地 Gateway。下一步是通过 Dashboard 完成首轮对话验证，详见[第三章](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop.md)。

在此之前，建议通过自带的诊断工具进行环境检查：

```bash
# 检查 Gateway 运行状态
openclaw gateway status

# 执行体检验证配置
openclaw doctor
```

在诊断通过后，说明“模型与基础控制链路”已经打通。下一节将详细介绍如何对运行在后台的 Gateway 进行监控、日志排查与深度可用性验证。

下一节入口：[2.4 守护进程与可用性验收](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.4_gateway_service.md)