# 2.2 引导向导与首次配置

> **生成模型**：OpenAI GPT-5.4 (openai/gpt-5.4) **Token 消耗**：输入 \~25k tokens，输出 \~3.6k tokens（本节）

***

上一节我们把 OpenClaw 安装好了，但那还只是“工具在电脑上”。现在还差一步：让它知道自己该怎么工作。

这一步如果你靠手写配置文件，也不是完全不行，但我不建议新手这么干。原因很简单：第一次接触 OpenClaw，你还不知道哪些字段是必填、哪些选项互相有关、哪些设置会落到哪个目录。这个时候最好的入口不是自己猜，而是直接跑引导向导。

OpenClaw 的首次引导命令叫：

```bash
openclaw onboard
```

有些场景你也会看到别人写：

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

这表示在完成引导的同时，顺手安装后台守护进程。我们这章先不着急把它放到后台长期运行，先把最小链路走通。所以建议你先从不带额外参数的 `openclaw onboard` 开始。

## 2.2.1 为什么第一次别手搓配置文件

你可以把 `onboard` 理解成一个带校验的安装助手。它不是“炫技用的交互界面”，而是把第一次配置里最容易漏、最容易配错的地方帮你拦下来。

比如它会引导你处理这些问题：

* Gateway 监听在哪里
* 默认模型用哪个
* 模型提供方怎么认证
* 工作目录和本地数据往哪里放
* 要不要顺手连接一个通道

这些设置如果你都清楚，当然也可以以后自己改配置；但第一次上手时，用向导明显更稳。

## 2.2.2 运行 `openclaw onboard` 之后会发生什么

先在终端里执行：

```bash
openclaw onboard
```

你通常会看到类似下面的开始界面：

```
Welcome to OpenClaw onboarding

This wizard will help you:
  - configure your local Gateway
  - choose a model provider
  - set a default model
  - optionally connect channels
```

不同版本的界面文案可能略有变化，但整体流程差不多。你可以把它想成 4 个阶段：

1. 确认基础信息和安全提醒
2. 配 Gateway
3. 配模型提供方和默认模型
4. 预览或连接第一个通道

我们一个个来看。

## 2.2.3 第一步：先过一遍安全提醒

第一次运行时，向导一般会先给你一段安全提醒。别看到提示就条件反射按回车，这里它不是在走形式。

OpenClaw 是一个能接收消息、能调模型、还能在某些配置下调用工具的系统。换句话说，它不是单纯“帮你问答”的玩具。如果你后面给它更高的能力，比如文件访问、命令执行，那输入内容的安全边界就很重要。

在入门阶段，你先记住一句话就够了：

不要把 OpenClaw 当成一个什么都能无脑相信的自动驾驶系统。

它很强，但也需要你给它一个合理的运行边界。

## 2.2.4 第二步：配置 Gateway

Gateway 可以先粗暴理解成 OpenClaw 的本地中枢。CLI 发消息给它，后面接消息通道也要靠它。所以向导里首先会问 Gateway 相关配置，这是合理的。

新手最常见的默认设置通常是：

* 监听地址：`127.0.0.1`
* 端口：`18789`

你在提示里看到的内容可能长这样：

```
Gateway host: 127.0.0.1
Gateway port: 18789
Allow remote access? No
```

如果你只是本机学习、自己在终端里发消息，这个默认值就很好，别乱改。

为什么默认绑定 `127.0.0.1`？因为这表示只允许本机访问。对第一次使用来说，这是最安全、最省心的方式。你暂时不需要考虑把它暴露给局域网，不需要考虑远程访问，更不需要一上来就研究公网入口。

等你后面真的需要多设备访问，再去看更完整的 Gateway 配置也不迟。

## 2.2.5 第三步：配置模型提供方

这一部分是整个引导里最关键的地方。因为 OpenClaw 自己不“产出答案”，真正生成回复的是后面的模型提供方。

你可以把这个关系理解成：

* OpenClaw 负责路由、会话、通道、工具、运行时
* 模型提供方负责生成自然语言回复

所以向导一定会问你：准备用哪家模型、怎么认证。

常见的选择包括：

* Anthropic
* OpenAI
* OpenRouter
* Google Gemini
* 本地模型服务（如 Ollama，取决于你的环境）

对于第一次上手，我建议你选自己最熟、最稳的那一家。如果你本来就有 API Key，直接配它，最省时间。

### 一个典型的 API Key 配置过程

比如你选择某个支持 API Key 的提供方后，向导大概率会继续问：

```
Choose authentication method:
  - API key
  - OAuth

Enter API key: ********
```

这时候你把 Key 填进去即可。终端一般不会明文回显，这很正常。输完之后，它通常还会让你选一个默认模型，比如：

```
Choose default model:
  - anthropic/claude-sonnet-4
  - anthropic/claude-opus-4-6
  - openai/gpt-5.1
  - openai/gpt-4.1
```

这里你不用纠结“最强的一定最好”。入门阶段的目标不是做模型测评，而是把链路跑通。能稳定返回结果的模型，就是好模型。

### API Key 放在哪儿了

新手很常问这个问题：我刚才输入的 Key，OpenClaw 存到哪里去了？

你不需要一开始就掌握全部配置细节，但最好知道一个大概：首次配置完成后，OpenClaw 会在你的用户目录下建立自己的工作目录，通常是 `~/.openclaw/`。里面会放主配置、凭据、会话数据、工作区等内容。

