企业官网建设流程全解析

1. 为什么第一次跑 OpenClaw CLI 总卡在 onboard

OpenClaw 是一个把大模型能力接到本地工作区、聊天频道和自动化任务上的开源 Agent 框架，你可以把它理解成一个「住在你机器里的 AI 助理调度中心」。它本身不训练模型，而是负责把模型、工具、频道、会话串起来。而openclaw onboard就是这套系统的第一次开机向导：它要问你模型走哪家、网关监听哪个端口、认证用明文还是引用、工作区放哪、要不要装守护进程。问题也恰恰出在这里——选项太多，第一次跑的人往往在「模型认证」和「网关认证」两处反复失败，最后连openclaw health都没见过一次成功输出。

这篇聚焦的正是这个首次初始化场景。我会把网关骨架和配置文件结构拆开讲，并且用 TaoToken 的统一 Key 作为模型接入通道，让你不用在 Anthropic、OpenAI、xAI 之间来回切密钥。适合谁：刚装完 OpenClaw、准备跑openclaw onboard、但不确定每个提示该怎么填的人；以及想把配置固化成可复制片段、方便以后重装或迁移的人。读完你应该能拿到一份能直接用的openclaw.json骨架、一条能验证网关连通的命令，以及一份常见报错对照表。

需要先说明一点：OpenClaw 的配置主文件是~/.openclaw/openclaw.json，不是config.toml。网上有些教程混用了别的工具命名，容易让人找错文件。本文所有片段都以openclaw.json为准，同时给出等价的settings.json风格写法供你对照。

2. TaoToken 前置：把统一 Key 和 API 通道准备好

在跑向导之前，先把「模型从哪来」这件事定下来。OpenClaw 支持自定义提供商，只要端点兼容 OpenAI 或 Anthropic 协议即可。TaoToken 提供的就是这样一个统一入口：你拿一个 Key，就能通过同一套 API 通道访问多种模型，省去在向导里逐个填各家密钥的麻烦。

你需要提前准备两样东西：

第一是 API Key。到控制台创建，地址是https://taotoken.net/api-keys。创建后复制保存，它只在生成时完整显示一次。

第二是确认 API 基地址。TaoToken 的 API 入口是https://taotoken.net/api，在 OpenClaw 里作为自定义提供商的baseUrl填入。注意这里不要带任何查询参数，保持干净的根路径。

如果你还想先确认模型能不能正常对话，可以到模型对话页面手动发一条消息试试，地址是https://taotoken.net/models。这一步不是必须的，但能帮你排除「Key 本身有问题」和「OpenClaw 配置有问题」这两类混淆。

提示：把 Key 写进配置文件属于明文存储。如果你在意这一点，向导支持--secret-input-mode ref引用模式，用环境变量代替明文。后文会给两种写法。

3. 可复制配置：openclaw.json 骨架与 settings.json 对照

先给结论：本地模式下，向导最终会往~/.openclaw/openclaw.json写入一批字段。你可以让向导自己生成，也可以先手写一份骨架再让向导「Modify」。手写的好处是字段可控，重装时直接覆盖。

下面是一份最小可用的openclaw.json，模型走 TaoToken 自定义提供商，网关开令牌认证：

{ "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "model": "taotoken/claude-sonnet" } }, "models": { "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "compatibility": "openai" } } }, "tools": { "profile": "coding" }, "gateway": { "mode": "local", "bind": "127.0.0.1", "port": 8787, "auth": { "mode": "token", "token": "本地生成的随机令牌" } }, "session": { "dmScope": "per-channel-peer" }, "skills": { "install": { "nodeManager": "npm" } } }

几个字段值得单独说。models.providers.taotoken.compatibility填openai表示按 OpenAI 兼容协议发请求；如果你的模型走 Anthropic 协议，改成anthropic。agents.defaults.model里的taotoken/前缀要和 providers 里的键名一致，否则向导的模型检查会报「未知模型」。gateway.bind保持127.0.0.1时也建议开令牌认证，这样本地 WebSocket 客户端仍须带令牌，避免同机其他进程随意连。

如果你更习惯settings.json风格（部分客户端会读这个文件名），等价写法如下，字段语义一致，只是嵌套层级按客户端约定调整：

{ "openclaw": { "workspace": "~/.openclaw/workspace", "provider": { "id": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "compatibility": "openai" }, "gateway": { "bind": "127.0.0.1", "port": 8787, "authMode": "token" } } }

