学了个寂寞

Appearance

CLI Setup Reference ​

本页是 openclaw onboard 的完整参考手册。 快速入门指南参见 Onboarding（CLI）。

向导做了什么 ​

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

  • 模型和认证设置（OpenAI Code 订阅 OAuth、Anthropic API Key 或 setup token，以及 MiniMax、GLM、Ollama、Moonshot 和 AI Gateway 选项）
  • 工作区位置和引导初始文件
  • Gateway 设置（端口、绑定地址、认证、Tailscale）
  • 频道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
  • 守护进程安装（LaunchAgent 或 systemd 用户单元）
  • 健康检查
  • Skills 设置

远程模式配置本机连接到其他地方的 gateway，不会在远程主机上安装或修改任何内容。

本地模式详细步骤 ​

第一步：检测已有配置 ​

  • 如果 ~/.openclaw/openclaw.json 已存在，选择 Keep（保留）、Modify（修改）或 Reset（重置）。
  • 重新运行向导不会清除任何内容，除非你明确选择 Reset（或传入 --reset）。
  • CLI --reset 默认范围为 config+creds+sessions；用 --reset-scope full 也包含工作区。
  • 如果配置无效或包含过期 key，向导会停止并要求你先运行 openclaw doctor。
  • Reset 使用 trash 工具，提供以下范围：
    • 仅配置
    • 配置 + 凭证 + 会话
    • 完全重置（同时移除工作区）

第二步：模型和认证 ​

完整选项矩阵参见下方 认证与模型选项。

第三步：工作区 ​

  • 默认 ~/.openclaw/workspace（可配置）。
  • 生成首次运行引导仪式所需的工作区文件。
  • 工作区布局：Agent 工作区。

第四步：Gateway ​

  • 提示填写端口、绑定地址、认证模式和 Tailscale 暴露。
  • 建议：即使在 loopback 上也保持 token 认证，这样本地 WS 客户端必须经过认证。
  • Token 模式下，交互式设置提供：
    • 生成/存储明文 token（默认）
    • 使用 SecretRef（选项）
  • Password 模式下，交互式设置同样支持明文或 SecretRef 存储。
  • 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
    • 需要在 onboarding 进程环境中设置非空的环境变量。
    • 不能与 --gateway-token 同时使用。
  • 只有当你完全信任所有本地进程时才禁用认证。
  • 非 loopback 绑定仍然需要认证。

第五步：频道 ​

  • WhatsApp：可选 QR 登录
  • Telegram：bot token
  • Discord：bot token
  • Google Chat：服务账号 JSON + webhook audience
  • Mattermost 插件：bot token + 基础 URL
  • Signal：可选 signal-cli 安装 + 账号配置
  • BlueBubbles：推荐用于 iMessage；服务器 URL + 密码 + webhook
  • iMessage：旧版 imsg CLI 路径 + DB 访问
  • DM 安全性：默认使用配对。首条 DM 发送验证码；通过 openclaw pairing approve <channel> <code> 批准，或使用许可名单。

第六步：守护进程安装 ​

  • macOS：LaunchAgent
    • 需要已登录的用户会话；无头模式需使用自定义 LaunchDaemon（不随 OpenClaw 提供）。
  • Linux 和 Windows（WSL2）：systemd 用户单元
    • 向导会尝试执行 loginctl enable-linger <user>，使 gateway 在注销后继续运行。
    • 可能需要 sudo（写入 /var/lib/systemd/linger）；先不带 sudo 尝试。
  • 运行时选择：Node（推荐；WhatsApp 和 Telegram 必须）。不推荐 Bun。

第七步：健康检查 ​

  • 启动 gateway（如需要）并运行 openclaw health。
  • openclaw status --deep 在状态输出中增加 gateway 健康探测。

第八步：Skills ​

  • 读取可用 skills 并检查依赖。
  • 让你选择 node 包管理器：npm 或 pnpm（不推荐 bun）。
  • 安装可选依赖（部分在 macOS 上使用 Homebrew）。

第九步：完成 ​

  • 摘要和后续步骤，包括 iOS、Android 和 macOS App 选项。

注意： 如果未检测到 GUI，向导会打印 SSH 端口转发指令用于访问 Control UI，而不是直接打开浏览器。如果 Control UI 资源文件缺失，向导会尝试构建它们；回退方案是 pnpm ui:build（自动安装 UI 依赖）。

远程模式详细说明 ​

远程模式配置本机连接到其他地方的 gateway。

提示： 远程模式不会在远程主机上安装或修改任何内容。

需要设置的内容：

  • 远程 gateway URL（ws://...）
  • 如果远程 gateway 需要认证，填写 token（推荐）

注意：

  • 如果 gateway 只绑定在 loopback，使用 SSH 隧道或 tailnet。
  • 发现提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

认证与模型选项 ​

Anthropic API Key ​

如果环境中有 ANTHROPIC_API_KEY 则直接使用，否则提示输入，然后保存供守护进程使用。

Anthropic Claude CLI ​

复用 gateway 主机上本地 Claude CLI 的登录，并将模型选择切换为 claude-cli/...。

  • macOS：检查 Keychain 项 "Claude Code-credentials"
  • Linux 和 Windows：如果存在则复用 ~/.claude/.credentials.json

