ClawCN - OpenClaw 中文版

主题

引导向导 (CLI) ​

引导向导是在 macOS、Linux 或 Windows(通过 WSL2;强烈推荐)上设置 OpenClaw 的推荐方式。 它在一个引导式流程中配置本地网关或远程网关连接,以及渠道、技能和工作空间默认设置。

主要入口点:

bash
openclaw onboard

最快的首次聊天:打开控制 UI(无需渠道设置)。运行 openclaw dashboard 并在浏览器中聊天。文档:控制面板。

后续重新配置:

bash
openclaw configure

推荐:设置 Brave Search API 密钥,以便代理可以使用 web_search (web_fetch 无需密钥即可工作)。最简单的方法:openclaw configure --section web 它会存储 tools.web.search.apiKey。文档:Web 工具。

快速启动 vs 高级 ​

向导从快速启动(默认)vs 高级(完全控制)开始。

快速启动保持默认设置:

  • 本地网关(环回)
  • 工作空间默认值(或现有工作空间)
  • 网关端口 18789
  • 网关认证 Token(自动生成,即使在环回上)
  • Tailscale 暴露 关闭
  • Telegram + WhatsApp 私信默认为允许列表(系统会提示您输入电话号码)

高级暴露每个步骤(模式、工作空间、网关、渠道、守护进程、技能)。

向导的功能 ​

**本地模式(默认)**引导您完成:

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

远程模式仅配置本地客户端以连接到其他地方的网关。 它不会在远程主机上安装或更改任何内容。

要添加更多隔离的代理(独立的工作空间 + 会话 + 认证),使用:

bash
openclaw agents add <name>

提示:--json 不意味着非交互模式。使用 --non-interactive(和 --workspace)用于脚本。

流程详情(本地) ​

  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 token(粘贴 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

  1. 工作空间

    • 默认 ~/.openclaw/workspace(可配置)。
    • 为代理引导仪式准备工作空间所需的文件。
    • 完整工作空间布局 + 备份指南:代理工作空间

  2. 网关

    • 端口、绑定、认证模式、tailscale 暴露。
    • 认证建议:即使对于环回也保持 Token,以便本地 WS 客户端必须进行身份验证。
    • 仅当您完全信任每个本地进程时才禁用认证。
    • 非环回绑定仍然需要认证。

  3. 渠道

    • WhatsApp:可选的二维码登录。
    • Telegram:机器人令牌。
    • Discord:机器人令牌。
    • Google Chat:服务账户 JSON + webhook 受众。
    • Mattermost(插件):机器人令牌 + 基础 URL。
    • Signal:可选的 signal-cli 安装 + 账户配置。
    • BlueBubbles:推荐用于 iMessage;服务器 URL + 密码 + webhook。
    • iMessage:旧版 imsg CLI 路径 + DB 访问。
    • 私信安全:默认是配对。首次私信发送代码;通过 openclaw pairing approve <channel> <code> 批准或使用允许列表。

  4. 守护进程安装

    • macOS:LaunchAgent
      • 需要已登录的用户会话;对于无头运行,使用自定义 LaunchDaemon(未提供)。
    • Linux(和通过 WSL2 的 Windows):systemd 用户单元
      • 向导尝试通过 loginctl enable-linger <user> 启用持久化,以便网关在注销后保持运行。
      • 可能提示 sudo(写入 /var/lib/systemd/linger);它首先尝试不使用 sudo。
    • 运行时选择: Node(推荐;WhatsApp/Telegram 必需)。不推荐 Bun。

  5. 健康检查

    • 启动网关(如果需要)并运行 openclaw health。
    • 提示:openclaw status --deep 将网关健康探测添加到状态输出(需要可访问的网关)。

  6. 技能(推荐)

    • 读取可用技能并检查要求。
    • 让您选择节点管理器:npm / pnpm(不推荐 bun)。
    • 安装可选依赖项(某些在 macOS 上使用 Homebrew)。

  7. 完成

    • 摘要 + 下一步,包括用于额外功能的 iOS/Android/macOS 应用。
  • 如果未检测到 GUI,向导会打印控制 UI 的 SSH 端口转发说明,而不是打开浏览器。
  • 如果缺少控制 UI 资源,向导会尝试构建它们;回退是 pnpm ui:build(自动安装 UI 依赖项)。

远程模式 ​

远程模式配置本地客户端以连接到其他地方的网关。

您将设置的内容:

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

注意事项:

  • 不执行远程安装或守护进程更改。
  • 如果网关仅限环回,请使用 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 自动化或编写引导脚本:

bash
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 以获取机器可读的摘要。

Gemini 示例:

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

Z.AI 示例:

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

Vercel AI Gateway 示例:

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

Moonshot 示例:

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

Synthetic 示例:

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

OpenCode Zen 示例:

bash
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

添加代理(非交互式)示例:

bash
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 安装遵循 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 或本地路径)。

相关文档 ​