OpenClaw openclaw configure 交互式配置向导实战指南：凭证、网关、渠道与智能体默认值一站式设置

导读

openclaw configure 是 OpenClaw 提供的一套交互式配置向导（interactive setup wizard），用于通过终端提示（prompt）逐步设置模型凭证、网关（Gateway）运行方式、渠道（Channels）连接、智能体工作区与默认模型等核心配置。本文以官方 CLI 参考文档为主体，结合仓库内 commands/configure.wizard.ts 等源码实现，完整讲解向导的 8 个配置分区（section）、--section 定向配置、与 openclaw config 的互补关系，以及网关端口/绑定/认证/Tailscale 等底层参数的实际落盘逻辑，帮助你在不手改 openclaw.json 的情况下完成绝大多数日常配置。

一、openclaw configure 是什么

openclaw configure 是一个交互式提示向导，用于设置：

• 凭证（credentials）：模型提供方（provider）的 API Key、OAuth 等认证信息；
• 设备（devices）：节点（node）、摄像头等设备相关配置；
• 智能体默认值（agent defaults）：默认模型、默认工作区、模型允许列表等。

运行后你会看到基于 clack prompts 构建的交互式菜单（源码见 commands/configure.shared.ts），每一步选择都会被合并写入配置文件并持久化。

与 openclaw config 的关系：不带子命令的 openclaw config 会打开同一个向导（源码层面二者都调用 runConfigureWizard，见 commands/configure.commands.ts）。而 openclaw config get|set|unset 则用于非交互式按路径读写配置值，适合脚本化与批量修改，详见 Config CLI 参考。

基本用法

# 启动完整向导
openclaw configure

# 只配置模型与渠道两个分区，其余跳过
openclaw configure --section models --section channels

向导启动后会先探测本机与远端网关的可达性（probeGatewayReachable，实现见 commands/onboard-helpers.ts），并读取现有配置快照：若配置文件已存在且有效，会先汇总展示当前配置；若配置无效，会提示先运行 openclaw doctor 修复后再继续（见 commands/configure.wizard.ts）。

二、向导的 8 个配置分区（Section）

交互式向导的核心是一个"选择要配置的分区"菜单，仓库中定义的分区列表为（见 commands/configure.shared.ts）：

分区值	菜单标签	提示（hint）	作用
workspace	Workspace	Set workspace + sessions	设置智能体工作区目录并初始化 sessions
model	Model	Pick provider + credentials	选择模型提供方并配置凭证、默认模型与允许列表
web	Web tools	Configure web search (Perplexity/Brave) + fetch	开关 web_search 与 web_fetch 工具
gateway	Gateway	Port, bind, auth, tailscale	配置网关端口、绑定模式、认证与 Tailscale 暴露
daemon	Daemon	Install/manage the background service	安装/重启/重装后台网关服务
channels	Channels	Link WhatsApp/Telegram/etc and defaults	链接/移除各渠道并设置默认账户
skills	Skills	Install/enable workspace skills	安装或启用工作区技能
health	Health check	Run gateway + channel checks	运行网关与渠道健康检查

用户选择某个分区后，向导执行对应逻辑（configureWorkspace、promptAuthConfig、promptWebToolsConfig、promptGatewayConfig、configureChannelsSection、setupSkills、maybeInstallDaemon、runGatewayHealthCheck），并在每步完成后立即写回配置（见 commands/configure.wizard.ts）。

菜单最后始终提供 "Continue"（继续） 选项：hint 会根据是否已做过选择显示 "Done" 或 "Skip for now"（见 commands/configure.wizard.ts）。如果未选择任何分区直接继续，向导会原样退出并提示 "No changes selected."。

三、Gateway 网关位置：始终更新 gateway.mode

向导第一步（交互模式）或 gateway 分区都会询问 "Where will the Gateway run?"，提供两个选项：

• Local (this machine)：本地运行。若检测到 ws://127.0.0.1:18789 可达，会显示 "Gateway reachable"，否则显示 "No gateway detected"。
• Remote (info-only)：远端网关。仅在配置了 gateway.remote.url 时可用，并会实时探测远端是否可达。

注意：选择 Gateway 运行位置始终会更新 gateway.mode。如果你只需要把模式从 remote 切回 local，可以不选择其他分区、直接选择 "Continue"——向导会落盘 gateway.mode: "local" 并提示 "Gateway mode set to local."（见 commands/configure.wizard.ts 与 commands/configure.wizard.ts）。远端模式下的配置流程由 promptRemoteGatewayConfig 处理，仅需填写远端 URL 与 token 等信息即完成。

四、gateway 分区：端口、绑定、认证与 Tailscale

选择 gateway 分区后，向导依次引导完成以下配置（完整实现见 commands/configure.gateway.ts）：

1. 端口（Gateway port）