别急着现在手动去改。先让向导帮你生成一套能跑的最小配置，后面再慢慢认识这些文件更合适。

## 2.2.6 第四步：选默认模型时，别把自己绕晕

很多同学第一次看到一串模型列表，会开始犹豫：到底该选推理强的，还是速度快的？要不要一步到位选最贵的？

这里我给一个很实用的建议：

先选你已经能正常认证、而且返回速度稳定的那个。

因为这一章的目标不是找“宇宙最优模型”，而是确认 OpenClaw 能把请求送出去、模型能回得来、Gateway 能把结果交回 CLI。只要链路通了，以后你改默认模型是非常便宜的事。

如果向导支持测试连接，建议你直接测一次。比如你会看到类似：

```
Testing model access...
Success: model is available
```

只要看到这类成功提示，心里就踏实很多。

## 2.2.7 Gateway 配置和模型配置，关系是什么

这一点很多新手会混在一起。

Gateway 配置解决的是“OpenClaw 本地服务怎么启动、怎么被访问”；模型配置解决的是“OpenClaw 该把推理请求发给谁”。

一个管本地中枢，一个管外部大脑。两者都得配，但不是一回事。

如果你把它们混在一起，后面排错时就容易乱。举个例子：

* `openclaw gateway` 启不来，优先看本地服务配置
* Gateway 能启动，但消息发出去没回复，优先看模型认证和默认模型

这样拆开想，很多问题就没那么吓人了。

## 2.2.8 第五步：第一个通道连接预览

做完模型配置之后，向导一般会继续问你，要不要现在连接消息通道。这里的“通道”，你可以先理解成 OpenClaw 接收和发送消息的入口，比如 Telegram、Discord、Slack、WhatsApp 之类。

但这一章我们主线是：先把本机 CLI 跑通。所以我的建议是：

先看预览，理解它大概能接什么；真正连接可以先跳过，或者只做最轻量的一种。

你可能会看到类似菜单：

```
Connect a channel now?
  - Skip for now
  - Telegram
  - Discord
  - Slack
  - WhatsApp
```

如果你选择 `Skip for now`，完全没问题。你不会因此失去本章后面的学习能力，因为我们下一节发第一条消息走的是 CLI，本来就不依赖 Telegram 或 Discord。

### 为什么还要让你先看一眼通道

因为这一步的价值不只是在“现在就连上”，还在于让你建立一个正确印象：OpenClaw 不是只能在终端里问答。CLI 只是其中一个入口，后面各种消息平台也是入口，而真正把这些入口统一起来的，是 Gateway。

哪怕你现在先不连通道，先看一眼菜单，脑子里也会有个图：哦，原来以后我能把同一套运行时接到不同平台上。

## 2.2.9 向导结束后，你会得到什么

当 `openclaw onboard` 走完以后，一般会给你一个完成提示，大概像这样：

```
Onboarding complete

Next steps:
  1. start the Gateway
  2. send a message with `openclaw agent`
  3. optionally connect channels later
```

这时最重要的不是把提示关掉，而是确认你已经完成了三件事：

* 有了一套本地配置
* 有了一个能用的模型提供方认证
* 选好了默认模型

这就够继续往下走了。

## 2.2.10 如果向导中途卡住，该怎么排

### 输入了 API Key，但测试失败

先确认三件事：

1. Key 有没有复制错，前后有没有多空格
2. 当前终端所在的机器网络能不能访问对应模型服务
3. 你选的模型是不是当前账号真能调用

很多时候不是 Key 错，而是“认证方式和模型不匹配”。

### 端口冲突

如果向导或后续启动时提示端口被占用，说明 `18789` 已经被别的进程用了。你可以换一个端口，但要记住后面 CLI 访问 Gateway 时也要用同样的配置。入门阶段如果没有特殊原因，优先先释放冲突，比随手改一堆端口更省脑子。

### 配完了，还是不放心

很正常。第一次配这种系统，很多人都会觉得“我是不是漏了什么”。最简单的验证办法不是去翻配置文件，而是下一节直接启动 Gateway，然后发一条消息。能回，就说明最关键的链路已经成立。

## 2.2.11 现在你脑子里应该有的图

到这里，你不需要记住所有配置细节，但最好已经有这样一幅图：

```
我运行 openclaw onboard
        ↓
向导帮我写好本地配置
        ↓
我选定 Gateway 的本地监听方式
        ↓
我配置模型提供方和默认模型
        ↓
我可以稍后再接消息通道
        ↓
下一步就能启动 Gateway 并发送第一条消息
```

如果这张图你已经能在脑子里说顺，说明这一节你就真的学到了，不是只跟着敲了一遍命令。

## 本节小结

* 第一次使用 OpenClaw，优先跑 `openclaw onboard`，别急着手写配置文件。
* 引导向导最关键的两部分是 Gateway 本地配置和模型提供方认证，这两者别混为一谈。
* API Key 配置的核心目标不是“选最强模型”，而是先选一个你能稳定调用的默认模型，把链路跑通。
* 通道连接这一步可以先预览、先跳过；本章后面的首条消息测试并不依赖 Telegram 或 Discord。
* 向导结束后，只要你已经完成本地配置、模型认证和默认模型选择，就可以进入下一节，启动 Gateway 并真正发出第一条消息。