1. 为什么第一次跑 OpenClaw CLI 总卡在 onboardOpenClaw 是一个把大模型能力接到本地工作区、聊天频道和自动化任务上的开源 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_KEYsk-你的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 会清掉配置和凭据作用域默认是 configcredssessions加--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 healthopenclaw health会返回网关状态。想看得更细用openclaw status --deep它会在状态输出里附带网关健康探测结果。成功时你会看到网关处于运行态、认证模式为 token、模型提供商解析正常。如果模型检查阶段提示「缺少认证」多半是apiKey没写对或环境变量没导出。再补一条验证模型通道的命令确认请求真的能打到 TaoTokenopenclaw 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只重置配置不碰工作区几分钟就能恢复整套环境。