入门向导（CLI）

入门向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。 它在一个引导流程中配置本地网关（Gateway）或远程网关连接，加上频道、技能和工作区默认值。

主要入口点：

openclaw onboard

最快的首次聊天：打开控制界面（Control UI）（无需频道设置）。运行 openclaw dashboard 并在浏览器中聊天。文档：Dashboard。

后续重新配置：

openclaw configure

推荐：设置 Brave Search API 密钥，以便代理可以使用 web_search （web_fetch 无需密钥即可工作）。最简单的方式：openclaw configure --section web 存储 tools.web.search.apiKey。文档：Web tools。

快速开始 vs 高级

向导从快速开始（默认值）vs 高级（完全控制）开始。

快速开始保持默认值：

  • 本地网关（回环）
  • 工作区默认值（或现有工作区）
  • 网关端口 18789
  • 网关认证 Token（自动生成，即使在回环上）
  • Tailscale 暴露 关闭
  • Telegram + WhatsApp 私信默认为 allowlist（会提示你输入电话号码）

高级暴露每个步骤（模式、工作区、网关、频道、守护进程、技能）。

向导做什么

**本地模式（默认）**引导你完成：

  • 模型/认证（OpenAI Code（Codex）订阅 OAuth、Anthropic API 密钥（推荐）或 setup-token（粘贴），加上 MiniMax/GLM/Moonshot/AI Gateway 选项）
  • 工作区位置 + 引导文件
  • 网关设置（端口/绑定/认证/tailscale）
  • 提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal）
  • 守护进程安装（LaunchAgent / systemd 用户单元）
  • 健康检查
  • 技能（推荐）

远程模式仅配置本地客户端以连接到其他地方的网关。 它不会在远程主机上安装或更改任何内容。

要添加更多隔离的代理（单独的工作区 + 会话 + 认证），使用：

openclaw agents add <name>

提示：--json 不意味着非交互模式。使用 --non-interactive（和 --workspace）用于脚本。

