[OpenClaw 文档]快速开始--第一步

本文档汇总了 OpenClaw 官方文档站 快速开始 > 第一步 子模块下的全部 3 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 入门指南

原文：https://docs.openclaw.ai/zh-CN/start/getting-started

安装 OpenClaw，运行新手引导，并与你的 AI 助手聊天，全程大约
5 分钟。完成后，你将拥有一个正在运行的 Gateway 网关、已配置的凭证，
以及一个可用的聊天会话。

你需要准备

• Node.js — 推荐 Node 24（也支持 Node 22.16+）
• 来自模型提供商的 API key（Anthropic、OpenAI、Google 等）— 新手引导会提示你输入

使用 node --version 检查你的 Node 版本。
Windows 用户： 支持原生 Windows 和 WSL2。WSL2 更稳定，
推荐用于完整体验。参见 Windows。
需要安装 Node？参见 Node 设置。

快速设置

bash
curl -fsSL https://openclaw.ai/install.sh | bash



powershell
iwr -useb https://openclaw.ai/install.ps1 | iex

<Note>
其他安装方式（Docker、Nix、npm）：[安装](/zh-CN/install)。
</Note>

bash
openclaw onboard --install-daemon

向导会引导你选择模型提供商、设置 API key，
并配置 Gateway 网关。大约需要 2 分钟。

完整参考见 [新手引导（CLI）](/zh-CN/start/wizard)。

bash
openclaw gateway status

你应该会看到 Gateway 网关正在监听端口 18789。

bash
openclaw dashboard

这会在你的浏览器中打开 Control UI。如果它能加载，说明一切正常。

在 Control UI 聊天中输入一条消息，你应该会收到 AI 回复。

想改用手机聊天？最快可设置的渠道是
[Telegram](/zh-CN/channels/telegram)（只需要一个 bot token）。所有选项见 [渠道](/zh-CN/channels)。

如果你维护本地化或自定义的仪表板构建，请将
gateway.controlUi.root 指向一个包含已构建静态
资源和 index.html 的目录。

mkdir -p "$HOME/.openclaw/control-ui-custom"
# Copy your built static files into that directory.

然后设置：

{
  "gateway": {
    "controlUi": {
      "enabled": true,
      "root": "$HOME/.openclaw/control-ui-custom"
    }
  }
}

重启 Gateway 网关并重新打开仪表板：

openclaw gateway restart
openclaw dashboard

下一步

Discord、Feishu、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等。


控制谁可以给你的智能体发消息。


模型、工具、沙箱和高级设置。


浏览器、exec、Web 搜索、skills 和插件。

如果你将 OpenClaw 作为服务账号运行，或想使用自定义路径：

• OPENCLAW_HOME — 用于内部路径解析的主目录
• OPENCLAW_STATE_DIR — 覆盖状态目录
• OPENCLAW_CONFIG_PATH — 覆盖配置文件路径

完整参考：环境变量。

相关内容

• 安装概览
• 渠道概览
• 设置

📄 新手引导（CLI）

原文：https://docs.openclaw.ai/zh-CN/start/wizard

CLI 新手引导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的推荐方式。
它会在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、技能和工作区默认值。

openclaw onboard

最快开始第一次聊天：打开控制 UI（无需设置渠道）。运行
openclaw dashboard 并在浏览器中聊天。文档：仪表板。

稍后重新配置：

openclaw configure
openclaw agents add <name>

--json 不表示非交互模式。脚本请使用 --non-interactive。

CLI 新手引导包含一个 Web 搜索步骤，你可以在其中选择提供商，
例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、
Ollama Web Search、Perplexity、SearXNG 或 Tavily。某些提供商需要
API key，而其他提供商无需密钥。你也可以稍后使用
openclaw configure --section web 配置此项。文档：Web 工具。

快速开始与高级

新手引导从快速开始（默认值）与高级（完全控制）开始。

- 本地 Gateway 网关（loopback）
- 工作区默认值（或现有工作区）
- Gateway 网关端口 18789
- Gateway 网关认证 Token（自动生成，即使在 loopback 上也是如此）
- 新本地设置的工具策略默认值：tools.profile: "coding"（保留现有显式 profile）
- 私信隔离默认值：本地新手引导会在未设置时写入 session.dmScope: "per-channel-peer"。详情：CLI 设置参考
- Tailscale 暴露关闭
- Telegram + WhatsApp 私信默认使用允许列表（系统会提示你输入电话号码）

- 暴露每个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。

新手引导会配置什么

本地模式（默认）会引导你完成以下步骤：

1. 模型/认证 — 选择任意受支持的提供商/认证流程（API key、OAuth 或提供商专用手动认证），包括 Custom Provider
   （OpenAI 兼容、Anthropic 兼容或 Unknown 自动检测）。选择默认模型。
   安全注意事项：如果此 agent 将运行工具或处理 webhook/hooks 内容，请优先选择可用的最强最新一代模型，并保持工具策略严格。较弱/较旧的层级更容易被提示注入。
   对于非交互运行，--secret-input-mode ref 会在认证 profile 中存储由环境变量支持的引用，而不是明文 API key 值。
   在非交互 ref 模式中，必须设置提供商环境变量；如果没有该环境变量却传入内联密钥 flag，会快速失败。
   在交互运行中，选择密钥引用模式可让你指向环境变量或已配置的提供商引用（file 或 exec），并在保存前进行快速预检验证。
   对于 Anthropic，交互式新手引导/配置会提供 Anthropic Claude CLI 作为首选本地路径，并提供 Anthropic API key 作为推荐生产路径。Anthropic setup-token 也仍作为受支持的 token-auth 路径可用。