默认值取自现有配置（resolveGatewayPort(cfg)，未配置时使用默认端口 18789）。输入非数字会被校验拦截（validate: (value) => (Number.isFinite(Number(value)) ? undefined : "Invalid port")）。

2. 绑定模式（bind）

提供 5 种绑定选项，向导会对每个选项显示安全提示：

选项	含义	说明
loopback	Loopback (Local only)	绑定 127.0.0.1，仅本机访问，最安全
tailnet	Tailnet (Tailscale IP)	仅绑定 Tailscale 分配的 100.x.x.x 地址
auto	Auto (Loopback → LAN)	优先 loopback，不可用时回退到所有网卡
lan	LAN (All interfaces)	绑定 0.0.0.0，局域网内任意设备可访问
custom	Custom IP	手动指定 IP（如 192.168.1.100），校验为合法 IPv4；不可用时回退 0.0.0.0

选择 custom 后需要继续输入具体 IP 地址（校验函数见 shared/net/ipv4.ts 中的 validateIPv4AddressInput），该值会写入 gateway.customBindHost。

3. 认证方式（auth）

网关认证提供 3 种模式：

• Token（推荐默认）：gateway.auth.mode: "token"。默认会自动生成随机 token（randomToken()，见 commands/onboard-helpers.ts），也可以选择 SecretRef 模式，将 token 存为环境变量引用（默认环境变量名 OPENCLAW_GATEWAY_TOKEN），而不是明文写入配置文件。向导会实时校验该环境变量当前会话中是否存在且非空。
• Password：设置 gateway.auth.password，用于 Web UI / 控制界面登录等场景。
• Trusted Proxy：适用于反向代理认证（Pomerium、Caddy + OAuth、Traefik + forward auth 等）。需要依次填写：用户身份 Header（默认 x-forwarded-user）、必需的额外 Header（逗号分隔，可选）、允许的用户列表（逗号分隔，空则放行所有已认证用户）、以及至少一个受信任代理 IP。对应配置结构为 gateway.auth.trustedProxy.userHeader/requiredHeaders/allowUsers 与 gateway.trustedProxies。

4. Tailscale 暴露

选项	含义
off	不启用 Tailscale 暴露
serve	通过 Tailscale Serve 提供私密 HTTPS，仅 tailnet 内设备可访问
funnel	通过 Tailscale Funnel 提供公网 HTTPS

源码中有几条自动修正规则（见 commands/configure.gateway.ts）：

• 启用 Tailscale 时若绑定模式不是 loopback，会自动将 bind 调整为 loopback（Tailscale 要求 loopback 绑定）；
• 选择 funnel 时若认证方式不是 password，会自动切换为 password（Funnel 要求密码认证）；
• 选择 trusted-proxy 认证与 Tailscale serve/funnel 冲突，会自动关闭 Tailscale；
• 启用 Tailscale 时会检测 tailscale 二进制是否可用（findTailscaleBinary），不可用会给出警告，并询问是否在退出时重置 serve/funnel；
• 若选择了 serve/funnel，向导会自动把 Tailnet 的 HTTPS origin 追加到 gateway.controlUi.allowedOrigins（见 gateway/gateway-config-prompts.shared.ts）。

这些参数最终都会写入 gateway.port、gateway.bind、gateway.auth.*、gateway.tailscale.* 等配置项。

五、model 分区：凭证、默认模型与允许列表

model 分区由 promptAuthConfig 驱动（见 commands/configure.gateway-auth.ts），流程为：

1. 选择认证提供方：通过分组选择器列出可用提供方（含插件提供方），可选择跳过（skip）或自定义 API Key（custom-api-key）。
2. 设置默认模型：若未选择具体提供方，会进入 promptDefaultModel（实现见 flows/model-picker.ts）——从模型目录（catalog）中按提供方过滤选择，支持 "Keep current" 保留当前值，也支持手动输入 provider/model 格式；模型选项会附带上下文窗口大小（如 ctx 200K）、reasoning 能力、别名等信息，未配置认证的提供方会标记 auth missing。
3. 配置模型允许列表：这是文档特别强调的新增能力——model 分区现在包含一个用于 agents.defaults.models 允许列表（allowlist）的多选项（multi-select），它决定 /model 命令和模型选择器中展示哪些模型。选择结果会：
   • 写入 agents.defaults.models（以 provider/model 为键，结构见 applyModelAllowlist，flows/model-picker.ts）；
   • 若选中的模型多于 1 个，还会自动为默认模型生成 fallbacks 回退列表（applyModelFallbacksFromSelection，flows/model-picker.ts），实现模型故障转移；
   • 选择"清空允许列表"则移除 agents.defaults.models，恢复展示全部模型。

六、channels 分区：渠道连接与允许列表

进入 channels 分区后，向导先展示当前各渠道状态（noteChannelStatus），再让你选择模式：

