跳转到内容
OpenClaw Docs

新手引导参考

这是 openclaw onboardCLI 的完整参考。 有关高级概述，请参阅 新手引导 (CLI)。

流程详情（本地模式）

Section titled “流程详情（本地模式）”

  1. Existing config detection

    • 如果 ~/.openclaw/openclaw.json 存在，请选择 保留当前值、查看并更新 或 设置前重置。
    • 重新运行新手引导不会清除任何内容，除非您明确选择 重置 （或传递 --resetCLI）。
    • CLI --reset 默认为 config+creds+sessions；使用 --reset-scope full 同时移除工作区。
    • 如果配置无效或包含旧版密钥，向导将停止并要求 您在继续之前运行 openclaw doctor。
    • 重置使用 trash（绝不使用 rm）并提供作用域：
      • 仅配置
      • 配置 + 凭据 + 会话
      • 完全重置（同时移除工作区）

  2. Model/Auth

    • Anthropic API key：如果存在 ANTHROPIC_API_KEY 则使用它，否则提示输入密钥，然后将其保存以供守护进程使用。
    • Anthropic API key：在 新手引导/configure 中首选的 Anthropic 助手选择。
    • Anthropic setup-token：在 新手引导/configure 中仍然可用，尽管如果可用，OpenClaw 现在更倾向于重用 Claude CLI。
    • OpenAI Code (Codex) subscription (OAuth)：浏览器流程；粘贴 code#state。
      • 当模型未设置或已经是 OpenAI 系列时，通过 Codex 运行时将 agents.defaults.model 设置为 openai/gpt-5.5。
    • OpenAI Code (Codex) subscription (device pairing)：带有短期设备代码的浏览器配对流程。
      • 当模型未设置或已经是 OpenAI 系列时，通过 Codex 运行时将 agents.defaults.model 设置为 openai/gpt-5.5。
    • OpenAI API key：如果存在 OPENAI_API_KEY 则使用它，否则提示输入密钥，然后将其存储在身份验证配置文件中。
      • 当模型未设置、openai/* 或传统 Codex 模型引用时，将 agents.defaults.model 设置为 openai/gpt-5.5。
    • xAI (Grok) OAuth / API key：选择时使用 xAI OAuth 登录，或者在 API-key 路径上提示输入 XAI_API_KEY，并将 xAI 配置为模型提供商。
    • OpenCode：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取），并允许您选择 Zen 或 Go 目录。
    • Ollama：首先提供 Cloud + Local（云+本地）、Cloud only（仅云）或 Local only（仅本地）。Cloud only 提示输入 OLLAMA_API_KEY 并使用 https://ollama.com；主机支持的模式提示输入 Ollama 基础 URL，发现可用模型，并在需要时自动拉入选定的本地模型；Cloud + Local 还会检查该 Ollama 主机是否已登录以进行云访问。
    • 更多详情：Ollama
    • API key：为您存储密钥。
    • Vercel AI Gateway(网关) (multi-模型 proxy)：提示输入 AI_GATEWAY_API_KEY。
    • 更多详情：Vercel AI Gateway(网关)
    • Cloudflare AI Gateway(网关)：提示输入 Account ID、Gateway(网关) ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
    • 更多详情：Cloudflare AI Gateway(网关)
    • MiniMax：配置是自动写入的；托管默认值为 MiniMax-M3。 API-key 设置使用 minimax/...，而 OAuth 设置使用 minimax-portal/...。
    • 更多详情：MiniMax
    • StepFun：为中国或全球端点上的 StepFun 标准版或 Step Plan 自动写入配置。
    • 标准版目前包括 step-3.5-flash，Step Plan 还包括 step-3.5-flash-2603。
    • 更多详情：StepFun
    • Synthetic (Anthropic-compatible)：提示输入 SYNTHETIC_API_KEY。
    • 更多详情：Synthetic
    • Moonshot (Kimi K2)：配置是自动写入的。
    • Kimi Coding：配置是自动写入的。
    • 更多详情：Moonshot AI (Kimi + Kimi Coding)
    • Skip：尚未配置身份验证。
    • 从检测到的选项中选择默认模型（或手动输入提供商/模型）。为了获得最佳质量和更低的提示注入风险，请选择提供商堆栈中可用的最强大的最新一代模型。
    • 新手引导运行模型检查，如果配置的模型未知或缺少身份验证，则会发出警告。
    • API 密钥存储模式默认为纯文本身份验证配置文件值。请使用 --secret-input-mode ref 来存储环境支持的引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
    • 身份验证配置文件位于 `~/.openclaw/agents/

    /agent/auth-profiles.json（API 密钥 + OAuth）。~/.openclaw/credentials/oauth.json` 仅用于旧版导入。 - 更多详情：/concepts/oauth

  3. Workspace

    • 默认 ~/.openclaw/workspace（可配置）。
    • 为 agent bootstrap ritual 所需的工作区文件进行播种。
    • 完整的工作区布局 + 备份指南：Agent workspace

  4. Gateway(网关)Gateway

    • 端口、绑定、认证模式、Tailscale 暴露。
    • 认证建议：即使是环回地址也保留 Token，以便本地 WS 客户端必须进行认证。
    • 在 token 模式下，交互式设置提供：
      • 生成/存储纯文本 token（默认）
      • 使用 SecretRef（可选）
      • 快速启动会重用现有的 gateway.auth.token SecretRefs，跨越 env、file 和 exec 提供商，用于新手引导 probe/dashboard bootstrap。
      • 如果该 SecretRef 已配置但无法解析，新手引导会提前失败并给出明确的修复消息，而不是在运行时静默降低认证安全性。
    • 在密码模式下，交互式设置也支持纯文本或 SecretRef 存储。
    • 非交互式 token SecretRef 路径：`—gateway-token-ref-env

    。 - 需要在新手引导流程环境中有一个非空的 环境变量。 - 不能与 —gateway-token` 结合使用。 - 仅当您完全信任每个本地进程时才禁用认证。 - 非环回绑定仍然需要认证。

  5. Channels

    • WhatsApp: 可选的 QR 登录。
    • Telegram: 机器人令牌。
    • Discord: 机器人令牌。
    • Google Chat: 服务账户 JSON + Webhook 受众。
    • Mattermost (插件): 机器人令牌 + 基础 URL。
    • Signal: 可选的 signal-cli 安装 + 账户配置。
    • iMessage: imsg CLIGateway(网关) 路径 + Messages 数据库访问权限；当 Gateway(网关) 在 Mac 以外运行时，请使用 SSH 封装器。
    • 私信安全：默认为配对。第一条私信会发送一个代码；通过 `openclaw pairing approve

    ` 批准或使用允许列表。

非交互模式

Section titled “非交互模式”

使用 --non-interactive 自动化或编写新手引导脚本：

Terminal window
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

添加 --json 以获取机器可读的摘要。

非交互模式下的 Gateway(网关) token SecretRef：

Terminal window
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

--gateway-token 和 --gateway-token-ref-env 互斥。

特定于提供商的命令示例位于 CLI 自动化 中。 请使用此参考页面了解标志语义和步骤顺序。

添加代理（非交互模式）

Section titled “添加代理（非交互模式）”
Terminal window
openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.5 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway(网关)向导 RPC

Section titled “Gateway(网关)向导 RPC”

Gateway 通过 RPC (Gateway(网关)RPCwizard.start, wizard.next, wizard.cancel, wizard.statusmacOS) 公开了新手引导流程。 客户端（macOS 应用、控制 UI）可以在不重新实现新手引导逻辑的情况下呈现步骤。

Signal 设置 (signal-cli)

Section titled “Signal 设置 (signal-cli)”

新手引导可以从 GitHub 发行版安装 signal-cliGitHub：

  • 下载适当的版本资产。
  • 将其存储在 ~/.openclaw/tools/signal-cli/<version>/ 下。
  • 将 channels.signal.cliPath 写入您的配置。

注意事项：

  • JVM 版本需要 Java 21。
  • 尽可能使用 Native 版本。
  • Windows 使用 WSL2；signal-cli 安装遵循 WSL 内部的 Linux 流程。

向导写入的内容

Section titled “向导写入的内容”

~/.openclaw/openclaw.json 中的典型字段：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择了 Minimax）
  • tools.profile（如果未设置，本地新手引导默认为 "coding"；保留现有的显式值）
  • gateway.*（mode, bind, auth, tailscale）
  • session.dmScopeCLI（行为详情：CLI 设置参考）
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • 频道允许列表（Slack/Discord/Matrix/Microsoft Teams），当您在提示期间选择加入时（名称尽可能解析为 ID）。
  • skills.install.nodeManager
    • setup --node-manager 接受 npm、pnpm 或 bun。
    • 手动配置仍可通过直接设置 skills.install.nodeManager 来使用 yarn。
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode

openclaw agents add 写入 agents.list[] 和可选的 bindings。

WhatsApp 凭据位于 ~/.openclaw/credentials/whatsapp/<accountId>/ 之下。 会话存储在 ~/.openclaw/agents/<agentId>/sessions/ 之下。

某些渠道以插件形式提供。当你在设置过程中选择一个时，新手引导 将提示安装它（npm 或本地路径），然后才能进行配置。

相关文档

Section titled “相关文档”