OpenClaw新手引导向导设置方法

新手引导向导（CLI）

新手引导向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。 它可以在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills 和工作区默认值。 主要入口：

最快开始聊天的方式：打开控制界面（无需设置渠道）。运行openclaw dashboard并在浏览器中聊天。文档：控制面板。 后续重新配置：

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

快速开始 vs 高级

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

• 本地 Gateway 网关（loopback）
• 默认工作区（或现有工作区）
• Gateway 网关端口18789
• Gateway 网关认证Token（自动生成，即使在 loopback 上）
• Tailscale 暴露关闭
• Telegram + WhatsApp 私信默认使用允许列表（系统会提示你输入电话号码）

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

向导做了什么

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

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

远程模式仅配置本地客户端连接到其他位置的 Gateway 网关。 它不会在远程主机上安装或更改任何内容。 要添加更多隔离的智能体（独立的工作区 + 会话 + 认证），使用：

openclaw agents add <name

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

流程详情（本地）

1. 现有配置检测
• 仅配置
• 配置 + 凭证 + 会话
• 完全重置（同时删除工作区）
• 如果~/.openclaw/openclaw.json存在，选择保留 / 修改 / 重置。
• 重新运行向导不会清除任何内容，除非你明确选择重置（或传递--reset）。
• 如果配置无效或包含遗留键名，向导会停止并要求你在继续之前运行openclaw doctor。
• 重置使用trash（永不使用rm）并提供范围选项：
2. 模型/认证
• 当模型未设置或为openai/*时，将agents.defaults.model设置为openai-codex/gpt-5.2。
• Anthropic API 密钥（推荐）：如果存在则使用ANTHROPICAPIKEY，否则提示输入密钥，然后保存供守护进程使用。
• Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导检查钥匙串项目”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 API 密钥：如果存在则使用OPENAIAPIKEY，否则提示输入密钥，然后保存到~/.openclaw/.env以便 launchd 可以读取。
• OpenCode Zen（多模型代理）：提示输入OPENCODEAPIKEY（或OPENCODEZENAPI_KEY，在https://opencode.ai/auth获取）。
• API 密钥：为你存储密钥。
• Vercel AI Gateway（多模型代理）：提示输入AIGATEWAYAPI_KEY。
• 更多详情：Vercel AI Gateway
• MiniMax M2.1：自动写入配置。
• 更多详情：MiniMax
• Synthetic（Anthropic 兼容）：提示输入SYNTHETICAPIKEY。
• 更多详情：Synthetic
• Moonshot（Kimi K2）：自动写入配置。
• Kimi Coding：自动写入配置。
• 更多详情：Moonshot AI（Kimi + Kimi Coding）
• 跳过：尚未配置认证。
• 从检测到的选项中选择默认模型（或手动输入提供商/模型）。
• 向导运行模型检查，如果配置的模型未知或缺少认证则发出警告。

• OAuth 凭证存储在~/.openclaw/credentials/oauth.json；认证配置文件存储在~/.openclaw/agents/<agentId/agent/auth-profiles.json（API 密钥 + OAuth）。
• 更多详情：/concepts/oauth

3. 工作区
• 默认~/.openclaw/workspace（可配置）。
• 为智能体引导仪式播种所需的工作区文件。
• 完整的工作区布局 + 备份指南：智能体工作区
4. Gateway 网关
• 端口、绑定、认证模式、tailscale 暴露。
• 认证建议：即使对于 loopback 也保持Token，以便本地 WS 客户端必须进行认证。
• 仅当你完全信任每个本地进程时才禁用认证。
• 非 loopback 绑定仍需要认证。
5. 渠道
• WhatsApp：可选的二维码登录。
• Telegram：机器人令牌。
• Discord：机器人令牌。
• Google Chat：服务账户 JSON + webhook 受众。
• Mattermost（插件）：机器人令牌 + 基础 URL。
• Signal：可选的signal-cli安装 + 账户配置。
• iMessage：本地imsgCLI 路径 + 数据库访问。
• 私信安全：默认为配对。第一条私信发送验证码；通过openclaw pairing approve <channel<code批准或使用允许列表。
6. 守护进程安装
• 向导尝试通过loginctl enable-linger <user启用 lingering，以便 Gateway 网关在注销后保持运行。
• 可能提示 sudo（写入/var/lib/systemd/linger）；它首先尝试不使用 sudo。
• 需要已登录的用户会话；对于无头环境，使用自定义 LaunchDaemon（未提供）。
• macOS：LaunchAgent
• Linux（和通过 WSL2 的 Windows）：systemd 用户单元
• 运行时选择：Node（推荐；WhatsApp/Telegram 需要）。不推荐Bun。
7. 健康检查
• 启动 Gateway 网关（如果需要）并运行openclaw health。
• 提示：openclaw status --deep在状态输出中添加 Gateway 网关健康探测（需要可达的 Gateway 网关）。
8. Skills（推荐）
• 读取可用的 Skills 并检查要求。
• 让你选择节点管理器：npm / pnpm（不推荐 bun）。
• 安装可选依赖项（某些在 macOS 上使用 Homebrew）。
9. 完成
• 总结 + 后续步骤，包括用于额外功能的 iOS/Android/macOS 应用。

• 如果未检测到 GUI，向导会打印控制界面的 SSH 端口转发说明，而不是打开浏览器。
• 如果控制界面资源缺失，向导会尝试构建它们；回退方案是pnpm ui:build（自动安装 UI 依赖）。

远程模式

远程模式配置本地客户端连接到其他位置的 Gateway 网关。 你将设置的内容：

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

注意事项：

• 不执行远程安装或守护进程更改。
• 如果 Gateway 网关仅限 loopback，使用 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 "$ANTHROPICAPIKEY" \ --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 "$GEMINIAPIKEY" \ --gateway-port 18789 \ --gateway-bind loopback

Z.AI 示例：

openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$ZAIAPIKEY" \ --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 "$AIGATEWAYAPI_KEY" \ --gateway-port 18789 \ --gateway-bind loopback

Moonshot 示例：

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

Synthetic 示例：

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

OpenCode Zen 示例：

openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODEAPIKEY" \ --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

Gateway 网关向导 RPC

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

Signal 设置（signal-cli）

向导可以从 GitHub releases 安装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）
• 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 或本地路径）。

相关文档

• macOS 应用新手引导：新手引导
• 配置参考：Gateway 网关配置
• 提供商：WhatsApp、Telegram、Discord、Google Chat、Signal、iMessage
• Skills：Skills、Skills 配置