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

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

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

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

## 2.3.1 运行初始化向导

执行以下命令启动向导。官方推荐使用 `--install-daemon` 参数，它不仅会生成工作区配置文件，还能自动安装后台守护进程（如 macOS 的 LaunchAgent 或 Linux/WSL2 的 systemd 用户服务）。

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

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

> **提示**：带与不带 `--install-daemon` 参数的主要区别在于是否自动配置系统的**后台守护进程**：
>
> * **带参数**（推荐）：不仅生成工作区配置文件（如 `~/.openclaw/workspace`），还会自动注册并安装系统后台服务（如 macOS 的 LaunchAgent 或 Linux 的 systemd），保障 Gateway 服务在机器重启后也在后台持续运行，适合长期使用。
> * **不带参数**（仅运行 `openclaw onboard`）：只生成配置文件并完成初始化，不会注册系统后台服务。每次需要使用时可能需要手动启动，更适合本地临时试用或验证。

## 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`，但不配置会影响 Agent 绝大多数需要联网查询和实时验证的任务。
4. **技能配置 (Skills)**：用于挂载官方或社区提供的基础能力包（例如专门处理版本控制的 `github`，或是针对游戏分发的 `gog`，以及常用的 `clawhub` 等）。为保证初始化环境干净，**强烈建议首次配置时选择 `Skip for now`**，等基础链路验证可用后，再根据需要通过控制台按需挂载特定的技能，从而避免一上来因为某个扩展包解析失败导致整个流程卡住。
5. **工作区 (Workspace)**：默认生成在 `~/.openclaw/workspace`，用于存放 Agent 的核心数据。建议保持默认。
6. **渠道 (Channels)** 选 `Skip for now`：这是极大降低挫败感的关键。先把自带的 Dashboard（控制台）验证可用，确认大模型和基础环境都没问题，后续再从容配置飞书或 WhatsApp 等渠道。

向导结束时会自动进行 Health check（健康检查），并**自动启动一次** Gateway。

> **注意**：如果初始化时未使用 `--install-daemon` 参数，后续在关闭终端或重启电脑后，需要手动执行 `openclaw gateway` 来启动服务。完成引导后，最快的首轮对话入口是 `openclaw dashboard`。

## 2.3.3 工作区产物概览

向导结束后，`openclaw onboard` 会在 `~/.openclaw/workspace` 目录下植入一组标准工作区文件。它们共同构成智能体的引导上下文与长期工作区；而单独运行 `openclaw setup` 时，至少也会初始化配置文件、工作区目录与会话目录。

```
~/.openclaw/workspace/
├── AGENTS.md        # 工作区启动清单与行为准则
├── SOUL.md          # 智能体人格与沟通风格定义
├── USER.md          # 用户档案与个人偏好
├── IDENTITY.md      # 智能体元数据（名称、形象等）
├── TOOLS.md         # 本地环境与工具配置
├── HEARTBEAT.md     # 心跳巡检清单（可选）
├── BOOT.md          # Gateway 启动时的可选自检/收尾清单
├── BOOTSTRAP.md     # 首次运行脚本（完成后自动删除）
├── MEMORY.md        # 可选的长期记忆索引
├── memory/          # 按日期切分的日记式记忆文件
├── skills/          # 工作区级技能目录（可选）
└── canvas/          # 节点 UI 或可视化文件（可选）
```

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

* `AGENTS.md`、`SOUL.md`、`USER.md`：每轮会话都会读取的常驻引导文件。
* `IDENTITY.md`：在 bootstrap ritual 中创建或更新，用于定义名称、形象与风格。
* `TOOLS.md`：记录本地工具和团队约定，只提供指导，不直接控制工具权限。
* `HEARTBEAT.md`：Heartbeat 运行时使用的微型清单，应保持尽量短小。
* `BOOT.md`：只在启用内部 Hook 且 Gateway 重启时执行的启动清单。
* `BOOTSTRAP.md`：只为全新工作区创建的一次性首跑仪式文件，用完即可删除。
* `memory/YYYY-MM-DD.md`：按日切分的记忆日志，官方建议在会话开始时优先读取今天和昨天。
* `MEMORY.md`：可选的长期记忆索引，更适合主私有会话，而不是共享/群组上下文。
* `skills/`：工作区级技能目录；与托管技能重名时，以工作区版本优先。
* `canvas/`：节点 UI 或可视化资源目录，例如 `canvas/index.html`。

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

> \[!TIP] 这些文件都是普通 Markdown，可以随时用任何编辑器修改。智能体自身也会在交互过程中主动更新它们。如果你修改了 SOUL.md 或 AGENTS.md，下一次新会话就会立即生效——无需重启 Gateway。

## 2.3.4 首轮验收标准

向导结束后，Gateway 已在后台运行。下一步是通过 Dashboard 完成首轮对话验证，详见[第三章](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop)。

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

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

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

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

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