流程详情（本地）

  1. 现有配置检测

    • 如果 ~/.openclaw/openclaw.json 存在，选择 Keep / Modify / Reset。
    • 重新运行向导不会擦除任何内容，除非你明确选择 Reset （或传递 --reset）。
    • 如果配置无效或包含旧版密钥，向导停止并要求你在继续之前运行 openclaw doctor。
    • Reset 使用 trash（从不 rm）并提供范围：
      • 仅配置
      • 配置 + 凭据 + 会话
      • 完全重置（也删除工作区）

  2. 模型/认证

    • Anthropic API 密钥（推荐）：如果存在则使用 ANTHROPIC_API_KEY，或提示输入密钥，然后保存供守护进程使用。
    • Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导检查钥匙串项目"Claude Code-credentials"（选择"始终允许"以便 launchd 启动不会阻塞）；在 Linux/Windows 上，如果存在则重用 ~/.claude/.credentials.json。
    • Anthropic token（粘贴 setup-token）：在任何机器上运行 claude setup-token，然后粘贴令牌（你可以命名它；空白 = 默认）。
    • OpenAI Code（Codex）订阅（Codex CLI）：如果 ~/.codex/auth.json 存在，向导可以重用它。
    • OpenAI Code（Codex）订阅（OAuth）：浏览器流程；粘贴 code#state。
      • 当模型未设置或为 openai/* 时，将 agents.defaults.model 设置为 openai-codex/gpt-5.2。
    • OpenAI API 密钥：如果存在则使用 OPENAI_API_KEY，或提示输入密钥，然后保存到 ~/.openclaw/.env 以便 launchd 可以读取它。
    • OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取）。
    • API 密钥：为你存储密钥。
    • Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
    • 更多详情：Vercel AI Gateway
    • MiniMax M2.1：配置自动写入。
    • 更多详情：MiniMax
    • Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
    • 更多详情：Synthetic
    • Moonshot（Kimi K2）：配置自动写入。
    • Kimi Code：配置自动写入。
    • 更多详情：Moonshot AI (Kimi + Kimi Code)
    • Skip：尚未配置认证。
    • 从检测到的选项中选择默认模型（或手动输入 provider/model）。
    • 向导运行模型检查，并在配置的模型未知或缺少认证时发出警告。
  • OAuth 凭据位于 ~/.openclaw/credentials/oauth.json；认证配置文件位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 密钥 + OAuth）。
  • 更多详情：/concepts/oauth

  1. 工作区

    • 默认 ~/.openclaw/workspace（可配置）。
    • 为代理引导仪式种子所需的工作区文件。
    • 完整的工作区布局 + 备份指南：Agent workspace

  2. 网关（Gateway）

    • 端口、绑定、认证模式、tailscale 暴露。
    • 认证推荐：即使对于回环也保持 Token，以便本地 WS 客户端必须进行身份验证。
    • 仅当你完全信任每个本地进程时才禁用认证。
    • 非回环绑定仍需要认证。

  3. 频道（Channels）

  • WhatsApp：可选的二维码登录。
  • Telegram：机器人令牌。
  • Discord：机器人令牌。
  • Google Chat：服务账户 JSON + webhook audience。
  • Mattermost（插件）：机器人令牌 + 基础 URL。
  • Signal：可选的 signal-cli 安装 + 账户配置。
  • iMessage：本地 imsg CLI 路径 + DB 访问。
  • 私信安全：默认是配对。第一条私信发送代码；通过 openclaw pairing approve <channel> <code> 批准或使用白名单。

  1. 守护进程安装

    • macOS：LaunchAgent
      • 需要登录的用户会话；对于无头，使用自定义 LaunchDaemon（未发布）。
    • Linux（和 Windows 通过 WSL2）：systemd 用户单元
      • 向导尝试通过 loginctl enable-linger <user> 启用 lingering，以便网关在注销后保持运行。
      • 可能提示 sudo（写入 /var/lib/systemd/linger）；它首先尝试不使用 sudo。
    • 运行时选择： Node（推荐；WhatsApp/Telegram 必需）。不推荐 Bun。

  2. 健康检查

    • 启动网关（如果需要）并运行 openclaw health。
    • 提示：openclaw status --deep 向状态输出添加网关健康探测（需要可到达的网关）。

  3. 技能（推荐）

    • 读取可用技能并检查要求。
    • 让你选择节点管理器：npm / pnpm（不推荐 bun）。
    • 安装可选依赖项（一些在 macOS 上使用 Homebrew）。

  4. 完成

    • 摘要 + 下一步，包括用于额外功能的 iOS/Android/macOS 应用。
  • 如果未检测到 GUI，向导打印控制界面的 SSH 端口转发说明，而不是打开浏览器。
  • 如果控制界面资源缺失，向导尝试构建它们；后备是 pnpm ui:build（自动安装 UI 依赖项）。

远程模式

远程模式配置本地客户端以连接到其他地方的网关。

你将设置：

  • 远程网关 URL（ws://...）
  • 如果远程网关需要认证（推荐），则使用令牌

说明：

  • 不执行远程安装或守护进程更改。
  • 如果网关仅限回环，使用 SSH 隧道或 tailnet。
  • 发现提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

添加另一个代理

使用 openclaw agents add <name> 创建一个单独的代理，拥有自己的工作区、会话和认证配置文件。不使用 --workspace 运行会启动向导。

它设置什么：

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

说明：

  • 默认工作区遵循 ~/.openclaw/workspace-<agentId>。
  • 添加 bindings 来路由入站消息（向导可以做到这一点）。
  • 非交互式标志：--model、--agent-dir、--bind、--non-interactive。

非交互模式

使用 --non-interactive 自动化或脚本化入门：

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 用于机器可读的摘要。

Gemini 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI Gateway 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zen 示例：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

添加代理（非交互式）示例：

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

网关向导 RPC

网关通过 RPC 暴露向导流程（wizard.start、wizard.next、wizard.cancel、wizard.status）。 客户端（macOS 应用、控制界面）可以渲染步骤，而无需重新实现入门逻辑。

Signal 设置（signal-cli）

向导可以从 GitHub releases 安装 signal-cli：

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

说明：

  • JVM 构建需要 Java 21。
  • 在可用时使用原生构建。
  • Windows 使用 WSL2；signal-cli 安装遵循 WSL 内的 Linux 流程。

向导写入什么

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择了 Minimax）
  • gateway.*（模式、绑定、认证、tailscale）
  • channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
  • 频道白名单（Slack/Discord/Matrix/Microsoft Teams），当你在提示期间选择加入时（名称在可能时解析为 ID）。
  • skills.install.nodeManager
  • 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 或本地路径）。

相关文档

← 返回文档首页