{"id":271,"date":"2026-03-21T22:47:25","date_gmt":"2026-03-21T14:47:25","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/start-wizard\/"},"modified":"2026-03-21T23:23:48","modified_gmt":"2026-03-21T15:23:48","slug":"start-wizard","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/start-wizard\/","title":{"rendered":"CLI \u65b0\u624b\u5f15\u5bfc"},"content":{"rendered":"

CLI 新手引导<\/h1>\n

CLI 新手引导是在 macOS、
\nLinux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐<\/strong>方式。
\n它可在一次引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills
\n和工作区默认值。<\/p>\n

“`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\nopenclaw onboard<\/p>\n

\n<Info>\n  最快的首次聊天方式：打开 Control UI（无需设置渠道）。运行\n  `openclaw dashboard` 并在浏览器中聊天。文档：[Dashboard](\/web\/dashboard)。\n<\/Info>\n\n若要稍后重新配置：\n\n```bash  theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nopenclaw configure\nopenclaw agents add <name>\n<\/code><\/pre>\n
\n  --json<\/code> 并不意味着非交互模式。对于脚本，请使用 --non-interactive<\/code>。\n<\/p>\n
\n  CLI 新手引导包含一个 web search 步骤，你可以选择一个提供商
\n  （Perplexity、Brave、Gemini、Grok 或 Kimi），并粘贴你的 API 密钥，以便智能体
\n  可以使用 web_search<\/code>。你也可以稍后通过
\n  openclaw configure --section web<\/code> 进行配置。文档：Web 工具<\/a>。\n<\/p>\n
快速开始与高级模式<\/h2>\n
新手引导开始时会让你选择快速开始<\/strong>（默认值）或高级模式<\/strong>（完全控制）。<\/p>\n
    * 本地网关（loopback）
\n    * 默认工作区（或现有工作区）
\n    * Gateway 网关端口 18789<\/strong>
\n    * Gateway 网关认证 Token<\/strong>（即使在 loopback 上也会自动生成）
\n    * 新本地设置的默认工具策略：tools.profile: \"coding\"<\/code>（会保留现有显式配置文件）
\n    * 私信隔离默认值：本地新手引导会在未设置时写入 session.dmScope: \"per-channel-peer\"<\/code>。详情见：CLI 设置参考<\/a>
\n    * Tailscale 暴露 关闭<\/strong>
\n    * Telegram + WhatsApp 私信默认使用 allowlist<\/strong>（系统会提示你输入电话号码）\n  <\/p>\n
\n    * 暴露每一个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。<\/p>\n
新手引导会配置什么<\/h2>\n
**本地模式（默认）**会引导你完成以下步骤：<\/p>\n
    \n
  1. 模型\/认证<\/strong> —— 选择任意受支持的提供商\/认证流程（API 密钥、OAuth 或 setup-token），包括自定义提供商
    \n   （兼容 OpenAI、兼容 Anthropic，或未知自动检测）。选择一个默认模型。
    \n   安全说明：如果这个智能体将运行工具或处理 webhook\/hooks 内容，请优先选择当前可用的最强最新一代模型，并保持严格的工具策略。较弱\/较旧的层级更容易被 prompt 注入。
    \n   对于非交互式运行，--secret-input-mode ref<\/code> 会在认证配置文件中存储基于环境变量的引用，而不是明文 API 密钥值。
    \n   在非交互式 ref<\/code> 模式下，必须设置提供商环境变量；如果传入内联密钥标志但缺少该环境变量，则会快速失败。
    \n   在交互式运行中，选择 secret reference 模式后，你可以指向环境变量或已配置的 provider ref（file<\/code> 或 exec<\/code>），并在保存前进行快速预检校验。<\/li>\n
  2. 工作区<\/strong> —— 智能体文件的位置（默认 ~\/.openclaw\/workspace<\/code>）。会植入引导文件。<\/li>\n
  3. Gateway 网关<\/strong> —— 端口、绑定地址、认证模式、Tailscale 暴露。
    \n   在交互式 token 模式中，你可以选择默认的明文 token 存储，或选择启用 SecretRef。
    \n   非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR><\/code>。<\/li>\n
  4. 渠道<\/strong> —— WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。<\/li>\n
  5. 守护进程<\/strong> —— 安装 LaunchAgent（macOS）或 systemd 用户单元（Linux\/WSL2）。
    \n   如果 token 认证需要 token，且 gateway.auth.token<\/code> 由 SecretRef 管理，守护进程安装会验证它，但不会将已解析的 token 持久化到监督服务的环境元数据中。
    \n   如果 token 认证需要 token，而已配置的 token SecretRef 无法解析，守护进程安装会被阻止，并提供可执行的指导。
    \n   如果同时配置了 gateway.auth.token<\/code> 和 gateway.auth.password<\/code>，而 gateway.auth.mode<\/code> 未设置，守护进程安装会被阻止，直到显式设置 mode。<\/li>\n
  6. 健康检查<\/strong> —— 启动 Gateway 网关并验证其正在运行。<\/li>\n
  7. Skills<\/strong> —— 安装推荐的 Skills 和可选依赖项。<\/li>\n<\/ol>\n
    \n  重新运行新手引导不会<\/strong>清除任何内容，除非你显式选择 Reset<\/strong>（或传入 --reset<\/code>）。
    \n  CLI --reset<\/code> 默认会重置配置、凭证和会话；如需包含工作区，请使用 --reset-scope full<\/code>。
    \n  如果配置无效或包含旧版键，新手引导会先要求你运行 openclaw doctor<\/code>。\n<\/p>\n
    远程模式<\/strong>只会配置本地客户端以连接到其他地方的 Gateway 网关。
    \n它不会<\/strong>在远程主机上安装或更改任何内容。<\/p>\n
    添加另一个智能体<\/h2>\n
    使用 openclaw agents add <name><\/code> 创建一个单独的智能体，它拥有自己的工作区、
    \n会话和认证配置文件。不带 --workspace<\/code> 运行会启动新手引导。<\/p>\n
    它会设置：<\/p>\n