• Configure/link（默认）：进入渠道配置流程（setupChannels），可添加/更新渠道，并支持禁用未选择的账户（allowDisable: true）。
• Remove channel config：进入移除模式（removeChannelConfigWizard，见 commands/configure.channels.ts），从 openclaw.json 中删除指定渠道的 token 与设置（磁盘上的凭证文件不会被删除）。

关键提示（来自官方文档）：面向渠道的服务（Slack / Discord / Matrix / Microsoft Teams 等）在设置期间会提示输入频道/房间允许列表（channel/room allowlist）。你可以输入名称或 ID；向导会尽可能把名称解析为 ID 后写入配置。若 openclaw.json 中没有任何渠道配置，移除模式会提示改用 openclaw channels status 查看已配置与已启用的渠道。

七、daemon 与 health 分区

• daemon 分区：用于安装/管理后台网关服务（maybeInstallDaemon，见 commands/configure.daemon.ts）。如果服务已安装，可选择 Restart / Reinstall / Skip；若未安装，会先选择服务运行时（当前仅有 node 一个选项，标注为推荐，见 commands/daemon-runtime.ts），然后构建安装计划并执行安装。Linux 上安装的是 systemd user 服务，安装完成后会交互式确认启用 linger（否则注销/空闲时 systemd 会停止用户会话并杀掉网关）。
• health 分区：调用 runGatewayHealthCheck，先等待网关可达（最多 15 秒，见 commands/onboard-helpers.ts），再执行 healthCommand 做全面健康检查，失败时给出排查文档提示。

八、web 与 workspace 分区

• web 分区：分别确认是否启用 web_search 与 web_fetch。启用搜索时，若当前插件策略下没有任何可用的搜索提供方，会提示 "Enable plugins or remove deny rules, then rerun configure" 并自动保持禁用；否则进入搜索提供方选择流程（setupSearch，支持 Perplexity/Brave 等）。web_fetch 为无密钥 HTTP 抓取，默认启用。
• workspace 分区：设置工作区目录（默认值来自 agents.defaults.workspace，否则使用系统默认工作区）。若当前尚无配置文件，向导会检测目标目录是否已存在 MEMORY.md/memory/.git 等标识；检测到已有内容时会提示"现有文件会被保留，缺失模板会被创建但绝不覆盖"（见 commands/configure.wizard.ts），随后执行 ensureWorkspaceAndSessions 初始化。

九、--section 定向配置与退出行为

--section 参数

openclaw configure --section <name> 支持多次指定，用于跳过菜单、直接按顺序执行指定分区（解析逻辑见 commands/configure.commands.ts）：

# 只配置模型与渠道
openclaw configure --section model --section channels

# 只配置网关与健康检查
openclaw configure --section gateway --section health

• 合法的分区值为：workspace、model、web、gateway、daemon、channels、skills、health；
• 传入了非法分区名时，命令会报错退出：Invalid --section: <name>. Expected one of: ...；
• 传入的 --section 为空（一个都没给）时，回退为运行完整向导。

在 --section 模式下，daemon 分区若之前未选择 gateway，会额外询问服务端口；health 分区使用当前配置的网关端口执行检查。

退出与取消

• 全部完成时，向导会输出 Control UI 的 Web UI 地址与 WebSocket 地址，并显示 Gateway: reachable / not detected 状态行（见 commands/configure.wizard.ts）；
• 任意一步按 Ctrl+C / Esc 取消（抛出 WizardCancelledError）都会以退出码 1 结束，不会写入半成品配置（见 commands/configure.wizard.ts）。

十、配置落盘与后续操作

向导每一步写回的都是同一个 openclaw.json 配置文件（写入前会调用 applyWizardMetadata 标记来源命令与网关模式，再经 writeConfigFile 落盘，见 commands/configure.wizard.ts）。修改配置后通常需要重启 Gateway 网关使配置生效（这与 Config CLI 文档的提示一致）。

若你在使用向导时遇到配置校验问题，可使用 openclaw doctor 修复；需要按路径精确读写单个配置项（如 gateway.port、agents.defaults.heartbeat.every、channels.whatsapp.groups），可参考 Config CLI 文档 中 get/set/unset 的用法；网关配置的完整参考见 Gateway 配置文档。

总结

openclaw configure 将 OpenClaw 最高频的配置项封装为可交互、可校验、可定向执行的向导：

• 一次运行完成凭证、网关、渠道、工作区、技能与健康检查的全部配置；
• --section 支持只处理你关心的分区，适合快速调整；
• gateway.mode 自动更新的语义，让"切换本地/远端"成为最轻量的操作；
• 模型允许列表（agents.defaults.models）多选、自动 fallbacks、Tailscale 自动绑定修正等细节，均由源码级校验保证配置一致性。

掌握它之后，绝大多数配置调整都可以在终端内交互完成，无需手工编辑 JSON 配置文件。