入门:CLI
CLI 引导式设置是 macOS、Linux 和 Windows(原生或 WSL2)上推荐的终端设置路径。在新安装时,快速开始会检测可用的 AI 接入方式,等待你选择连接,通过一次真实补全验证你的选择,并以前台 Gateway 打开 Web 仪表盘。自定义设置保留完整的引导流程。openclaw setup 运行相同的流程(设置 涵盖仅限配置的 --baseline 变体)。Windows 桌面用户也可以从 Windows Hub 开始。
引导式设置会在启动 Gateway 和 AI 聊天之前验证你选择的连接。检测到的连接与受支持的提供商共用同一个选择器;失败或取消绝不会自动选择另一个提供商。在本地引导中,暂时跳过会准备指定智能体的工作区和本地 Gateway 配置,然后退出且不启动其中任何一项。被中断的基线设置会在下次运行时恢复。本地设置摘要确认的是工作区和 Gateway 配置,而非可用的 AI 连接;推理就绪仅在所选连接通过验证后出现。
经典向导仍可用于远程 Gateway 设置、频道配对、守护进程控制、技能和导入。使用 openclaw onboard --classic 显式运行它;引导式推理选择器不会委托给它。推理通过后,OpenClaw 可以使用 open channel wizard for <channel> 将需要密钥的频道设置交给掩码终端向导。工作区技能和网页搜索以同样的对话方式配置:configure skills 和 configure web search 在聊天中承载这些设置流程,而 open search wizard 将凭据输入交给掩码终端向导。对于本地 Gateway,configure gateway 引导端口、绑定、认证和 Tailscale 设置,但仅保存配置而不重启;之后可以说 restart gateway,或使用 open gateway wizard 进行掩码终端凭据输入,然后运行 openclaw gateway restart。远程 Gateway 模式仍然是引导式设置或 openclaw configure 中的选择,而非托管聊天向导。
引导式设置创建默认智能体工作区后,import memory 可以将检测到的本地记忆复制到其中。这种对话式导入不会更改配置,也不会导入凭据或技能,无需重启 Gateway,并会如实报告每个来源的部分复制或复制失败情况。要更改模型提供商或其认证方式,请退出 OpenClaw 并运行 openclaw onboard;OpenClaw 不会打开引导式或经典提供商流程。
Info
在新安装时,运行 npx openclaw@latest 并选择快速开始以打开浏览器仪表盘。之后可使用 openclaw dashboard 重新打开。
文档:仪表盘。
区域设置¶
向导会对固定的引导文案进行本地化。它按顺序使用 OPENCLAW_LOCALE、LC_ALL、LC_MESSAGES 和 LANG 中第一个非空值,然后回退到英语。支持的区域设置:en、zh-CN、zh-TW。
OPENCLAW_LOCALE=zh-CN openclaw onboard
OPENCLAW_LOCALE=en openclaw onboard # Explicit English override
无论区域设置如何,产品名称、命令、配置键、URL、提供商 ID、模型 ID 以及插件/频道标签均保持英文。
之后要重新配置非推理设置:
Note
--json 并不表示非交互模式。对于脚本,请使用 --non-interactive(参见 CLI 自动化)。
Tip
经典向导包含一个网页搜索步骤,你可以在其中选择提供商:Brave、
DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web
Search、Perplexity、SearXNG 或 Tavily。有些需要 API 密钥,其他则无需密钥。
之后可以使用 openclaw configure --section web 进行配置,或在 OpenClaw 聊天中
说 configure web search,以对话方式运行相同的提供商设置。
文档:网页工具。
引导式默认流程¶
新安装时的本地交互式引导会在一行指向安全指南的提示之后,提供快速开始和自定义设置。快速开始会记录安全确认;自定义设置显示完整的安全说明并要求确认。默认情况下,快速开始使用智能体名称 main 和完全访问权限,将遥测同意保留为未设置,并跳过记忆导入和应用推荐。自定义设置保留遥测选择、智能体名称、访问模式和可选设置提示。两条路径都要求先明确选择提供商,然后才能进行实时补全或任何提供商安装、模型选择或凭据写入。
快速开始遵循以下路径:
- 在一行安全提示后选择快速开始。
- 检测已配置的模型、API 密钥环境变量、受支持的本地 AI CLI,以及 Gateway 主机上可访问的 Ollama 或 LM Studio 服务器中已安装且具备工具调用能力的模型。这一只读过程绝不会下载模型。当 Pi 和 OpenCode 安装无法充当可复用的推理路由时,它们也可能作为上下文信息被报告。Gemini CLI 和 Antigravity 不作为检测到的设置路由提供。
- 选择你想要的检测连接,或选择一个受支持的提供商。只有该连接会用一次真实补全进行测试。如果失败,请查看错误并选择是重试、选择另一个提供商还是跳过。
- 选择更多…以查看其他提供商组,包括可安装的官方插件。每个提供商的区域、套餐以及受支持的浏览器、设备、API 密钥或令牌方式都会出现在第二个菜单中。插件安装需要先完成其能力审查,然后所选提供商的设置才会继续。对于未列出的端点,请选择自定义提供商(如显示,位于更多…下方),并输入其基础 URL、可选 API 密钥、兼容性和模型 ID。自定义设置流程在 Gateway 主机上的本地 CLI 中运行,并在保存提供商或替换当前模型之前验证真实回复。选择暂时跳过以准备本地基线并退出,而不启动 Gateway 或 AI 聊天。通过其手动设置选择提供商会保留快速开始的默认设置:智能体名称
main、完全访问权限、遥测同意未设置,以及验证后在前台运行的 Gateway。 - 保存已验证的路由,准备智能体工作区,并持久化 Gateway 设置。
- 在前台启动 Gateway 并打开浏览器仪表盘。按 Ctrl+C 停止;配置会保留。之后可使用
openclaw gateway install进行后台运行,使用openclaw打开 TUI,或使用openclaw dashboard重新打开 Web UI。
对于已配置的安装、远程 Gateway 聊天设置、非交互式运行,或带有 --skip-ui 或 --tui 的运行,不会提供 Quick start(快速开始)选项。
在已配置的安装上重新运行该命令时,会首先提供当前默认模型。选择它即可进行一轮验证和修复。检查失败绝不会自动替换已配置的模型;引导式设置会等待你的下一次选择。如需后续进行非推理相关的添加,请运行 openclaw channels add 或 openclaw configure;如需更改提供商或认证方式,请使用 openclaw onboard。
选择一个智能体或一个团队¶
当引导式设置创建第一个智能体时,请选择 One agent(单个智能体)(默认)或 A small team: a chief of staff plus specialists(小型团队:一名幕僚长加多名专员)。团队选项使用与 openclaw agents team create 相同的预设:一名幕僚长(coordinator)、一名研究员、一名撰稿人和一名审核员,各自拥有独立的工作区、完整的身份信息和书面角色契约。幕僚长会分配合适的任务,并在向你汇报之前验证专员的工作成果。
引导式设置会在所选提供商通过连接检查后创建团队。如果检查失败,会返回提供商选择,且不会创建团队成员。选择 Skip(跳过) 会创建工作区以供后续使用,并提示 AI 访问仍需配置。引导式设置会在重启后记住所选的协调者,包括在提供商激活后、成员创建前发生中断的情况。
对于团队,--workspace 是父目录;每个成员使用 <workspace>/<agent-id>。在所有成员创建完成后,被中断的设置会将该父目录保留为恢复工作区。重试 openclaw onboard --workspace <workspace>(不带 --team)即可完成设置。在关闭设置回执之前,系统会检查完整的团队成员名单以及每个成员的工作区;如果团队不完整或发生变化,则会保持待处理状态并显示错误。
如果成员创建本身失败,已创建的成员会被保留,并且不会自动重新创建。请检查 openclaw agents list,并在重试设置前修复不完整的名单。
使用 --team 可在交互式或非交互式运行中直接选择团队:
常规的非交互式提供商和 Gateway 选项仍然适用。引导式设置会明确将协调者指定为聊天目标。仅当未配置环境所有者时,它才会将 agents.defaults.systemAgent.agentId 设置为协调者;已存在的所有者会被保留并报告。团队不会引入通用默认智能体,也不会更改全局委派或工具策略。如需在后续处理该问题,请使用显式目标:
--team 用于本地的首个智能体设置。它不能与远程、经典或导入式设置组合使用。如果已存在智能体名单,请改用 openclaw agents team create。
有关委派配置,请参阅团队预设;如需向现有安装添加命名空间团队,请参阅agents team create。
经典向导设置模式¶
运行 openclaw onboard --classic 可打开完整向导。其 Setup mode(设置模式) 菜单是根据当前安装情况构建的:
- 当没有配置默认模型时,默认选中 QuickStart(推荐),其后是 Manual setup(手动设置)。
- 当已配置默认模型时,Keep existing model config(保留现有模型配置) 会首先出现并默认选中,其后是 QuickStart(推荐) 和 Manual setup(手动设置)。
- 当存在可用的迁移提供商时,Import from another agent(从其他智能体导入) 会出现在设置选项之后。选择它会打开提供商特定的条目,例如 Import from Claude、Import from Codex 和 Import from Hermes。检测到的来源会优先显示并附带其路径;其他可用提供商则会要求输入来源路径。在导入开始前,可使用提供商列表中的 Back(返回)按钮回到 Setup mode(设置模式)。
使用 --flow quickstart 或 --flow manual(别名 advanced)可选择经典设置流程并跳过该提示。导入标志会直接选择导入流程,而不是显示一个可能丢弃所请求导入的菜单。
- 本地 Gateway,回环(loopback)绑定
- 默认工作区(或现有工作区)
- Gateway 端口 18789
- Gateway 认证 Token(自动生成,即使在回环模式下也会生成)
- 工具策略:当未配置 profile 时,使用
tools.profile: "full";显式配置的 profile 和其他策略会被保留。执行权限保持独立。请参阅工具配置文件。 - 私信(DM)会话:引导式设置会保留显式配置的
session.dmScope,否则保持未设置状态,因此"main"默认值会将所有频道中的私信保留在智能体的滚动主会话中——这是个人智能体的默认设置。对于共享或多用户收件箱,请使用"per-channel-peer";当openclaw security audit检测到多用户私信流量时,会建议进行隔离。详情:CLI 设置参考 - Tailscale 暴露 Off(关闭)
- Telegram 和 WhatsApp 的私信默认使用 allowlist(白名单):Telegram 会要求输入数字形式的 Telegram 用户 ID,WhatsApp 会要求输入手机号码
- 显示所有步骤:模式、工作区、Gateway、频道、守护进程、技能
远程模式(--mode remote)始终使用手动流程;它仅将本机配置为连接到其他位置的 Gateway,并且绝不会在远程主机上安装或更改任何内容。
经典引导式设置的配置内容¶
本地模式(默认)会依次执行以下步骤:
- Workspace(工作区) - 智能体文件的目录(默认
~/.openclaw/workspace)。会生成引导(bootstrap)文件。 - Model/Auth(模型/认证) - 选择提供商认证流程(API 密钥、OAuth 或提供商特定的手动认证),包括 Custom Provider(自定义提供商,支持 OpenAI 兼容、OpenAI Responses 兼容、Anthropic 兼容或 Unknown(未知)自动检测)。选择默认模型。全新的 OpenAI API 密钥和 ChatGPT/Codex 设置默认使用
openai/gpt-6-astra。纯直接 API 别名openai/gpt-5.6仍然受支持,并解析为 Sol。重新运行设置会保留现有的显式模型,包括openai/gpt-5.5。如果账户未开放 GPT-5.6,请显式选择openai/gpt-5.5。安全提示:如果此智能体将运行工具或处理 webhook/hook 内容,请优先使用可用的最强最新一代模型,并保持严格的工具策略——较弱或较旧的层级更容易受到提示注入(prompt injection)攻击。对于非交互式运行,--secret-input-mode ref会将新凭据存储为环境变量支持的引用(ref);添加凭据时需设置提供商的环境变量。现有的可解析命名配置文件及其env、file、exec或store引用会原样复用,无需重新写入凭据或设置额外的提供商环境变量。之前存储的明文不会被迁移;请参阅密钥管理。交互式密钥引用模式可以指向环境变量或已配置的提供商引用(file或exec),保存前会进行快速预检。完成模型/认证设置后,向导会提供可选的实时补全测试;测试失败可以返回模型/认证设置一次,也可以选择忽略,而不会阻塞经典向导的其余步骤。忽略该测试不会解锁 OpenClaw;对话式设置仍然需要通过推理检查。 - Gateway - 端口、绑定地址、密钥存储和 Tailscale 暴露。默认以 token 模式生成 Gateway 密钥,无需你选择 token 还是密码。现有的密码模式配置会被保留;
--gateway-auth password或--gateway-password <value>可显式选择密码模式。Tailscale Funnel 仍然要求使用密码模式。选择明文密钥存储(默认)或选择使用 SecretRef。非交互式 token SecretRef 路径:--gateway-token-ref-env <ENV_VAR>。 - Channels(频道) - 内置和官方插件的聊天频道,包括 Discord、Feishu、Google Chat、iMessage、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 等。当不存在命令所有者时,完成的频道设置会提供单独的操作员账户步骤,用于
/update和其他管理操作。输入你自己的用户 ID 并确认,或跳过。此功能适用于没有私信(DM)配对的服务器和群组,并且不会将聊天列入白名单。请参阅命令所有者设置。 - Web search(网络搜索) - 配置可选的搜索提供商。
- Skills(技能) - 安装推荐的技能及其可选依赖项。
- Daemon(守护进程) - 安装 LaunchAgent(macOS)、systemd 用户单元(Linux/WSL2)或原生 Windows 计划任务(Scheduled Task),并提供按用户的启动(Startup)文件夹回退方案。如果要求使用 token 认证,且
gateway.auth.token由 SecretRef 管理,守护进程安装会验证该 token,但不会将解析后的 token 持久化到 supervisor 服务环境元数据中;无法解析的 SecretRef 会阻止安装并给出指导。如果同时设置了gateway.auth.token和gateway.auth.password,而gateway.auth.mode未设置,则安装会被阻止,直到你显式设置该模式。 - Health check(健康检查) - 等待受管理的或临时会话 Gateway 启动,并验证其是否可访问。如果引导式设置未启动 Gateway,它会检查当前的可达性,并说明如何启动一个 Gateway,而不是等待引导式设置并未启动的服务。
Note
重新运行引导流程(onboarding)不会清除任何数据,除非你传入了 --reset。
重置(Reset)是一个命令行标志,而不是设置模式(Setup mode)菜单选项。
它默认清除配置、凭据和会话;使用 --reset-scope full 可同时移除工作区。
该命令会在将状态移至废纸篓(Trash)之前验证 TTY 可用性和可拒绝的 CLI 选项;
非交互式设置还要求先传入 --accept-risk。交互式经典设置会在显示风险确认
之前执行重置,而拒绝该提示并不会撤销重置。
迁移导入选项(--flow import、--import-from、--import-source
和 --import-secrets)不能与 --reset 组合使用;请在不带 --reset
的情况下运行导入。
如果不带 --reset,无效配置或旧版密钥会促使引导流程要求你先运行
openclaw doctor。
--flow import 会在经典向导中运行检测到的迁移流程(例如 Hermes),而不是进行全新设置;
参见 迁移 以及 安装 下的迁移指南。
openclaw onboard --modern 是 OpenClaw 的兼容别名。
它与 openclaw setup 使用相同的推理门控(inference gate):验证通过的推理会启动助手,
而交互式失败则会返回引导式推理设置。
添加另一个智能体¶
使用 openclaw agents add <name> 创建一个拥有独立工作区、会话和认证配置文件的智能体。
不带 --workspace 运行时,会启动一个交互式流程来设置名称、工作区、认证、通道和绑定
——它并不是完整的 openclaw onboard 向导。
它会设置以下项:
agents.entries.*.nameagents.entries.*.workspaceagents.entries.*.agentDir
注意:
- 默认工作区:
~/.openclaw/workspace-<agentId>(若已设置agents.defaults.workspace,则位于其下)。 - 添加
bindings以将入站消息路由到此智能体(引导流程可以帮你完成此项)。 - 非交互式标志:
--role、--model、--agent-dir、--bind、--non-interactive。使用--role时,--workspace可以省略。参见 角色模板。
完整参考¶
有关详细的逐步行为说明和配置输出,请参阅 CLI 设置参考。
有关非交互式示例,请参阅 CLI 自动化。
有关完整的标志参考,请参阅 openclaw onboard。
相关文档¶
- CLI 命令参考:
openclaw onboard - 引导流程概述:引导流程概述
- macOS 应用引导流程:引导流程
- 智能体首次运行仪式:智能体引导启动
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw