OpenClaw从入门到应用：基础知识——CLI 初始化配置参考

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》本文档是openclaw onboard命令的完整参考指南。如需简短指南请参阅 入门向导CLI。向导的功能openclaw onboard向导支持两种运行模式本地模式默认在本地机器上完成完整配置包括模型与认证、工作区、网关、频道、守护进程安装、健康检查和技能设置。远程模式将当前机器配置为连接到其他位置的网关不会在远程主机上安装或修改任何内容。本地流程细节配置管理如果~/.openclaw/openclaw.json已存在向导将提示您选择保留Keep、修改Modify或重置Reset。重新运行向导不会删除任何内容除非您明确选择重置或传入--reset参数。--reset默认作用域为configcredssessions使用--reset-scope full可同时删除工作区。如果配置无效或包含已弃用的字段向导将停止并要求您先运行openclaw doctor。重置操作使用trash命令并提供以下作用域选项仅配置Config only配置 凭据 会话Config credentials sessions完全重置同时删除工作区工作区位置与引导文件默认工作区路径为~/.openclaw/workspace可配置。向导会生成首次运行所需的引导文件。工作区布局详见Agent 工作区。网关设置向导将提示您输入端口、绑定地址、认证模式和 Tailscale 暴露选项。建议即使绑定到 loopback127.0.0.1也保持令牌认证启用以确保本地 WebSocket 客户端必须通过认证。在令牌模式下交互式向导提供以下选项生成/存储明文令牌默认使用 SecretRef可选在密码模式下同样支持明文或 SecretRef 存储。非交互式模式下指定令牌 SecretRef 的参数为--gateway-token-ref-env 环境变量名。要求在向导运行环境中该环境变量非空。不能与--gateway-token同时使用。仅在完全信任本地所有进程时才应禁用认证。非 loopback 绑定始终需要认证。频道与提供商向导支持配置以下频道部分需要额外安装插件WhatsApp可选 QR 登录Telegram机器人令牌Discord机器人令牌Google Chat服务账号 JSON Webhook 受众Mattermost 插件机器人令牌 基础 URLSignal可选安装signal-cli并配置账号BlueBubbles推荐用于 iMessage需提供服务器 URL、密码和 WebhookiMessage旧版imsgCLI 路径 数据库访问权限私信DM安全策略默认为配对pairing首次私信会发送验证码可通过openclaw pairing approve code批准或使用白名单。守护进程安装macOS使用 LaunchAgent需要用户已登录会话如需无头headless运行请自行配置 LaunchDaemon官方未提供。Linux 和 WSL2 下的 Windows使用 systemd 用户单元向导会尝试执行loginctl enable-linger 用户名以便用户登出后网关仍保持运行。可能会提示输入 sudo 密码用于写入/var/lib/systemd/linger向导会先尝试不使用 sudo。运行时选择Node推荐WhatsApp 和 Telegram 必需。不推荐使用 Bun。健康检查启动网关如需要并运行openclaw health。使用openclaw status --deep可在状态输出中加入网关健康探测结果。技能设置读取可用技能并检查依赖项。允许您选择 Node 包管理器npm 或 pnpm不推荐 bun。安装可选依赖部分在 macOS 上使用 Homebrew。控制 UI若未检测到图形界面GUI向导将打印 Control UI 的 SSH 端口转发指令而非打开浏览器。若 Control UI 资源缺失向导将尝试自动构建回退方案为手动执行pnpm ui:build会自动安装 UI 依赖。远程模式细节远程模式配置当前机器连接到其他位置的网关。它不会在远程主机上安装或修改任何内容。您需要设置远程网关 URL例如ws://...若远程网关启用了认证强烈建议启用则需提供令牌若网关仅绑定 loopback请使用 SSH 隧道或 Tailscale 网络tailnet。发现提示macOSBonjourdns-sdLinuxAvahiavahi-browse认证与模型选项向导支持多种模型提供商和认证方式完整的选项矩阵如下提供商配置Anthropic API 密钥若环境变量ANTHROPIC_API_KEY存在则使用否则提示输入。Claude Code OAuthmacOS检查钥匙串中 “Claude Code-credentials”Linux/Windows复用~/.claude/.credentials.json在 macOS 上选择“始终允许”以免 launchd 启动时被阻塞。Claude Code 设置令牌运行claude setup-token粘贴令牌可命名。Codex 认证若~/.codex/auth.json存在向导可复用。OpenAI Code OAuth浏览器流程粘贴code#state。当模型未设置或为openai/*时自动设置agents.defaults.model为openai-codex/gpt-5.4。OpenAI API 密钥若OPENAI_API_KEY存在则使用否则提示输入。当模型未设置、为openai/*或openai-codex/*时自动设置agents.defaults.model为openai/gpt-5.1-codex。xAI提示输入XAI_API_KEY并配置 xAI。Opencode提示输入OPENCODE_API_KEY或OPENCODE_ZEN_API_KEY选择 Zen 或 Go 目录。设置地址opencode.ai/auth。GLM自动存储密钥。Vercel AI Gateway提示输入AI_GATEWAY_API_KEY。详见Vercel AI Gateway。Cloudflare AI Gateway提示输入账户 ID、网关 ID 和CLOUDFLARE_AI_GATEWAY_API_KEY。详见Cloudflare AI Gateway。MiniMax配置自动写入。详见MiniMax。Synthetic提示输入SYNTHETIC_API_KEY。详见Synthetic。Ollama提示输入基础 URL默认http://127.0.0.1:11434选择 CloudLocal 或 Local 模式自动发现可用模型并建议默认值。详见Ollama。Moonshot AI自动写入 MoonshotKimi K2和 Kimi Coding 配置。详见Moonshot AI。自定义提供商支持 OpenAI 兼容和 Anthropic 兼容的端点。交互式向导支持与其他提供商相同的 API 密钥存储选项立即粘贴 API 密钥明文使用密钥引用Secret Reference非交互式参数--auth-choice custom-api-key、--custom-base-url、--custom-model-id、--custom-api-key可选、--custom-provider-id可选、--custom-compatibility可选默认openai。跳过认证保持认证未配置状态。模型行为从检测到的选项中选择默认模型或手动输入提供商和模型。向导会执行模型检查若配置的模型未知或缺少认证将发出警告。凭据与配置文件路径OAuth 凭据~/.openclaw/credentials/oauth.json认证配置文件API 密钥 OAuth~/.openclaw/agents/agent_name/agent/auth-profiles.json凭据存储模式默认向导行为将 API 密钥以明文形式持久化到认证配置文件中。使用--secret-input-mode ref可启用引用模式而非明文存储。交互式向导中可选择环境变量引用例如keyRef: { source: env, provider: default, id: OPENAI_API_KEY }已配置的提供商标识file或exec类型需提供别名和 ID交互式引用模式会在保存前执行快速预检验证环境变量引用验证变量名及当前向导环境中该变量是否非空提供商标识引用验证提供者配置并解析请求的 ID若预检失败向导将显示错误并允许重试在非交互式模式下--secret-input-mode ref仅支持环境变量后端需在向导运行环境中设置相应的提供者环境变量内联密钥参数如--openai-api-key要求对应环境变量已设置否则向导将快速失败对于自定义提供者非交互式ref模式会将models.providers.name.apiKey存储为{ source: env, provider: default, id: CUSTOM_API_KEY }在此场景下--custom-api-key要求CUSTOM_API_KEY环境变量已设置网关认证凭据在交互式向导中支持明文和 SecretRef 选择令牌模式生成/存储明文令牌默认或使用 SecretRef密码模式明文或 SecretRef非交互式令牌 SecretRef 路径参数--gateway-token-ref-env 环境变量名现有的明文配置将继续正常工作不受影响。无头Headless与服务器部署提示在有浏览器的机器上完成 OAuth 流程然后将~/.openclaw/credentials/oauth.json或$OPENCLAW_STATE_DIR/credentials/oauth.json复制到网关主机即可。输出与内部机制~/.openclaw/openclaw.json中的典型字段包括agents.defaults.workspaceagents.defaults.model/models.providers若选择了 MiniMaxtools.profile本地向导在未设置时默认为coding已有显式值将保留gateway.*模式、绑定、认证、Tailscalesession.dmScope本地向导在未设置时默认为per-channel-peer已有显式值将保留channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*频道白名单Slack、Discord、Matrix、Microsoft Teams——若您在提示中选择启用名称会尽可能解析为 IDskills.install.nodeManagerwizard.lastRunAtwizard.lastRunVersionwizard.lastRunCommitwizard.lastRunCommandwizard.lastRunModeopenclaw agents add会写入agents.list[]和可选的bindings。WhatsApp 凭据存储在~/.openclaw/credentials/whatsapp/phone/下。会话存储在~/.openclaw/agents/agent/sessions/下。部分频道以插件形式提供。若在向导过程中选择这些频道向导将提示您先安装插件通过 npm 或本地路径再进行频道配置。网关向导 RPCwizard.startwizard.nextwizard.cancelwizard.status客户端macOS 应用和 Control UI可渲染步骤界面而无需重新实现向导逻辑。Signal 设置行为下载合适的发布版本资源存储在~/.openclaw/tools/signal-cli/version/下在配置中写入channels.signal.cliPathJVM 构建版本需要 Java 21若有原生构建版本则优先使用Windows 通过 WSL2 运行并在 WSL 内部遵循 Linux 的 signal-cli 流程相关文档向导中心入门向导CLI自动化与脚本CLI 自动化命令参考openclaw onboard本文档使用 Mintlify 构建。