入站向导参考

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

流程详情（本地模式）

- 如果 `~/.openclaw/openclaw.json` 存在，选择**保留 / 修改 / 重置**。 - 重新运行向导**不会**清除任何内容，除非你明确选择**重置**（或传递 `--reset`）。 - CLI `--reset` 默认为 `config+creds+sessions`；使用 `--reset-scope full` 也可删除工作区。 - 如果配置无效或包含旧密钥，向导会停止并要求你在继续之前运行 `openclaw doctor`。 - 重置使用 `trash`（而不是 `rm`）并提供范围： - 仅配置 - 配置 + 凭据 + 会话 - 完全重置（也删除工作区） - **Anthropic API 密钥（推荐）**：如果存在 `ANTHROPIC_API_KEY` 则使用它，或提示输入密钥，然后保存以供守护进程使用。 - **Anthropic OAuth（Claude Code CLI）**：在 macOS 上，向导检查 Keychain 项"Claude Code-credentials"（选择"始终允许"以使 launchd 启动不会阻塞）；在 Linux/Windows 上，如果存在则重用 `~/.claude/.credentials.json`。 - **Anthropic 令牌（粘贴 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` 则使用它，或提示输入密钥，然后将其存储在认证配置文件中。 - **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](/zh/docs/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**：提示输入账户 ID、网关 ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 - 详情请参阅：[Cloudflare AI Gateway](/zh/docs/providers/cloudflare-ai-gateway) - **MiniMax M2.1**：配置自动写入。 - 详情请参阅：[MiniMax](/zh/docs/providers/minimax) - **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。 - 详情请参阅：[Synthetic](/zh/docs/providers/synthetic) - **Moonshot（Kimi K2）**：配置自动写入。 - **Kimi Coding**：配置自动写入。 - 详情请参阅：[Moonshot AI（Kimi + Kimi Coding）](/zh/docs/providers/moonshot) - **跳过**：暂未配置认证。 - 从检测到的选项中选择默认模型（或手动输入提供商/模型）。 - 向导运行模型检查，如果配置的模型未知或缺少认证则发出警告。 - API 密钥存储模式默认为纯文本认证配置文件值。使用 `--secret-input-mode ref` 存储环境支持的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。 - OAuth 凭据存储在 `~/.openclaw/credentials/oauth.json`；认证配置文件存储在 `~/.openclaw/agents//agent/auth-profiles.json`（API 密钥 + OAuth）。 - 详情请参阅：[/zh/docs/concepts/oauth](/zh/docs/concepts/oauth) 无头/服务器提示：在一台有浏览器的机器上完成 OAuth，然后复制 `~/.openclaw/credentials/oauth.json`（或 `$OPENCLAW_STATE_DIR/credentials/oauth.json`）到 网关主机。 - 默认为 `~/.openclaw/workspace`（可配置）。 - 为 agent 引导仪式填充工作区所需的文件。 - 完整工作区布局 + 备份指南：[Agent 工作区](/zh/docs/concepts/agent-workspace) - 端口、绑定、认证模式、Tailscale 暴露。 - 认证建议：即使对环回也保持**令牌**，以便本地 WS 客户端必须认证。 - 仅在你完全信任每个本地进程时才禁用认证。 - 非环回绑定仍然需要认证。 - [WhatsApp](/zh/docs/channels/whatsapp)：可选 QR 登录。 - [Telegram](/zh/docs/channels/telegram)：机器人令牌。 - [Discord](/zh/docs/channels/discord)：机器人令牌。 - [Google Chat](/zh/docs/channels/googlechat)：服务账户 JSON + webhook 受众。 - [Mattermost](/zh/docs/channels/mattermost)（插件）：机器人令牌 + 基础 URL。 - [Signal](/zh/docs/channels/signal)：可选 `signal-cli` 安装 + 账户配置。 - [BlueBubbles](/zh/docs/channels/bluebubbles)：**iMessage 推荐**；服务器 URL + 密码 + webhook。 - [iMessage](/zh/docs/channels/imessage)：传统 `imsg` CLI 路径 + 数据库访问。 - DM 安全：默认是配对。第一个 DM 发送代码；通过 `openclaw pairing approve ` 批准或使用白名单。 - macOS：LaunchAgent - 需要已登录的用户会话；对于无头，请使用自定义 LaunchDaemon（不随附）。 - Linux（以及通过 WSL2 的 Windows）：systemd 用户单元 - 向导尝试通过 `loginctl enable-linger ` 启用 lingering，以便网关在注销后保持运行。 - 可能提示输入 sudo（写入 `/var/lib/systemd/linger`）；它首先尝试不带 sudo。 - **运行时选择：** Node（推荐；WhatsApp/Telegram 需要）。Bun **不推荐**。 - 启动网关（如需要）并运行 `openclaw health`。 - 提示：`openclaw status --deep` 将网关健康探测添加到状态输出（需要可访问的网关）。 - 读取可用技能并检查要求。 - 让你选择节点管理器：**npm / pnpm**（bun 不推荐）。 - 安装可选依赖项（有些在 macOS 上使用 Homebrew）。 - 摘要 + 下一步，包括用于额外功能的 iOS/Android/macOS 应用。 如果没有检测到 GUI，向导会打印 SSH 端口转发说明而不是打开浏览器。 如果缺少控制 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`）。 ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$ZAI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash 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 ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice cloudflare-ai-gateway-api-key \ --cloudflare-ai-gateway-account-id "your-account-id" \ --cloudflare-ai-gateway-gateway-id "your-gateway-id" \ --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ```

添加 agent（非交互式）

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

Signal 设置（signal-cli）

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

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

注意事项：

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

向导写入的内容

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果选择 Minimax）
  • 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 或本地路径）后才能配置。

相关文档