openclaw 网盘下载
OpenClaw
Ctrl K

文档

首页 > 文档 > 设置向导参考

设置向导参考

这是 openclaw onboard CLI 向导的完整参考。
有关高层概览，请参阅 设置向导。

流程详情（本地模式）

* 如果 ~/.openclaw/openclaw.json 存在，请选择 Keep / Modify / Reset。
* 重新运行向导不会清除任何内容，除非你明确选择 Reset
（或传入 --reset）。
* CLI --reset 默认值为 config+creds+sessions；使用 --reset-scope full
可额外移除工作区。
* 如果配置无效或包含旧版键，向导会停止，并要求
你先运行 openclaw doctor 再继续。
* 重置会使用 trash（绝不使用 rm），并提供以下范围：
* 仅配置
* 配置 + 凭证 + 会话
* 完整重置（也会移除工作区）

* Anthropic API key：如果存在则使用 ANTHROPIC_API_KEY，否则提示输入 key，然后保存以供守护进程使用。
* Anthropic OAuth（Claude Code CLI）：在 macOS 上，向导会检查钥匙串项目 “Claude Code-credentials”（请选择 “Always Allow”，这样 launchd 启动时就不会被阻塞）；在 Linux/Windows 上，如果存在，则会重用 ~/.claude/.credentials.json。
* Anthropic token（粘贴 setup-token）：在任意机器上运行 claude setup-token，然后粘贴该 token（你可以为其命名；留空 = default）。
* 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 key：如果存在则使用 OPENAI_API_KEY，否则提示输入 key，然后将其存储到凭证配置文件中。
* xAI（Grok）API key：提示输入 XAI_API_KEY，并将 xAI 配置为模型提供商。
* OpenCode：提示输入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，可从 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。
* Ollama：提示输入 Ollama base URL，提供 Cloud + Local 或 Local 模式，发现可用模型，并在需要时自动拉取所选本地模型。
* 更多细节： Ollama
* API key：为你存储该 key。
* Vercel AI Gateway（多模型代理）：提示输入 AI_GATEWAY_API_KEY。
* 更多细节： Vercel AI Gateway
* Cloudflare AI Gateway：提示输入 Account ID、Gateway 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)
* Skip：暂不配置认证。
* 从已检测到的选项中选择默认模型（或手动输入 provider/model）。为了获得最佳质量并降低 prompt injection 风险，请选择你在提供商栈中可用的最强最新一代模型。
* 向导会运行模型检查，并在所配置模型未知或缺少认证时发出警告。
* API key 存储模式默认为明文 auth-profile 值。使用 --secret-input-mode ref 可改为存储基于环境变量的引用（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
* OAuth 凭证保存在 ~/.openclaw/credentials/oauth.json；auth-profile 保存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API key + OAuth）。
* 更多细节： /concepts/oauth

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

* 默认为 ~/.openclaw/workspace（可配置）。
* 为工作区植入智能体引导仪式所需的文件。
* 完整工作区布局 + 备份指南： 智能体工作区

* Port、bind、auth mode、tailscale 暴露方式。
* 认证建议：即使是 loopback，也保留 Token，这样本地 WS 客户端也必须进行认证。
* 在 token 模式下，交互式设置提供：
* 生成/存储明文 token（默认）
* 使用 SecretRef（可选启用）
* 快速开始会在新手引导探测/dashboard 引导期间，跨 env、file 和 exec 提供商重用现有的 gateway.auth.token SecretRef。
* 如果该 SecretRef 已配置但无法解析，则新手引导会提前失败，并给出明确修复信息，而不是静默降级运行时认证。
* 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。
* 非交互式 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
* 要求新手引导进程环境中存在非空环境变量。
* 不能与 --gateway-token 组合使用。
* 仅当你完全信任每个本地进程时，才禁用认证。
* 非 loopback 绑定仍然需要认证。

* WhatsApp：可选 QR 登录。
* Telegram：bot token。
* Discord：bot token。
* Google Chat：服务账号 JSON + webhook audience。
* Mattermost（插件）：bot token + base URL。
* Signal：可选安装 signal-cli + 账号配置。
* BlueBubbles：iMessage 推荐方案；server URL + password + webhook。
* iMessage：旧版 imsg CLI 路径 + 数据库访问。
* 私信安全：默认为 pairing。首次私信会发送一个代码；通过 openclaw pairing approve <channel> <code> 批准，或使用允许列表。

* 选择一个提供商：Perplexity、Brave、Gemini、Grok 或 Kimi（也可跳过）。
* 粘贴你的 API key（QuickStart 会自动从环境变量或现有配置中检测 key）。
* 使用 --skip-search 跳过。
* 之后再配置：openclaw configure --section web。

* macOS：LaunchAgent
* 需要已登录的用户会话；无头场景请使用自定义 LaunchDaemon（未随产品提供）。
* Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
* 向导会尝试启用 lingering：loginctl enable-linger <user>，以便 Gateway 网关在注销后仍保持运行。
* 可能会提示输入 sudo（会写入 /var/lib/systemd/linger）；它会先尝试不使用 sudo。
* 运行时选择： Node（推荐；WhatsApp/Telegram 必需）。不推荐 Bun。
* 如果 token 认证需要 token，并且 gateway.auth.token 由 SecretRef 管理，则守护进程安装会验证它，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
* 如果 token 认证需要 token，但配置的 token SecretRef 尚未解析，则会阻止守护进程安装，并给出可执行指导。
* 如果同时配置了 gateway.auth.token 和 gateway.auth.password，且 gateway.auth.mode 未设置，则会阻止守护进程安装，直到显式设置 mode。

* 启动 Gateway 网关（如果需要）并运行 openclaw health。
* 提示：openclaw status --deep 会在状态输出中添加 Gateway 网关健康探测（需要能访问到 Gateway 网关）。

* 读取可用的 Skills 并检查要求。
* 让你选择一个 node manager：npm / pnpm（不推荐 bun）。
* 安装可选依赖（某些在 macOS 上使用 Homebrew）。

* 摘要 + 后续步骤，包括可提供额外功能的 iOS/Android/macOS 应用。

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

非交互模式

使用 --non-interactive 自动化或脚本化新手引导：

“`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
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` 可获得机器可读摘要。

在非交互模式中使用 Gateway token SecretRef：

```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive 
  --mode local 
  --auth-choice skip 
  --gateway-auth token 
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

--gateway-token 和 --gateway-token-ref-env 互斥。

--json 并不意味着非交互模式。脚本中请使用 --non-interactive（以及 --workspace）。

特定提供商的命令示例位于 CLI Automation。
本参考页用于说明标志语义和步骤顺序。

添加智能体（非交互）

bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 应用、Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。

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）
  • tools.profile（本地新手引导在未设置时默认为 "coding"；已有的显式值会被保留）
  • gateway.*（mode、bind、auth、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 或本地路径），然后才能配置。

相关文档