OpenClaw 在 Ubuntu 22.04 上的安装与初始化指南

一、环境准备：使用 NVM 管理 Node.js

这是最稳妥的方式，能避免系统级 Node.js 版本冲突。我们推荐使用 NVM（Node Version Manager）来管理运行环境。

1. 安装依赖与 NVM

首先确保 curl 和 wget 可用，然后安装 NVM 的最新稳定版。

sudo apt update && sudo apt install -y curl wget
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

2. 激活环境变量

安装完成后终端不会立即识别 nvm 命令，需要手动加载配置。Ubuntu 默认使用 bash，如果是 zsh 则需对应修改。

source ~/.bashrc
# 如果是 zsh 终端，执行：source ~/.zshrc

3. 验证安装

nvm -v
# 输出版本号（如 0.39.7）即表示成功

4. 安装 Node.js

建议安装最新的 LTS 版本以保证稳定性。

# 安装最新 LTS 版本
nvm install --lts
# 或指定版本（如 20.x）
nvm install 20
# 查看已安装版本
nvm list
# 切换到指定版本
nvm use 20
# 验证 Node.js 和 npm 版本
node -v
npm -v

5. 优化：配置国内镜像

为了解决下载慢的问题，可以永久配置淘宝镜像。

echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.bashrc
source ~/.bashrc

二、安装 OpenClaw

1. 运行安装脚本

通过 npm 全局安装并运行新手引导是最推荐的方式。

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

如果需要查看安装器标志位，可执行：

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

注意：安装过程可能需要 10 分钟以上，请耐心等待。

2. 安装成功示意

安装成功后，终端会显示相关确认信息。

三、初始化向导详解

1. 风险提示

系统会提示安全风险。如果你是个人本地使用且理解风险，选择 Yes 继续；如果是团队或多用户场景，建议选择 No，先完成安全加固和权限隔离。

2. 部署模式选择

这是初始化流程中的关键决策点，主要有两种模式：

选项	核心逻辑	适用场景
Quickstart（快速启动）	采用默认配置，跳过详细设置	个人测试、本地体验、功能验证
Manual（手动配置）	交互式逐一设置核心参数	团队部署、公网暴露、生产环境

优先选 Quickstart：首次接触 OpenClaw，仅需本地测试 AI 代理的文件操作、命令执行等基础能力，或部署环境为本地隔离环境。
必须选 Manual：计划将 OpenClaw 暴露至公网、局域网，或供多用户/团队使用，需自定义安全策略。

后续操作指引

选择 Quickstart 后：部署完成后，执行 openclaw configure 补全 API 密钥、工具启用列表及安全审计规则。
选择 Manual 后：跟随交互式提示依次完成网关配置、大模型参数、工具权限及安全配置，无需后续补配。

3. 模型/认证提供商选择

根据需求选择合适的大模型服务：

国际主流：OpenAI (Codex QAUTH + API key)、Anthropic (Claude)、xAI (Grok)、Google (Gemini)。
国内主流：BytePlus、Moonshot AI (Kimi K2.5)、Qwen、Z.AI、Qianfan、Xiaomi 等。
聚合网关：OpenRouter、Cloudflare AI Gateway、Vercel AI Gateway。
自定义：Custom Provider（支持私有部署）。
暂时跳过：Skip for now（后续通过 openclaw configure 补全）。

选型建议：个人快速体验优先选 OpenAI 或 OpenRouter；国内环境可选 Moonshot 或 Qwen；已有统一网关的团队直接选对应选项。

4. 对接通义千问（Qwen）的 OAuth 授权

若选择 Qwen，需完成 OAuth 授权流程：

完成授权：登录通义千问账号，输入用户码或直接确认授权。
等待连接：终端显示 "Waiting for Qwen OAuth approval…"，自动获取访问令牌。

打开授权链接：

https://chat.qwen.ai/authorize?user_code=CEEGL6GX&client=qwen-code

常见问题：链接无法访问请检查网络；授权超时需重新发起；确保账号已开通 API 访问权限。

5. 配置界面解读

授权完成后，界面会显示配置状态：

Qwen OAuth complete：授权成功。
Model configured：默认模型为 qwen-portal/coder-model。
Token 自动刷新：令牌会自动刷新，失败需重新登录。
Default model：可选择保持当前代码模型，或手动输入私有模型名称。

6. 频道（Channels）工作原理

OpenClaw 支持多种通讯渠道接入，核心是安全机制和各渠道特点：

DM 安全：陌生私信要求配对码，防止未授权访问。公网部署建议关闭 allowFrom=["*"]，改用白名单。
多用户 DM：通过配置隔离会话，避免跨用户权限泄露。

常见渠道接入方式：

渠道	接入方式	特点
Telegram	Bot Token	简单入门，生态成熟
WhatsApp	绑定号码	支持度高，注意隐私
Discord	原生支持	开发者友好，社区活跃
Feishu（飞书）	企业级消息	适合国内团队协作
Slack	Socket Mode	企业级协作，实时事件
其他	Webhook/API	如 Google Chat, Signal, LINE 等

7. 插件安装（以飞书为例）