2. 工作区 — agent 文件的位置（默认 ~/.openclaw/workspace）。会生成引导文件。
3. Gateway 网关 — 端口、绑定地址、认证模式、Tailscale 暴露。
   在交互式 token 模式中，选择默认明文 token 存储，或选择使用 SecretRef。
   非交互 token SecretRef 路径：--gateway-token-ref-env <ENV_VAR>。
4. 渠道 — 内置和捆绑的聊天渠道，例如 iMessage、Discord、Feishu、Google Chat、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 等。
5. 守护进程 — 安装 LaunchAgent（macOS）、systemd 用户单元（Linux/WSL2），或原生 Windows 计划任务，并带有按用户 Startup 文件夹的回退方案。
   如果 token 认证需要 token 且 gateway.auth.token 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的 token 持久化到 supervisor 服务环境元数据中。
   如果 token 认证需要 token 且配置的 token SecretRef 未解析，守护进程安装会被阻止，并给出可操作指导。
   如果同时配置了 gateway.auth.token 和 gateway.auth.password，且未设置 gateway.auth.mode，守护进程安装会被阻止，直到显式设置模式。
6. 健康检查 — 启动 Gateway 网关并验证它正在运行。
7. Skills — 安装推荐 Skills 和可选依赖项。

重新运行新手引导不会清除任何内容，除非你明确选择重置（或传入 --reset）。
CLI --reset 默认重置配置、凭据和会话；使用 --reset-scope full 可包含工作区。
如果配置无效或包含旧版键名，新手引导会要求你先运行 openclaw doctor。

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

添加另一个 agent

使用 openclaw agents add <name> 创建一个独立 agent，它有自己的工作区、
会话和认证 profile。不带 --workspace 运行会启动新手引导。

它会设置：

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

注意：

• 默认工作区遵循 ~/.openclaw/workspace-<agentId>。
• 添加 bindings 可路由入站消息（新手引导可以执行此操作）。
• 非交互 flag：--model、--agent-dir、--bind、--non-interactive。

完整参考

有关详细的分步说明和配置输出，请参阅
CLI 设置参考。
有关非交互示例，请参阅 CLI 自动化。
有关更深入的技术参考（包括 RPC 详情），请参阅
新手引导参考。

相关文档

• CLI 命令参考：openclaw onboard
• 新手引导概览：新手引导概览
• macOS 应用新手引导：新手引导
• Agent 首次运行仪式：Agent 引导启动

📄 新手引导（macOS 应用）

原文：https://docs.openclaw.ai/zh-CN/start/onboarding

本文档描述了当前首次运行设置流程。目标是提供顺畅的“第 0 天”体验：选择 Gateway 网关运行位置、连接凭证、运行向导，并让智能体完成自举。
有关新手引导路径的总体概览，请参阅新手引导概览。

安全信任模型：

• 默认情况下，OpenClaw 是个人智能体：单个受信任操作者边界。
• 共享/多用户设置需要锁定（拆分信任边界、尽量减少工具访问权限，并遵循安全）。
• 本地新手引导现在会将新配置默认设为 tools.profile: "coding"，因此新的本地设置会保留文件系统/运行时工具，而无需强制使用无限制的 full 配置文件。
• 如果启用了钩子/webhook 或其他不受信任的内容源，请使用强大的现代模型档位，并保持严格的工具策略/沙箱隔离。

Gateway 网关在哪里运行？

• 这台 Mac（仅本地）： 新手引导可以在本地配置凭证并写入凭证。
• 远程（通过 SSH/Tailnet）： 新手引导不会配置本地凭证；凭证必须已存在于 Gateway 网关主机上。
• 稍后配置： 跳过设置，并让应用保持未配置状态。

Gateway 网关凭证提示：

• 向导现在即使对 loopback 也会生成一个 token，因此本地 WS 客户端必须进行身份验证。
• 如果你禁用凭证，任何本地进程都可以连接；仅在完全受信任的机器上这样做。
• 对多机器访问或非 loopback 绑定使用 token。

新手引导会请求以下所需的 TCC 权限：

• 自动化（AppleScript）
• 通知
• 辅助功能
• 屏幕录制
• 麦克风
• 语音识别
• 摄像头
• 位置

此步骤为可选
应用可以通过 npm、pnpm 或 bun 安装全局 openclaw CLI。
它会优先使用 npm，然后是 pnpm；只有在检测到 bun 是唯一的
包管理器时才会使用 bun。对于 Gateway 网关运行时，Node 仍然是推荐路径。


设置完成后，应用会打开一个专用的新手引导聊天会话，让智能体可以
介绍自己并指导后续步骤。这会将首次运行指导与你的常规对话分开。
有关首次智能体运行期间 Gateway 网关主机上发生的事情，请参阅自举。

相关

• 新手引导概览
• 入门指南