Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw onboard
用于本地或远程 Gateway 网关设置的交互式新手引导。
相关指南
CLI 新手引导中心
交互式 CLI 流程演练。
新手引导概览
OpenClaw 新手引导如何组合在一起。
CLI 设置参考
输出、内部机制和每步行为。
CLI 自动化
非交互式标志和脚本化设置。
macOS 应用新手引导
macOS 菜单栏应用的新手引导流程。
示例
--flow import 使用插件拥有的迁移提供商，例如 Hermes。它只会针对全新的 OpenClaw 设置运行；如果已有配置、凭据、会话，或工作区记忆/身份文件，请在导入前重置或选择全新设置。
--modern 会启动 Crestodian 对话式新手引导预览版。不使用
--modern 时，openclaw onboard 会保留经典新手引导流程。
对于明文私有网络 ws:// 目标（仅限受信任网络），请在新手引导进程环境中设置
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。
这个客户端侧传输协议应急开关没有对应的 openclaw.json 配置项。
非交互式自定义提供商：
--custom-api-key 在非交互式模式下是可选的。如果省略，新手引导会检查 CUSTOM_API_KEY。
OpenClaw 会自动将常见视觉模型 ID 标记为支持图像。对于未知的自定义视觉 ID，请传入 --custom-image-input；或传入 --custom-text-input 强制使用仅文本元数据。
LM Studio 在非交互式模式下也支持特定于提供商的密钥标志：
--custom-base-url 默认值为 http://127.0.0.1:11434。--custom-model-id 是可选的；如果省略，新手引导会使用 Ollama 的建议默认值。诸如 kimi-k2.5:cloud 的云模型 ID 在这里也可用。
将提供商密钥存储为引用，而不是明文：
--secret-input-mode ref 时，新手引导会写入由环境变量支持的引用，而不是明文密钥值。
对于由 auth-profile 支持的提供商，这会写入 keyRef 条目；对于自定义提供商，这会将 models.providers.<id>.apiKey 写为环境变量引用（例如 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }）。
非交互式 ref 模式契约：
- 在新手引导进程环境中设置提供商环境变量（例如
OPENAI_API_KEY）。 - 除非该环境变量也已设置，否则不要传入内联密钥标志（例如
--openai-api-key）。 - 如果传入了内联密钥标志但没有所需环境变量，新手引导会快速失败并给出指导。
--gateway-auth token --gateway-token <token>存储明文令牌。--gateway-auth token --gateway-token-ref-env <name>将gateway.auth.token存储为环境变量 SecretRef。--gateway-token和--gateway-token-ref-env互斥。--gateway-token-ref-env要求新手引导进程环境中存在非空环境变量。- 使用
--install-daemon时，当令牌认证需要令牌时，由 SecretRef 管理的 Gateway 网关令牌会被验证，但不会以解析后的明文形式持久化到 supervisor 服务环境元数据中。 - 使用
--install-daemon时，如果令牌模式需要令牌且配置的令牌 SecretRef 未解析，新手引导会关闭失败并给出修复指导。 - 使用
--install-daemon时，如果同时配置了gateway.auth.token和gateway.auth.password，并且gateway.auth.mode未设置，新手引导会阻止安装，直到显式设置模式。 - 本地新手引导会将
gateway.mode="local"写入配置。如果之后的配置文件缺少gateway.mode，请将其视为配置损坏或未完成的手动编辑，而不是有效的本地模式快捷方式。 - 当所选设置路径需要时，本地新手引导会安装选定的可下载插件。
- 远程新手引导只会写入远程 Gateway 网关的连接信息，不会安装本地插件包。
--allow-unconfigured是单独的 Gateway 网关运行时逃生口。它不表示新手引导可以省略gateway.mode。
- 除非传入
--skip-health，否则新手引导会等待本地 Gateway 网关可达后才成功退出。 --install-daemon会先启动托管 Gateway 网关安装路径。没有它时，你必须已经有一个本地 Gateway 网关在运行，例如openclaw gateway run。- 如果你只想在自动化中写入配置/工作区/bootstrap，请使用
--skip-health。 - 如果你自行管理工作区文件，请传入
--skip-bootstrap来设置agents.defaults.skipBootstrap: true，并跳过创建AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md和BOOTSTRAP.md。 - 在原生 Windows 上，
--install-daemon会先尝试 Scheduled Tasks，如果任务创建被拒绝，则回退到每用户 Startup-folder 登录项。
- 提示时选择 Use secret reference。
- 然后选择以下任一项：
- 环境变量
- 已配置的机密提供商（
file或exec）
- 新手引导会在保存引用前执行快速预检验证。
- 如果验证失败，新手引导会显示错误并允许你重试。
非交互式 Z.AI 端点选择
--auth-choice zai-api-key 会为你的密钥自动检测最佳 Z.AI 端点（优先使用带 zai/glm-5.1 的通用 API）。如果你明确想使用 GLM Coding Plan 端点，请选择 zai-coding-global 或 zai-coding-cn。流程说明
流程类型
流程类型
quickstart：最少提示，自动生成 Gateway 网关令牌。manual：端口、绑定和认证的完整提示（advanced的别名）。import：运行检测到的迁移提供商，预览计划，然后在确认后应用。
提供商预筛选
提供商预筛选
当认证选择隐含首选提供商时，新手引导会将默认模型和 allowlist 选择器预筛选到该提供商。对于 Volcengine 和 BytePlus，这也会匹配 coding-plan 变体（
volcengine-plan/*、byteplus-plan/*）。如果首选提供商筛选尚未产生任何已加载模型，新手引导会回退到未筛选目录，而不是让选择器为空。Web 搜索后续步骤
Web 搜索后续步骤
某些 Web 搜索提供商会触发特定于提供商的后续提示：
- Grok 可以使用相同的
XAI_API_KEY提供可选的x_search设置，以及一个x_search模型选择。 - Kimi 可以询问 Moonshot API 区域（
api.moonshot.ai与api.moonshot.cn）和默认 Kimi Web 搜索模型。
常用后续命令
--json 并不意味着非交互式模式。脚本请使用 --non-interactive。