5676a6b38d
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style Tests: pnpm docs:build
7.2 KiB
read_when, summary, title, x-i18n
| read_when | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
入门指南：从零开始到发送第一条消息（向导、认证、渠道、配对） | 入门指南 |
|
入门指南
目标：从 零开始 → 第一次成功聊天 （使用合理的默认配置）尽可能快地完成。
最快聊天方式：打开控制界面（无需设置渠道）。运行 openclaw dashboard
然后在浏览器中聊天，或打开 http://127.0.0.1:18789/ （在 Gateway网关主机上）。
文档： 仪表盘 和 控制界面。
推荐路径：使用 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）。 参见 网络工具。
macOS：如果你计划构建应用程序，请安装 Xcode / CLT。如果仅使用 CLI + Gateway网关，Node 就足够了。 Windows：使用 WSL2 （推荐 Ubuntu）。强烈推荐使用 WSL2；原生 Windows 未经测试，问题较多，且工具兼容性较差。请先安装 WSL2，然后在 WSL 内执行 Linux 步骤。参见 Windows (WSL2)。
1）安装 CLI（推荐）
curl -fsSL https://openclaw.bot/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 二维码登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
- 守护进程：后台安装（launchd/systemd；WSL2 使用 systemd）
- 运行时：Node（推荐；WhatsApp/Telegram 必需）。Bun 为 不推荐。
- Gateway网关令牌：向导默认会生成一个（即使在 local loopback 上）并将其存储在
gateway.auth.token。
向导文档： 向导
凭证：存储位置（重要）
-
推荐的 Anthropic 路径： 设置 API 密钥（向导可以将其存储以供服务使用）。
claude setup-token：你可以复用 Claude Code 凭据。 -
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
仪表盘（本地 local loopback）： http://127.0.0.1:18789/
如果配置了令牌，请将其粘贴到控制界面设置中（存储为 connect.params.auth.token）。
⚠️ Bun 警告（WhatsApp + Telegram）： Bun 在这些渠道上存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 **Node **。
3.5）快速验证（2 分钟）
openclaw status
openclaw health
openclaw security audit --deep
4）配对 + 连接你的第一个聊天界面
WhatsApp（二维码登录）
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 # auto-installs UI deps on first run
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网关请求健康快照。