配置飞书频道时，有三种插件安装选项：

Download from npm：从官方仓库下载最新版，适合首次安装。
Use local plugin path：使用本地已存在的插件目录，适合调试。
Skip for now：暂时跳过，后续补全。

选型建议：首次使用选 Download from npm；本地开发调试选 Use local plugin path。

凭证配置步骤

访问飞书开放平台，创建自建应用。
获取 App ID 和 App Secret。
启用必要权限（如 im:message, im:chat）。
发布应用或加入测试组。
在 OpenClaw 中配置环境变量或交互式输入。

安全加固建议

显式信任插件：设置 plugins.allow，仅允许飞书插件加载。
权限最小化：仅启用所需的最小权限集。
凭证保护：不要硬编码 App Secret，优先使用环境变量。

8. App Secret 存储方式

Enter App Secret：直接存储在配置文件中，适合个人测试，安全性较低。
Use external secret provider：使用外部密钥管理服务（如 Vault），适合生产环境，安全性高。

9. 连接模式选择

WebSocket (default)：OpenClaw 主动建立长连接，无需公网 IP，适合本地测试。
Webhook：飞书服务器推送 HTTP 请求，需公网 IP 或域名，适合生产环境。

10. 群组聊天策略配置

Allowlist：仅在白名单群组响应，最安全，适合企业协作。
Open (requires mention)：所有群组响应但需提及，兼顾便利与安全。
Disabled：禁用群组响应，仅私信可用，隐私性最高。

11. 群组 ID 白名单

填写多个群组 ID 时用英文逗号分隔，格式通常为 oc_ 开头。需在飞书客户端群设置中复制群 ID。

12. 最终校验与重复插件警告

配置完成后，可能会检测到重复插件 ID 警告（例如 feishu 插件）。这通常是因为重复安装导致的。

解决方案：

停止服务：systemctl stop openclaw-gateway
清理重复插件：删除多余的插件文件夹，保留一个版本。
强制指定信任插件：openclaw config set plugins.allow '["/root/.openclaw/extensions/feishu/index.ts"]'
重启服务：systemctl start openclaw-gateway

13. Web 搜索工具配置

用于让智能体具备联网查询能力：

Brave Search：结构化结果，隐私友好。
Gemini (Google Search)：基于 Google 搜索，结果全面。
Kimi (Moonshot)：对中文内容支持更好。
Perplexity Search：深度分析，引用来源。

选型建议：中文场景优先 Kimi；精准结构化选 Brave；已用 Gemini 模型则选 Gemini Search。

14. Skills 状态汇总

初始化后的技能状态汇总界面显示：

Eligible：满足依赖条件的技能数量。
Missing requirements：缺少依赖的技能数量。
Unsupported on this OS：不兼容操作系统的技能。

建议：优先启用核心技能（文件操作、代码执行），按需安装缺失依赖。

15. 依赖安装处理

如果安装 github 技能失败，通常是因为缺少 Homebrew 或 gh 命令行工具。OpenClaw 会提示安装 Homebrew 或手动安装 gh。

16. 其他可选技能配置

以下技能可根据需求选择是否配置 API Key：

goplaces：地点查询和地图功能（需 Google Places API Key）。
nano-banana-pro：增强 AI 能力（需 Gemini API Key）。
notion：笔记/知识库交互（需 Notion API Key）。
openai-image-gen：图像生成（需 OpenAI API Key）。
openai-whisper-api：语音转文字（需 OpenAI API Key）。
sag：语音合成（需 ElevenLabs API Key）。

若无特定需求，选择 No 跳过即可，不影响核心功能。

17. Hooks 配置

Hooks 用于在智能体执行命令时自动触发操作：

boot-md：启动时生成 Markdown 报告。
command-logger：记录所有执行的命令，便于审计。
session-memory：保存会话上下文。

建议启用 command-logger 以便追踪操作历史。

18. 启动 Gateway 服务

启动时会进行系统检查：

Systemd Lingering：确保服务在用户登出后继续运行。
Node.js 版本：若系统默认版本过低（如 v12），会自动切换至 nvm 管理的 v24+ 版本。建议后续升级系统默认 Node.js 版本以避免兼容性问题。

19. 日志与故障排查

启动日志可能包含两类问题：

重复插件警告：非致命，但建议清理冗余插件文件。
飞书频道启动失败：错误 API error: app do not have bot。解决方法是在飞书开放平台启用'机器人'功能，并确保事件订阅 URL 和权限范围正确。

20. 智能体孵化与 Dashboard

最后一步是选择如何'孵化'智能体：

Hatch in TUI (recommended)：终端对话方式配置，个性化体验最佳。
Open the Web UI：浏览器图形化配置。
Do this later：稍后配置。

Dashboard 访问方式：

本地访问：http://127.0.0.1:18789/#token=XXXXXXXXXXX
远程访问：建立 SSH 隧道后访问 localhost:18789

ssh -N -L 18789:127.0.0.1:18789 [email protected]

下一步：访问 Dashboard 开始配置，修复飞书频道问题，并根据需要启用更多技能和 Hooks。