用引用模式时，把apiKey换成环境变量引用，并在运行向导的 shell 里先导出变量：

export TAOTOKEN_API_KEY="sk-你的TaoToken密钥" openclaw onboard --secret-input-mode ref

非交互式场景下，自定义提供商的引用会写成{ source: "env", provider: "default", id: "TAOTOKEN_API_KEY" }这种结构，向导会做一次预检，确认变量名合法且当前环境非空，否则直接失败并让你重试。

4. 跑通初始化并验证网关连通

配置准备好后，正式跑向导。本地模式直接执行：

openclaw onboard

如果~/.openclaw/openclaw.json已存在，向导会问你 Keep / Modify / Reset。选 Modify 可以保留已有字段只改你要动的部分；选 Reset 会清掉配置和凭据，作用域默认是 config+creds+sessions，加--reset-scope full才会连工作区一起删。重置用的是 trash 命令，不是直接 rm，所以还有后悔余地。

非交互式一次性跑完，可以这样组合参数：

openclaw onboard \ --auth-choice custom-api-key \ --custom-base-url "https://taotoken.net/api" \ --custom-model-id "claude-sonnet" \ --custom-provider-id "taotoken" \ --custom-compatibility "openai" \ --gateway-token-ref-env TAOTOKEN_GATEWAY_TOKEN

注意--gateway-token-ref-env要求该环境变量在向导运行环境里非空，且不能和--gateway-token同时用。这一步是网关认证，和模型认证是两回事，别混。

向导跑完后，启动网关并做健康检查：

openclaw gateway start openclaw health

openclaw health会返回网关状态。想看得更细，用：

openclaw status --deep

它会在状态输出里附带网关健康探测结果。成功时你会看到网关处于运行态、认证模式为 token、模型提供商解析正常。如果模型检查阶段提示「缺少认证」，多半是apiKey没写对或环境变量没导出。

再补一条验证模型通道的命令，确认请求真的能打到 TaoToken：

openclaw models test --provider taotoken --model claude-sonnet

返回里出现正常的响应内容，就说明从 CLI 到网关再到模型通道整条链路是通的。

5. 本篇常见错排查

报错一：unknown model或模型检查警告。原因是agents.defaults.model的前缀和models.providers的键名不一致。检查两处是否都叫taotoken，大小写敏感。

报错二：gateway auth failed。网关令牌没对上。如果你用了--gateway-token-ref-env，确认变量在当前 shell 里echo有值；如果向导里选了明文令牌，确认客户端连接时带的是同一个。

报错三：config invalid, run openclaw doctor。配置里有已弃用字段或格式错误。先跑openclaw doctor，它会指出具体位置，修完再重跑向导。

报错四：非 loopback 绑定被拒。把gateway.bind改成0.0.0.0或具体网卡地址时，认证是强制要求，不能禁用。要么开令牌，要么开密码模式。

报错五：--custom-api-key快速失败。在 ref 模式下，内联密钥参数要求对应环境变量已设置。要么导出变量，要么改用明文模式。

报错六：守护进程装不上。macOS 用 LaunchAgent 需要用户已登录会话；无头运行要自己配 LaunchDaemon。Linux 和 WSL2 用 systemd 用户单元，向导会尝试loginctl enable-linger，可能提示 sudo 密码，它会先试不带 sudo。

报错七：Control UI 打不开。没检测到图形界面时，向导会打印 SSH 端口转发指令而不是开浏览器。资源缺失时它会尝试自动构建，回退方案是手动pnpm ui:build。

6. 后续怎么走：按你的场景选入口

初始化跑通只是起点。接下来看你主要拿 OpenClaw 干什么：

如果你在排障或做接入，重点是把 Key 和文档吃透，API Keys 管理在https://taotoken.net/api-keys，接入文档在https://taotoken.net/doc，两边对照着看能少走弯路。

如果你只是想先验证模型对话效果，直接到https://taotoken.net/models手动发消息，比在 CLI 里反复调参快得多。

如果你打算长期用 OpenClaw 做编码或跑 Agent 任务，建议上 Coding Plan，地址是https://taotoken.net/coding-plan，它更适合高频、长会话的使用方式，比按次调用省心。

我自己的习惯是：配置骨架手写一份存进 dotfiles，重装时直接覆盖再跑openclaw onboard --reset-scope config，只重置配置不碰工作区，几分钟就能恢复整套环境。