OpenClaw 🦞

入职向导参考

入职向导参考

这是 openclaw onboard CLI 向导的完整参考。 有关高级概述，请参阅 入职向导。

流程详细信息（本地模式）

1

现有配置检测

  • 如果 ~/.openclaw/openclaw.json 存在，选择 保留 / 修改 / 重置。
  • 重新运行向导不会擦除任何内容，除非您明确选择 重置 （或传递 --reset）。
  • CLI --reset 默认为 config+creds+sessions；使用 --reset-scope full 还可以删除工作区。
  • 如果配置无效或包含传统密钥，向导会停止并要求您先运行 openclaw doctor。
  • 重置使用 trash（从不使用 rm）并提供范围：
    • 仅配置
    • 配置 + 凭据 + 会话
    • 完全重置（还删除工作区）
2

模型/认证

  • Anthropic API 密钥：如果存在则使用 ANTHROPIC_API_KEY，或提示输入密钥，然后保存以供守护进程使用。
  • Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导检查 Keychain 项 "Claude Code-credentials"（选择"始终允许"以便 launchd 启动不会阻塞）；在 Linux/Windows 上，如果存在则重用 ~/.claude/.credentials.json。
  • Anthropic 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，或提示输入密钥，然后将其存储在认证配置文件中。
  • xAI（Grok）API 密钥：提示输入 XAI_API_KEY 并将 xAI 配置为模型提供者。
  • OpenCode Zen（多模型代理）：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 获取）。
  • API 密钥：为您存储密钥。
  • Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
  • 更多详情：Vercel AI Gateway
  • Cloudflare AI Gateway：提示输入账户 ID、网关 ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
  • 更多详情：Cloudflare AI Gateway
  • MiniMax M2.5：配置自动写入。
  • 更多详情：MiniMax
  • Synthetic（Anthropic 兼容）：提示输入 SYNTHETIC_API_KEY。
  • 更多详情：Synthetic
  • Moonshot（Kimi K2）：配置自动写入。
  • Kimi Coding：配置自动写入。
  • 更多详情：Moonshot AI（Kimi + Kimi Coding）
  • 跳过：尚未配置认证。
  • 从检测到的选项中选择默认模型（或手动输入提供者/模型）。为了获得最佳质量和较低的提示注入风险，请选择提供者堆栈中可用的最强最新一代模型。
  • 向导运行模型检查，并在配置的模型未知或缺少认证时发出警告。
  • API 密钥存储模式默认为纯文本认证配置文件值。使用 --secret-input-mode ref 存储环境支持的引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
  • OAuth 凭据位于 ~/.openclaw/credentials/oauth.json；认证配置文件位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 密钥 + OAuth）。
  • 更多详情：/concepts/oauth

无头/服务器提示：在带有浏览器的机器上完成 OAuth，然后将 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）复制到 网关主机。

3

工作区

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

网关

  • 端口、绑定、认证模式、tailscale 暴露。
  • 认证建议：即使对于环回也保持 令牌，以便本地 WS 客户端必须进行认证。
  • 仅当您完全信任每个本地进程时才禁用认证。
  • 非环回绑定仍然需要认证。
5

渠道

  • WhatsApp：可选 QR 登录。
  • Telegram：机器人令牌。
  • Discord：机器人令牌。
  • Google Chat：服务账户 JSON + webhook 受众。
  • Mattermost（插件）：机器人令牌 + 基础 URL。
  • Signal：可选 signal-cli 安装 + 账户配置。
  • BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook。
  • iMessage：传统 imsg CLI 路径 + DB 访问。
  • DM 安全：默认为配对。第一条 DM 发送代码；通过 openclaw pairing approve <channel> <code> 批准或使用允许列表。
6

守护进程安装

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

健康检查

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

技能（推荐）

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

完成

  • 摘要 + 下一步，包括用于额外功能的 iOS/Android/macOS 应用。

如果未检测到 GUI，向导会打印 SSH 端口转发说明以用于 Control UI，而不是打开浏览器。 如果 Control UI 资产丢失，向导会尝试构建它们；回退是 pnpm ui:build（自动安装 UI 依赖项）。

非交互模式

使用 --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 以获得机器可读的摘要。

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

添加代理（非交互模式）

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 应用、Control UI）可以渲染步骤而无需重新实现入职逻辑。

Signal 设置（signal-cli）

向导可以从 GitHub 发布版安装 signal-cli：

  • 下载适当的发布版资产。
  • 将其存储在 ~/.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）
  • tools.profile（本地入职在未设置时默认为 "messaging"；保留现有的显式值）
  • gateway.*（模式、绑定、认证、tailscale）
  • session.dmScope（行为详细信息：CLI 入职参考）
  • 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 或本地路径）。

相关文档