​

引导向导(CLI)

openclaw onboard

openclaw configure

​

快速开始 vs 高级

• 本地网关(loopback)
• 工作空间默认值(或现有工作空间)
• 网关端口 18789
• 网关身份验证 令牌(自动生成,即使在 loopback 上)
• Tailscale 暴露 关闭
• Telegram + WhatsApp DM 默认为 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>

​

流程详细信息(本地)

1. 现有配置检测
   • 如果 ~/.openclaw/openclaw.json 存在,选择 保留 / 修改 / 重置。
   • 重新运行向导不会擦除任何内容,除非您明确选择 重置 (或传递 --reset)。
   • 如果配置无效或包含遗留密钥,向导会停止并要求 您在继续之前运行 openclaw doctor。
   • 重置使用 trash(从不 rm)并提供作用域:
     • 仅配置
     • 配置 + 凭据 + 会话
     • 完全重置(还删除工作空间)
2. 模型/身份验证
   • Anthropic API 密钥(推荐):如果存在则使用 ANTHROPIC_API_KEY,或提示输入密钥,然后保存以供守护进程使用。
   • 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/* 时,将 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 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. 网关
   • 端口、绑定、身份验证模式、tailscale 暴露。
   • 身份验证建议:即使对于 loopback,也保留 令牌,以便本地 WS 客户端必须进行身份验证。
   • 仅当您完全信任每个本地进程时才禁用身份验证。
   • 非 loopback 绑定仍需要身份验证。
5. 频道
   • WhatsApp:可选的 QR 登录。
   • Telegram:机器人令牌。
   • Discord:机器人令牌。
   • Google Chat:服务账户 JSON + webhook 受众。
   • Mattermost(插件):机器人令牌 + 基础 URL。
   • Signal:可选的 signal-cli 安装 + 账户配置。
   • iMessage:本地 imsg CLI 路径 + DB 访问。
   • DM 安全:默认为配对。第一个 DM 发送代码;通过 openclaw pairing approve <channel> <code> 批准或使用 allowlist。
6. 守护进程安装
   • macOS:LaunchAgent
     • 需要登录的用户会话;对于无头,使用自定义 LaunchDaemon(未提供)。
   • Linux(和通过 WSL2 的 Windows):systemd 用户单元
     • 向导尝试通过 loginctl enable-linger <user> 启用持久性,以便网关在注销后保持运行。
     • 可能提示输入 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,向导会打印控制 UI 的 SSH 端口转发说明,而不是打开浏览器。
• 如果缺少控制 UI 资产,向导尝试构建它们;后备是 pnpm ui:build(自动安装 UI 依赖项)。

​

远程模式

• 远程网关 URL(ws://...)
• 如果远程网关需要身份验证(推荐),则需要令牌

• 不执行远程安装或守护进程更改。
• 如果网关仅为 loopback,请使用 SSH 隧道或 tailnet。
• 发现提示:
  • macOS:Bonjour(dns-sd)
  • Linux:Avahi(avahi-browse)

​

添加另一个代理

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

• 默认工作空间遵循 ~/.openclaw/workspace-<agentId>。
• 添加 bindings 以路由入站消息(向导可以执行此操作)。
• 非交互式标志:--model、--agent-dir、--bind、--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

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

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

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

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

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

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

​

Signal 设置(signal-cli)

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

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

​

向导写入什么

• agents.defaults.workspace
• agents.defaults.model / models.providers(如果选择 Minimax)
• gateway.*(模式、绑定、身份验证、tailscale)
• channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
• 频道 allowlist(Slack/Discord/Matrix/Microsoft Teams),当您在提示期间选择加入时(名称在可能时解析为 ID)。
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

​

相关文档

• macOS 应用引导:引导
• 配置参考:网关配置
• 提供者:WhatsApp、Telegram、Discord、Google Chat、Signal、iMessage
• 技能:技能、技能配置