929a3725d3
* docs(navigation): canonicalize paths and align zh nav * chore(docs): remove stray .DS_Store * docs(scripts): add non-mint docs link audit * docs(nav): fix zh source paths and preserve legacy redirects (#11428) (thanks @sebslight) * chore(docs): satisfy lint for docs link audit script (#11428) (thanks @sebslight)
7.0 KiB
read_when, summary, title, x-i18n
| read_when | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
新手指南：从零到第一条消息（向导、认证、渠道、配对） | 入门指南 |
|
入门指南
目标：尽快从零到第一个可用聊天（使用合理的默认值）。
最快聊天：打开 Control UI（无需渠道设置）。运行 openclaw dashboard 并在浏览器中聊天，或在 Gateway 网关主机上打开 http://127.0.0.1:18789/。文档：Dashboard 和 Control UI。
推荐路径：使用 CLI 新手引导向导（openclaw onboard）。它设置：
- 模型/认证（推荐 OAuth）
- Gateway 网关设置
- 渠道（WhatsApp/Telegram/Discord/Mattermost（插件）/...）
- 配对默认值（安全私信）
- 工作区引导 + Skills
- 可选的后台服务
如果你想要更深入的参考页面，跳转到：向导、设置、配对、安全。
沙箱注意事项：agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（默认 "main"），因此群组/渠道会话会被沙箱隔离。如果你想要主智能体始终在主机上运行，设置显式的每智能体覆盖：
{
"routing": {
"agents": {
"main": {
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "off" }
}
}
}
}
0) 前置条件
- Node
>=22 pnpm（可选；如果从源代码构建则推荐）- **推荐：**Brave Search API 密钥用于网页搜索。最简单的方式：
openclaw configure --section web（存储tools.web.search.apiKey）。参见 Web 工具。
macOS：如果你计划构建应用，安装 Xcode / CLT。仅用于 CLI + Gateway 网关的话，Node 就足够了。 Windows：使用 WSL2（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经测试，问题更多，工具兼容性更差。先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 Windows (WSL2)。
1) 安装 CLI（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash
安装程序选项（安装方法、非交互式、从 GitHub）：安装。
Windows (PowerShell)：
iwr -useb https://openclaw.ai/install.ps1 | iex
替代方案（全局安装）：
npm install -g openclaw@latest
pnpm add -g openclaw@latest
2) 运行新手引导向导（并安装服务）
openclaw onboard --install-daemon
你将选择：
- 本地 vs 远程 Gateway 网关
- 认证：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic 我们推荐 API 密钥；也支持
claude setup-token。 - 提供商：WhatsApp QR 登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
- 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
- 运行时：Node（推荐；WhatsApp/Telegram 必需）。不推荐 Bun。
- Gateway 网关令牌：向导默认生成一个（即使在 loopback 上）并存储在
gateway.auth.token。
向导文档：向导
凭证：存储位置（重要）
-
**推荐的 Anthropic 路径：**设置 API 密钥（向导可以为服务使用存储它）。如果你想复用 Claude Code 凭证，也支持
claude setup-token。 -
OAuth 凭证（旧版导入）：
~/.openclaw/credentials/oauth.json -
认证配置文件（OAuth + API 密钥）：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
无头/服务器提示：先在普通机器上完成 OAuth，然后将 oauth.json 复制到 Gateway 网关主机。
3) 启动 Gateway 网关
如果你在新手引导期间安装了服务，Gateway 网关应该已经在运行：
openclaw gateway status
手动运行（前台）：
openclaw gateway --port 18789 --verbose
Dashboard（local loopback）：http://127.0.0.1:18789/
如果配置了令牌，将其粘贴到 Control UI 设置中（存储为 connect.params.auth.token）。
⚠️ **Bun 警告（WhatsApp + Telegram）：**Bun 与这些渠道存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 Node 运行 Gateway 网关。
3.5) 快速验证（2 分钟）
openclaw status
openclaw health
openclaw security audit --deep
4) 配对 + 连接你的第一个聊天界面
WhatsApp（QR 登录）
openclaw channels login
通过 WhatsApp → 设置 → 链接设备扫描。
WhatsApp 文档：WhatsApp
Telegram / Discord / 其他
向导可以为你写入令牌/配置。如果你更喜欢手动配置，从这里开始：
- Telegram：Telegram
- Discord：Discord
- Mattermost（插件）：Mattermost
**Telegram 私信提示：**你的第一条私信会返回配对码。批准它（见下一步），否则机器人不会响应。
5) 私信安全（配对审批）
默认姿态：未知私信会获得一个短代码，消息在批准之前不会被处理。如果你的第一条私信没有收到回复，批准配对：
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>
配对文档：配对
从源代码（开发）
如果你正在开发 OpenClaw 本身，从源代码运行：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon
如果你还没有全局安装，从仓库通过 pnpm openclaw ... 运行新手引导步骤。pnpm build 也会打包 A2UI 资源；如果你只需要运行那个步骤，使用 pnpm canvas:a2ui:bundle。
Gateway 网关（从此仓库）：
node openclaw.mjs gateway --port 18789 --verbose
7) 验证端到端
在新终端中，发送测试消息：
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
如果 openclaw health 显示"未配置认证"，回到向导设置 OAuth/密钥认证——没有它智能体将无法响应。
提示：openclaw status --all 是最佳的可粘贴、只读调试报告。
健康探测：openclaw health（或 openclaw status --deep）向运行中的 Gateway 网关请求健康快照。