在 macOS 上，选择"Always Allow"以避免 launchd 启动时被阻塞。

Anthropic token（setup-token 粘贴） ​

在任意机器上运行 claude setup-token，然后粘贴 token。可以命名，留空使用默认名。

OpenAI Code 订阅（Codex CLI 复用） ​

如果存在 ~/.codex/auth.json，向导可以复用它。

OpenAI Code 订阅（OAuth） ​

浏览器流程；粘贴 code#state。

当模型未设置或为 openai/* 时，将 agents.defaults.model 设为 openai-codex/gpt-5.4。

OpenAI API Key ​

如果环境中有 OPENAI_API_KEY 则直接使用，否则提示输入，然后存储在认证配置中。

当模型未设置、为 openai/* 或 openai-codex/* 时，将 agents.defaults.model 设为 openai/gpt-5.4。

xAI（Grok）API Key ​

提示输入 XAI_API_KEY 并将 xAI 配置为模型提供商。

OpenCode ​

提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）并让你选择 Zen 或 Go 目录。 设置 URL：opencode.ai/auth。

通用 API Key ​

为你存储 Key。

Vercel AI Gateway ​

提示输入 AI_GATEWAY_API_KEY。 详细说明：Vercel AI Gateway。

Cloudflare AI Gateway ​

提示输入账号 ID、gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。 详细说明：Cloudflare AI Gateway。

MiniMax ​

配置自动写入。托管默认模型为 MiniMax-M2.7；MiniMax-M2.5 仍可使用。 详细说明：MiniMax。

Synthetic（Anthropic 兼容） ​

提示输入 SYNTHETIC_API_KEY。 详细说明：Synthetic。

Ollama（云端和本地开源模型） ​

提示输入 base URL（默认 http://127.0.0.1:11434），然后提供 Cloud + Local 或仅 Local 模式。发现可用模型并建议默认值。 详细说明：Ollama。

Moonshot 和 Kimi Coding ​

Moonshot（Kimi K2）和 Kimi Coding 配置自动写入。 详细说明：Moonshot AI（Kimi + Kimi Coding）。

自定义提供商 ​

支持 OpenAI 兼容和 Anthropic 兼容的 endpoint。

交互式 onboarding 支持与其他提供商 API Key 流程相同的存储选择：

  • 现在粘贴 API Key（明文）
  • 使用 secret reference（环境变量引用或配置好的提供商引用，含预检验证）

非交互式标志：

  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key（可选；回退到 CUSTOM_API_KEY）
  • --custom-provider-id（可选）
  • --custom-compatibility <openai|anthropic>（可选；默认 openai）

跳过 ​

保持认证未配置。

模型行为：

  • 从检测到的选项中选择默认模型，或手动输入提供商和模型名称。
  • 向导会运行模型检查，如果配置的模型未知或缺少认证会发出警告。

凭证和配置文件路径：

  • OAuth 凭证：~/.openclaw/credentials/oauth.json
  • 认证配置（API Key + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

凭证存储模式：

  • 默认 onboarding 行为：在认证配置中以明文存储 API Key 值。
  • --secret-input-mode ref：启用引用模式，而非明文 Key 存储。交互式设置中可选择：
    • 环境变量引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 配置好的提供商引用（file 或 exec），需提供提供商别名 + id
  • 交互式引用模式在保存前进行快速预检验证：
    • 环境变量引用：验证变量名称 + 当前 onboarding 环境中的非空值。
    • 提供商引用：验证提供商配置并解析请求的 id。
    • 预检失败时，onboarding 显示错误并允许重试。
  • 非交互式模式下，--secret-input-mode ref 仅支持环境变量引用：
    • 在 onboarding 进程环境中设置提供商环境变量。
    • 内联 Key 标志（例如 --openai-api-key）要求该环境变量已设置，否则快速失败。
    • 自定义提供商的非交互式 ref 模式将 models.providers.<id>.apiKey 存储为 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 该情况下，--custom-api-key 要求 CUSTOM_API_KEY 已设置，否则快速失败。
  • Gateway 认证凭证在交互式设置中支持明文和 SecretRef 选择：
    • Token 模式：生成/存储明文 token（默认）或使用 SecretRef。
    • Password 模式：明文或 SecretRef。
  • 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
  • 现有明文设置继续正常工作，无需更改。

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

输出与内部机制 ​

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（选择 Minimax 时）
  • tools.profile（本地 onboarding 在未设置时默认 "coding"；已有显式值时保留）
  • gateway.*（模式、绑定、认证、Tailscale）
  • session.dmScope（本地 onboarding 在未设置时默认 per-channel-peer；已有显式值时保留）
  • 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 或本地路径），然后再进行频道配置。

Gateway 向导 RPC：

  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status

客户端（macOS App 和 Control UI）可以渲染步骤，无需重新实现 onboarding 逻辑。

Signal 设置行为：

  • 下载适当的发布资产
  • 存储在 ~/.openclaw/tools/signal-cli/<version>/ 下
  • 在配置中写入 channels.signal.cliPath
  • JVM 版本需要 Java 21
  • 有原生版本时优先使用原生版本
  • Windows 使用 WSL2 并在 WSL 内遵循 Linux signal-cli 流程

相关文档 ​

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策