Ubuntu 安装部署 OpenClaw AI 详细教程自托管 AI 智能体 Gateway 网关 — 多渠道、开源、本地优先的智能助手平台Ubuntu 20.04 / 22.04 / 24.04Node.js 2410 聊天渠道MIT 开源 教程目录OpenClaw AI 简介架构与工作原理系统要求安装 Node.js安装 OpenClaw三种方式新手引导配置验证安装使用 Control UI 仪表板连接聊天渠道Docker 部署方式服务器部署与运维常用配置说明常见问题排查部署检查清单1OpenClaw AI 简介OpenClaw俗称小龙虾是一款本地优先、开源、跨平台的 AI 智能体 Gateway 网关。它不是云端 SaaS而是直接运行在你自己的电脑或服务器上通过赋予模型手脚让 AI 从被动回答问题升级为主动完成任务。核心特性自托管在你的硬件上按你的规则运行数据完全可控多渠道 Gateway 网关单个 Gateway 支持 Discord、Telegram、WhatsApp、Signal、Slack、飞书、微信等 10 聊天渠道智能体原生支持工具使用、会话、记忆、多智能体路由插件市场ClawHub 插件生态可扩展渠道和能力媒体支持发送和接收图像、音频及文档Web Control UI浏览器仪表板用于聊天、配置和会话管理移动节点支持 iOS / Android 节点配对Canvas、相机和语音工作流开源MIT 许可证由 OpenClaw 基金会社区驱动支持的聊天渠道主流渠道TelegramDiscordWhatsAppSignalSlackMicrosoft Teams其他渠道飞书 / Google ChatiMessageMatrixZaloWebChat网页聊天更多可通过插件扩展和其他 AI 助手的区别OpenClaw 不是又一个聊天机器人而是一个Gateway 网关。你把它部署在服务器上连接各种聊天应用然后在任何地方都能和你的 AI 助手对话——就像跟朋友发消息一样自然。2架构与工作原理聊天应用Discord/Telegram/WhatsApp... ↔ OpenClaw Gateway会话·路由·渠道连接 ↔ AI 智能体工具·记忆·多模型 ↔ 模型提供商Anthropic/OpenAI/Google...核心组件组件作用Gateway 网关会话、路由和渠道连接的唯一事实来源管理所有消息流渠道插件连接各个聊天平台的适配器一个 Gateway 可同时接多个渠道智能体运行时处理 AI 对话、工具调用、记忆管理Control UI浏览器仪表板用于聊天、配置和会话管理节点NodeiOS/Android/本地设备端提供屏幕、相机、Canvas 能力ClawHub插件市场可扩展渠道和技能配置与数据位置配置文件~/.openclaw/openclaw.json状态目录~/.openclaw/默认端口18789Control UI 和 Gateway API3系统要求3.1 最低要求项目最低要求推荐配置Ubuntu 版本20.0422.04 LTS / 24.04 LTSNode.js22.22.3 或 24.15Node 24.x默认目标版本CPU1 核2 核及以上内存1 GB2 GB运行沙箱时建议 4GB硬盘空间1 GB5 GB网络能访问模型 API稳定的互联网连接3.2 准备 API Key你需要至少一个 AI 模型提供商的 API Key。支持的主要提供商提供商说明Anthropic (Claude)推荐质量最佳OpenAIGPT 系列模型Google (Gemini)Gemini 系列本地模型支持 Ollama 等本地模型服务新手建议先准备好一个 API Key比如 Anthropic 或 OpenAI 的新手引导时会用到。之后可以随时添加更多提供商。4安装 Node.jsOpenClaw 需要 Node.js 22.22.3、24.15 或 25.9推荐使用 Node 24。4.1 方式一使用 NodeSource 仓库推荐# 添加 NodeSource Node.js 24.x 仓库 $ curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - # 安装 Node.js $ sudo apt install -y nodejs # 验证 $ node --version # v24.x.x $ npm --version # 10.x.x4.2 方式二使用 nvm多版本管理# 安装 nvm $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重新加载 shell $ source ~/.bashrc # 安装 Node 24 $ nvm install 24 $ nvm use 24 # 验证 $ node --version4.3 方式三让安装脚本自动安装如果你使用官方安装脚本下一节它会自动检测并安装所需版本的 Node.js可以跳过这一步。注意Ubuntu 22.04 默认仓库的 Node.js 版本是 12.x24.04 默认是 18.x都低于要求。请务必使用上面的方式安装 Node 24。5安装 OpenClaw三种方式方式一一键安装脚本 推荐最简单最快的方式自动检测系统、安装 Node、安装 OpenClaw 并启动新手引导。$ curl -fsSL https://openclaw.ai/install.sh | bash如果不想运行新手引导$ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard方式二npm 全局安装如果你已经自行安装了 Node.js可以直接用 npm 安装$ npm install -g openclawlatest # 然后运行新手引导并安装守护进程 $ openclaw onboard --install-daemonpnpm 用户需要先批准构建脚本pnpm add -g openclawlatest pnpm approve-builds -g openclaw onboard --install-daemon方式三本地前缀安装隔离安装高级将 OpenClaw 和 Node 都保存在本地前缀~/.openclaw下不依赖系统级 Node 安装$ curl -fsSL https://openclaw.ai/install-cli.sh | bash从 GitHub 源码安装开发者$ git clone https://github.com/openclaw/openclaw.git $ cd openclaw $ pnpm install pnpm build pnpm ui:build $ pnpm link --global $ openclaw onboard --install-daemon从源码安装需要 pnpm如果没有 pnpm先执行npm install -g pnpm6新手引导配置安装完成后运行新手引导完成初始配置$ openclaw onboard --install-daemon新手引导会引导你完成以下设置选择模型提供商— 选择你想用的 AI 模型Anthropic、OpenAI、Google 等输入 API Key— 输入对应的 API 密钥Gateway 配置— 设置网关监听地址和端口安装守护进程—--install-daemon参数会自动安装 systemd 用户服务开机自启渠道配对可选— 可以先跳过之后再配置引导完成标志提示 Gateway 网关已启动并正在运行显示访问地址和端口默认 18789。跳过某些步骤如果想先快速跑起来渠道配对、Skills 安装等都可以跳过之后用以下命令继续配置$ openclaw configure # 修改配置 $ openclaw channels add # 添加新渠道7验证安装7.1 检查 CLI 是否可用$ openclaw --version # 输出类似openclaw/0.x.x linux-x64 node-v24.x.x7.2 运行健康检查$ openclaw doctor # 检查配置问题、环境状态等7.3 检查 Gateway 状态$ openclaw gateway status正常输出应包含Gateway is running PID: 12345 Port: 18789 Uptime: 2m 30s7.4 常用管理命令命令作用openclaw gateway start启动 Gatewayopenclaw gateway stop停止 Gatewayopenclaw gateway restart重启 Gatewayopenclaw gateway status查看状态openclaw gateway logs查看日志openclaw dashboard打开 Control UI8使用 Control UI 仪表板8.1 打开仪表板$ openclaw dashboard这会在默认浏览器中打开 Control UI。8.2 手动访问如果浏览器没有自动打开手动访问本地地址http://127.0.0.1:18789/8.3 仪表板功能聊天界面和 AI 助手对话多会话管理文件上传下载代码块渲染配置管理模型提供商设置渠道管理插件安装安全设置8.4 测试第一条消息在 Control UI 聊天框中输入一条消息比如你好如果收到 AI 回复说明一切运行正常。9连接聊天渠道OpenClaw 最强大的功能之一是多渠道支持。下面以最容易配置的 Telegram 为例9.1 快速连接 Telegram第 1 步创建 Telegram Bot在 Telegram 中搜索BotFather发送/newbot命令按提示设置 bot 名称和用户名BotFather 会给你一个Bot Token保存下来第 2 步在 OpenClaw 中添加 Telegram 渠道$ openclaw channels add telegram按提示输入 Bot Token 即可。第 3 步开始聊天在 Telegram 中找到你刚创建的 bot发送一条消息AI 就会回复。9.2 其他渠道渠道难度说明Telegram⭐ 最简单只需 Bot TokenDiscord⭐⭐创建 Discord 应用和 BotWhatsApp⭐⭐⭐需要 WhatsApp Business API 或网页版Signal⭐⭐⭐需要 Signal 账号飞书⭐⭐创建飞书应用Slack⭐⭐创建 Slack App9.3 控制谁可以访问可以配置白名单只允许特定用户使用# 编辑配置文件 $ nano ~/.openclaw/openclaw.json添加允许列表{ channels: { telegram: { allowFrom: [15555550123, your_username] } } }安全提醒在公共渠道群聊中使用时建议设置requireMention: true只有 机器人时才会回复避免误触发。10Docker 部署方式10.1 前置条件$ sudo apt install -y docker.io docker-compose-v2 $ sudo usermod -aG docker $USER $ newgrp docker # 使组权限立即生效 $ docker --version $ docker compose version10.2 使用预构建镜像# 创建数据目录 $ mkdir -p ~/.openclaw # 运行容器 $ docker run -d \ --name openclaw \ -p 18789:18789 \ -v ~/.openclaw:/root/.openclaw \ --restart unless-stopped \ ghcr.io/openclaw/openclaw:latest10.3 使用 Docker Compose$ mkdir -p ~/openclaw-docker cd ~/openclaw-docker $ cat docker-compose.yml EOF services: openclaw: image: ghcr.io/openclaw/openclaw:latest container_name: openclaw ports: - 18789:18789 volumes: - ~/.openclaw:/root/.openclaw restart: unless-stopped EOF $ docker compose up -d10.4 从源码构建镜像$ git clone https://github.com/openclaw/openclaw.git $ cd openclaw $ ./scripts/docker/setup.shDocker 镜像来源官方镜像发布在 GitHub Container Registryghcr.io/openclaw/openclaw和 Docker Hubopenclaw/openclaw。请使用官方镜像避免使用非官方来源。11服务器部署与运维11.1 在 VPS 上部署在云服务器上部署 OpenClaw 的流程和本地基本一致但需要注意安全配置。安全最佳实践不要把 Gateway 暴露到公网默认绑定 127.0.0.1通过 SSH 隧道或 Tailscale 访问配置访问令牌设置gateway.auth.token或gateway.auth.password使用 HTTPS对外暴露时必须使用反向代理 SSL限制渠道访问配置allowFrom白名单定期备份备份~/.openclaw/目录11.2 通过 SSH 隧道远程访问# 在你的本地电脑上执行建立 SSH 端口转发 $ ssh -L 18789:localhost:18789 useryour-server-ip # 然后本地浏览器访问 # http://localhost:1878911.3 配置 Nginx 反向代理可选$ sudo apt install -y nginx $ sudo tee /etc/nginx/sites-available/openclaw EOF server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:18789; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 支持 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } } EOF $ sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ $ sudo nginx -t $ sudo systemctl restart nginx11.4 systemd 服务管理使用--install-daemon安装后OpenClaw 会作为 systemd 用户服务运行# 查看服务状态 $ systemctl --user status openclaw-gateway # 查看日志 $ journalctl --user -u openclaw-gateway -f $ openclaw gateway logs # 更简单的方式11.5 性能调优低配机器如果在小内存 VPS 或 ARM 主机上运行缓慢可以启用 Node 模块编译缓存$ grep -q NODE_COMPILE_CACHE/var/tmp/openclaw-compile-cache ~/.bashrc || cat ~/.bashrc EOF export NODE_COMPILE_CACHE/var/tmp/openclaw-compile-cache mkdir -p /var/tmp/openclaw-compile-cache export OPENCLAW_NO_RESPAWN1 EOF $ source ~/.bashrc11.6 更新 OpenClaw# 更新到最新稳定版 $ openclaw update # 切换到开发版 $ openclaw update --channel dev # 切换回稳定版 $ openclaw update --channel stable12常用配置说明12.1 配置文件位置~/.openclaw/openclaw.json12.2 多模型提供商配置{ providers: { anthropic: { apiKey: sk-ant-... }, openai: { apiKey: sk-... } }, agents: { defaults: { model: claude-3-5-sonnet-20240620 } } }12.3 渠道白名单配置{ channels: { telegram: { allowFrom: [your_username], groups: { *: { requireMention: true } } }, whatsapp: { allowFrom: [8613800138000] } }, messages: { groupChat: { mentionPatterns: [openclaw] } } }12.4 Gateway 安全配置{ gateway: { bind: 127.0.0.1, port: 18789, auth: { password: your-secure-password } } }修改配置后重启 Gatewayopenclaw gateway restart12.5 环境变量变量作用OPENCLAW_HOME主目录路径OPENCLAW_STATE_DIR覆盖状态目录OPENCLAW_CONFIG_PATH覆盖配置文件路径OPENCLAW_NO_RESPAWN禁用进程重生小内存机器有用NODE_COMPILE_CACHENode 模块编译缓存路径13常见问题排查13.1 命令找不到openclaw: command not found几乎都是 PATH 问题npm 的全局二进制目录不在 shell 的 PATH 中。# 检查 Node 是否安装 $ node -v # 查找全局包位置 $ npm prefix -g # 检查 PATH $ echo $PATH # 如果不在 PATH 中添加到 .bashrc $ echo export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc $ source ~/.bashrc13.2 Gateway 启动失败# 查看详细日志 $ openclaw gateway logs # 运行健康检查 $ openclaw doctor # 检查端口是否被占用 $ sudo lsof -i :1878913.3 端口 18789 被占用# 修改配置文件中的端口 $ nano ~/.openclaw/openclaw.json # 修改 gateway.port 为其他端口例如 18790 $ openclaw gateway restart13.4 API Key 无效 / 模型调用失败# 重新配置提供商 $ openclaw configure # 检查网络连接 $ curl -I https://api.anthropic.com13.5 升级后出问题# 回退到上一个版本 $ openclaw update --version 0.x.x # 或者运行 doctor 诊断 $ openclaw doctor13.6 卸载 OpenClaw$ openclaw gateway stop $ openclaw gateway uninstall $ npm uninstall -g openclaw # 彻底删除数据谨慎操作 $ rm -rf ~/.openclaw14部署检查清单基础环境Ubuntu 20.04 / 22.04 / 24.04 系统Node.js 24.x 已安装npm / pnpm 可用网络能访问模型 API安装与配置OpenClaw CLI 可正常运行openclaw --version新手引导完成API Key 已配置Gateway 守护进程已安装并运行功能验证Control UI 可以访问http://127.0.0.1:18789能正常和 AI 聊天对话至少一个渠道已连接可选openclaw doctor无严重错误服务器部署安全检查Gateway 绑定 127.0.0.1不直接暴露公网配置了访问密码或令牌渠道设置了白名单有定期备份策略防火墙配置正确 部署完成你现在拥有了一个完全自托管的 AI 智能体 Gateway 网关。可以通过 Control UI 在浏览器中聊天或者连接 Telegram、Discord 等渠道在手机上随时使用。接下来可以探索安装插件、添加更多渠道、配置多智能体、连接本地模型等。官方网站openclaw.ai | 文档docs.openclaw.ai | GitHubopenclaw/openclaw