跳转至

入门:CLI

openclaw onboard

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 以及插件/频道标签均保持英文。

之后要重新配置非推理设置:

openclaw configure
openclaw agents add <name>

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 和完全访问权限,将遥测同意保留为未设置,并跳过记忆导入和应用推荐。自定义设置保留遥测选择、智能体名称、访问模式和可选设置提示。两条路径都要求先明确选择提供商,然后才能进行实时补全或任何提供商安装、模型选择或凭据写入。

快速开始遵循以下路径:

  1. 在一行安全提示后选择快速开始。
  2. 检测已配置的模型、API 密钥环境变量、受支持的本地 AI CLI,以及 Gateway 主机上可访问的 Ollama 或 LM Studio 服务器中已安装且具备工具调用能力的模型。这一只读过程绝不会下载模型。当 Pi 和 OpenCode 安装无法充当可复用的推理路由时,它们也可能作为上下文信息被报告。Gemini CLI 和 Antigravity 不作为检测到的设置路由提供。
  3. 选择你想要的检测连接,或选择一个受支持的提供商。只有该连接会用一次真实补全进行测试。如果失败,请查看错误并选择是重试、选择另一个提供商还是跳过。
  4. 选择更多…以查看其他提供商组,包括可安装的官方插件。每个提供商的区域、套餐以及受支持的浏览器、设备、API 密钥或令牌方式都会出现在第二个菜单中。插件安装需要先完成其能力审查,然后所选提供商的设置才会继续。对于未列出的端点,请选择自定义提供商(如显示,位于更多…下方),并输入其基础 URL、可选 API 密钥、兼容性和模型 ID。自定义设置流程在 Gateway 主机上的本地 CLI 中运行,并在保存提供商或替换当前模型之前验证真实回复。选择暂时跳过以准备本地基线并退出,而不启动 Gateway 或 AI 聊天。通过其手动设置选择提供商会保留快速开始的默认设置:智能体名称 main、完全访问权限、遥测同意未设置,以及验证后在前台运行的 Gateway。
  5. 保存已验证的路由,准备智能体工作区,并持久化 Gateway 设置。
  6. 在前台启动 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 可在交互式或非交互式运行中直接选择团队:

openclaw onboard --team
openclaw onboard --non-interactive --team --accept-risk

常规的非交互式提供商和 Gateway 选项仍然适用。引导式设置会明确将协调者指定为聊天目标。仅当未配置环境所有者时,它才会将 agents.defaults.systemAgent.agentId 设置为协调者;已存在的所有者会被保留并报告。团队不会引入通用默认智能体,也不会更改全局委派或工具策略。如需在后续处理该问题,请使用显式目标:

openclaw agent --agent coordinator --message "Research a topic and prepare a draft."

--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,并且绝不会在远程主机上安装或更改任何内容。

经典引导式设置的配置内容

本地模式(默认)会依次执行以下步骤:

  1. Workspace(工作区) - 智能体文件的目录(默认 ~/.openclaw/workspace)。会生成引导(bootstrap)文件。
  2. 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;对话式设置仍然需要通过推理检查。
  3. Gateway - 端口、绑定地址、密钥存储和 Tailscale 暴露。默认以 token 模式生成 Gateway 密钥,无需你选择 token 还是密码。现有的密码模式配置会被保留;--gateway-auth password 或 --gateway-password <value> 可显式选择密码模式。Tailscale Funnel 仍然要求使用密码模式。选择明文密钥存储(默认)或选择使用 SecretRef。非交互式 token SecretRef 路径:--gateway-token-ref-env <ENV_VAR>。
  4. Channels(频道) - 内置和官方插件的聊天频道,包括 Discord、Feishu、Google Chat、iMessage、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 等。当不存在命令所有者时,完成的频道设置会提供单独的操作员账户步骤,用于 /update 和其他管理操作。输入你自己的用户 ID 并确认,或跳过。此功能适用于没有私信(DM)配对的服务器和群组,并且不会将聊天列入白名单。请参阅命令所有者设置。
  5. Web search(网络搜索) - 配置可选的搜索提供商。
  6. Skills(技能) - 安装推荐的技能及其可选依赖项。
  7. 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 未设置,则安装会被阻止,直到你显式设置该模式。
  8. 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.*.name
  • agents.entries.*.workspace
  • agents.entries.*.agentDir

注意:

  • 默认工作区:~/.openclaw/workspace-<agentId>(若已设置 agents.defaults.workspace,则位于其下)。
  • 添加 bindings 以将入站消息路由到此智能体(引导流程可以帮你完成此项)。
  • 非交互式标志:--role、--model、--agent-dir、--bind、--non-interactive。使用 --role 时,--workspace 可以省略。参见 角色模板。

完整参考

有关详细的逐步行为说明和配置输出,请参阅 CLI 设置参考。 有关非交互式示例,请参阅 CLI 自动化。 有关完整的标志参考,请参阅 openclaw onboard。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw