OpenClaw VPS 部署完整教程
本教程已根据两轮官方文档校对进行修正，覆盖启动命令、onboarding 参数、Telegram pairing 流程、服务管理、Docker 标准流程、systemd linger 等关键细节。所以，我觉得已经蛮完整的了，当然后续可能会视情况继续更改。
零、3 分钟最短速通版（新手先看这里，先跑出来一个大致结果会心理上比较有成就感）
复杂配置可以之后慢慢加，先用这 4 条命令确认 OpenClaw 能在你的服务器上跑起来：
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway --port 18789
openclaw dashboard
最后一步会打开浏览器控制台。先用浏览器确认 OpenClaw 能正常工作，再去接 Telegram、MCP、Docker 等扩展配置。
一、为什么要部署在 VPS 上？
OpenClaw 是一个运行在自己服务器上的 AI 代理平台，支持通过 Telegram 等消息渠道发送自然语言指令来控制它完成任务——整理邮件、管理代码仓库、自动化工作流等。将它部署在 VPS 而非本地电脑有以下核心优势：
- 24/7 在线：本地电脑关机代理即失联，VPS 保持持续运行
- 安全隔离：OpenClaw 拥有对所在机器的完整访问权限，专用 VPS 避免污染个人设备
- 更低延迟：数据中心带宽和响应速度通常优于家用宽带
- 团队共享：一台 VPS 可供小团队共用同一个 AI 助手实例
二、硬件配置要求
| 场景 | CPU | 内存 | 硬盘 | 备注 |
|---|---|---|---|---|
| 最低（可能不稳定） | 1 vCPU | 2 GB | 20 GB SSD | 仅供测试 |
| 推荐（日常使用） | 2 vCPU | 4 GB | 40 GB SSD | 生产首选 |
| 本地 LLM（Ollama） | 6+ vCPU | 30 GB+ | 80 GB SSD | 需 GPU 12GB VRAM |
⚠️ 官方文档标注最低 1 GB RAM，但实测安装过程中极易触发内存溢出，强烈建议至少 2 GB，推荐 4 GB。
推荐操作系统：Ubuntu 22.04 LTS 或 24.04 LTS
三、VPS 初始化准备
3.1 连接服务器
ssh root@你的VPS_IP地址
3.2 更新系统
apt update && apt upgrade -y
3.3 创建专用用户（强烈推荐）
OpenClaw 拥有对运行机器的完整访问权限，不应以 root 身份运行：
# 创建专用用户
adduser openclaw
# 赋予 sudo 权限
usermod -aG sudo openclaw
# 切换到新用户（后续所有操作均在此用户下执行）
su - openclaw
四、安装 OpenClaw
4.1 确认 Node.js 环境（需要 Node 22+）
安装脚本会尝试自动处理依赖，但手动会更加稳妥一些：
# 安装 Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs
# 验证版本
node -v # 应显示 v22.x.x
npm -v
4.2 运行官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash
官方建议：除非有特殊原因，否则请使用此安装器，不要手动安装。
安装完成后脚本通常会直接进入 Onboarding 向导。若跳过，手动运行下面命令（必须带 --install-daemon 参数，这会一并安装后台守护进程）：
openclaw onboard --install-daemon
注意！只写
openclaw onboard不会自动安装守护进程，需要后续单独配置服务。官方推荐始终带--install-daemon参数。
五、Onboarding 引导配置详解
步骤 1：安全确认
⚠️ I understand this is powerful and inherently risky. Continue?
仔细阅读后选择 Yes。OpenClaw 可以访问你的文件系统和终端，请确保它运行在独立的 VPS 环境中。
步骤 2：选择启动模式
QuickStart / Advanced
新手建议选择 QuickStart，快速完成基础配置。
步骤 3：选择 AI 模型提供商
Which provider do you want to use as your default?
> Anthropic
OpenAI
Google Gemini
Local (Ollama)
...
默认选择 Anthropic（Claude 系列，太贵了，openclaw运行消耗的token非常之多，不是土豪根本用不起，大家要细细考虑，国外的几个模型都不便宜，言尽于此）。
步骤 4：输入 API Key
Paste your Anthropic API key: sk-ant-xxxxxxxxxxxxx
步骤 5：选择默认模型
向导会列出当时可用的模型，以向导实际显示为准，不要照抄网上教程里的具体版本号，那些很容易过时。
步骤 6：配置消息渠道
Which messaging channel do you want to use?
> Telegram ← 推荐，国外服务器还是推荐这个，当然钉钉也可以，但是要自己创建一个团队，才能创建钉钉机器人
WhatsApp
iMessage
Skip
选择 Telegram 后，系统会引导你填写 Bot Token（创建方式见第十一节）。渠道配置完成后，Telegram 的实际接入还需要一个 pairing（配对） 步骤，详见第十一节。
步骤 7：Shell 补全 & 包管理器
Shell 补全建议选 Yes，包管理器选 npm 即可。
六、启动 Gateway（网关服务）
启动命令为
openclaw gateway --port 18789。
6.1 调试用：前台直接启动
测试阶段可以前台运行查看实时日志：
openclaw gateway --port 18789
6.2 生产环境：使用官方服务管理命令（推荐）
OpenClaw 提供了内置的服务管理命令，比手写 systemd 文件更规范：
# 将 Gateway 安装为系统服务（开机自启）
openclaw gateway install
# 查看服务状态
openclaw gateway status
# 重启服务
openclaw gateway restart
# 停止服务
openclaw gateway stop
在 Linux 上 openclaw gateway install 默认使用 systemd 用户服务。用户服务有一个非常容易踩的坑：用户退出 SSH 登录后，用户级 systemd 服务默认会停止运行。对于长期运行的 VPS，必须执行下面这条命令：
sudo loginctl enable-linger openclaw
这会让 openclaw 用户的 systemd 服务在该用户未登录时也持续保活。这一步不做的话，重启或退出登录后 Gateway 会悄悄停掉，所以openclaw会不回答。
6.3 验证运行状态
# 综合健康检查（安装后第一步就跑这个）
openclaw doctor
# 查看运行状态摘要
openclaw status
# 查看 Gateway 专项状态
openclaw gateway status
# 健康端点检查
openclaw health
七、关键安全配置
7.1 Gateway 绑定本地地址（防止暴露公网）
OpenClaw Gateway 默认绑定到 127.0.0.1（本地回环地址），核心配置项为 gateway.mode=local。用以下命令验证：
openclaw gateway status
# 确认监听地址为 127.0.0.1:18789 而非 0.0.0.0:18789
0.0.0.0:18789意味着 Gateway 暴露在公网，任何人都可以访问。必须确保是127.0.0.1。
7.2 配置防火墙（UFW）
# 设置默认策略
sudo ufw default deny incoming
sudo ufw default allow outgoing
# 只开放 SSH，并限速防暴力破解
sudo ufw allow 22/tcp
sudo ufw limit 22/tcp
# 如有 Web 服务则开放 80/443
# sudo ufw allow 80/tcp
# sudo ufw allow 443/tcp
# 启用防火墙
sudo ufw enable
# 查看规则
sudo ufw status numbered
不要将 18789 端口开放到公网！不要将 18789 端口开放到公网！不要将 18789 端口开放到公网！将所有远程访问应通过 SSH 隧道或 Tailscale 进行。
7.3 通过 SSH 隧道远程访问控制台
在本地电脑上运行：
ssh -L 18789:127.0.0.1:18789 openclaw@你的VPS_IP
然后在本地浏览器访问：http://127.0.0.1:18789
7.4 Telegram 群组访问收敛
如果你把 Bot 加入了群组，默认行为通常是"仅响应提及（@mention）"。可以通过 channels.telegram.groups 配置项做 allowlist，限制 Bot 只响应指定群组，并要求明确 @mention 才触发。不要一上来就让 Bot 对所有群组消息都响应。
八、Docker 部署方式（可选）
Docker 部署提供更好的环境隔离，迁移也更方便。
8.1 官方推荐流程（从仓库根目录运行）
官方当前推荐的 Docker 方式是在克隆仓库后，从根目录运行官方脚本，它会自动构建镜像、执行 onboarding、启动 compose 并生成 token：
./docker-setup.sh
若需要手动执行每一步，官方流程如下：
# 1. 构建本地镜像
docker build -t openclaw:local -f Dockerfile .
# 2. 运行 onboarding（交互式，会生成配置）
docker compose run --rm openclaw-cli onboard
# 3. 启动 Gateway
docker compose up -d openclaw-gateway
⚠️ 以上命令均需在仓库根目录下执行。onboarding、dashboard token、设备批准等流程都依赖这个标准路径。
8.2 进阶：手动 docker-compose.yml 自定义
如果有特殊需求需要自定义，以下是参考示例。注意这不是官方主推流程，和官方后续文档的服务名、配置项可能存在差异，需要自行对照：
version: "3.8"
services:
openclaw:
image: ghcr.io/openclaw/openclaw:latest
container_name: openclaw-gateway
restart: always
ports:
- "127.0.0.1:18789:18789" # 只绑定本地，不暴露公网
volumes:
- ~/openclaw/data:/home/node/.openclaw # 数据持久化
environment:
- NODE_ENV=production
- OPENCLAW_NO_RESPAWN=1
- ANTHROPIC_API_KEY=sk-ant-你的Key
- TELEGRAM_BOT_TOKEN=你的BotToken
extra_hosts:
- "host.docker.internal:host-gateway" # 容器访问宿主机服务（如 Postgres）
# 启动
cd ~/openclaw
docker compose up -d
# 查看日志
docker compose logs -f
# 更新
docker compose pull && docker compose up -d
# Docker 下打开 dashboard
docker compose run --rm openclaw-cli dashboard --no-open
九、OpenClaw 核心参数配置
运行 openclaw configure 进入交互式配置菜单，以下是关键参数：
| 参数 | 说明 | 推荐值 |
|---|---|---|
gateway.mode |
Gateway 绑定模式 | local（绑定 127.0.0.1） |
gateway.port |
监听端口 | 18789（默认） |
gateway.auth.token |
Gateway 访问令牌 | 自动生成，妥善保存 |
model.default |
默认 AI 模型 | 以向导显示为准，推荐 Sonnet 档 |
memory.enabled |
是否启用长期记忆 | true |
workspace.path |
工作区路径 | ~/.openclaw/workspace |
十、接入外部 MCP Server（工具扩展）
MCP（Model Context Protocol）是开放协议，允许 AI 助手通过标准接口调用外部工具和数据源。OpenClaw 内置 MCP 客户端支持，配置后 Agent 可以直接发现并调用所有 MCP 工具。
10.1 MCP 工作原理
你（Telegram 消息）
↓
OpenClaw Agent（理解意图，决定调用哪个工具）
↓
MCP Client（向对应 Server 发起请求）
↓
MCP Server（Notion / GitHub / PostgreSQL / 文件系统 ...）
↓
返回结果给 Agent，Agent 组织成自然语言回复你
10.2 配置方式：编辑 openclaw.json
nano ~/.openclaw/openclaw.json
配置结构如下（修改后需重启 Gateway 生效）：
{
"mcp": {
"servers": {
"服务名称": {
"command": "npx",
"args": ["-y", "包名"],
"env": {
"API_KEY": "你的Key"
},
"transport": "stdio"
}
}
}
}
配置是严格校验的。 未知字段不会被忽略，而是可能直接导致 Gateway 启动失败。修改后如果无法启动，先运行
openclaw doctor并用python3 -m json.tool ~/.openclaw/openclaw.json检查 JSON 格式。
10.3 常用配置示例
Notion：
{
"mcp": {
"servers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/mcp"],
"env": { "NOTION_API_KEY": "secret_xxxx" },
"transport": "stdio"
}
}
}
}
GitHub：
{
"mcp": {
"servers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" },
"transport": "stdio"
}
}
}
}
通过命令行添加远程 HTTP MCP Server：
openclaw mcp add \
--transport http \
--scope user \
tavily \
"https://mcp.tavily.com/mcp/?tavilyApiKey=你的Key"
多个 MCP Server 并列配置：
{
"mcp": {
"servers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/mcp"],
"env": { "NOTION_API_KEY": "secret_xxxx" },
"transport": "stdio"
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" },
"transport": "stdio"
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/openclaw/workspace"],
"transport": "stdio"
}
}
}
}
10.4 Python 实现的 MCP Server（使用 uvx）
部分 MCP Server 是用 Python 编写的，需要用 uvx 而非 npx 运行：
# 先安装 uv（包含 uvx）
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
{
"mcp": {
"servers": {
"slack": {
"command": "uvx",
"args": ["mcp-server-slack"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-你的SlackBotToken",
"SLACK_TEAM_ID": "T你的TeamID"
},
"transport": "stdio"
}
}
}
}
10.5 常用 MCP Server 速查表
| MCP Server | npm 包名 | 主要功能 | 所需凭证 |
|---|---|---|---|
| Notion | @notionhq/mcp |
笔记/数据库/页面 | NOTION_API_KEY |
| GitHub | @modelcontextprotocol/server-github |
Issue/PR/代码 | GITHUB_PERSONAL_ACCESS_TOKEN |
| PostgreSQL | @modelcontextprotocol/server-postgres |
SQL 查询 | 连接字符串 |
| 文件系统 | @modelcontextprotocol/server-filesystem |
读写本地文件 | 目录路径 |
| Tavily 搜索 | tavily-mcp |
联网搜索 | TAVILY_API_KEY |
| Slack | mcp-server-slack（uvx） |
消息/频道管理 | SLACK_BOT_TOKEN |
| SQLite | @modelcontextprotocol/server-sqlite |
本地 SQLite | db 文件路径 |
| Puppeteer | @modelcontextprotocol/server-puppeteer |
浏览器自动化 | 无 |
更多 MCP Server 可在 github.com/modelcontextprotocol/servers 浏览官方维护列表。
10.6 验证 MCP 连接状态
# 列出所有已注册的 MCP Server 及其状态
openclaw mcp list
# 查看某个 Server 提供的工具列表
openclaw mcp tools notion
# 实时查看详细日志（排查连接问题）
openclaw gateway --verbose
十一、连接 Telegram 并开始使用
11.1 创建 Telegram Bot
- 在 Telegram 中搜索并打开
@BotFather - 发送
/newbot - 输入 Bot 名称（如
My OpenClaw） - 输入 Bot 用户名（必须以
bot结尾，如myopenclaw_bot） - 复制 BotFather 返回的 HTTP API Token，在 Onboarding 向导中粘贴
11.2 Pairing（配对）：首次接入的正确流程
Telegram 接入默认采用 pairing 模式，不是直接在聊天里输入 Gateway Token。正确流程如下：
- 确保 Gateway 已启动（
openclaw gateway status） - 在 Telegram 中直接私信你的 Bot，发送任意消息
- 系统进入配对等待状态，在服务器端运行以下命令查看待批准的配对码：
openclaw pairing list telegram
- 找到配对码后批准它：
openclaw pairing approve telegram <CODE>
完成后，Telegram 即可正常发送指令给 OpenClaw。
为什么是这个流程？ Pairing 模式防止任何人私信你的 Bot 就能控制你的服务器——只有经过服务端手动批准的设备才能接入。这是一个安全设计。
11.3 接入成功后可以做什么
帮我整理一下今天的邮件，把重要的标记出来
在我的 GitHub 上创建一个新 issue，标题是「修复登录 bug」
设置一个每周一早上 9 点提醒我查看周报的定时任务
十二、日志查看与排障
# 实时跟踪日志（最常用）
openclaw logs --follow
# Gateway 详细模式（调试启动问题）
openclaw gateway --verbose
# 综合健康检查
openclaw doctor
# 运行状态摘要
openclaw status
# 健康端点检查
openclaw health
遇到 Gateway 无法启动时，排查顺序：openclaw doctor → openclaw gateway --verbose → 检查 ~/.openclaw/openclaw.json 格式。
十三、升级、备份与回滚
13.1 查看当前版本
openclaw --version
13.2 升级前先备份
# 备份整个配置目录（包含 token、MCP 配置、workspace 等）
cp -r ~/.openclaw ~/.openclaw.bak.$(date +%Y%m%d)
13.3 升级
curl -fsSL https://openclaw.ai/install.sh | bash
13.4 升级后验证
openclaw doctor
openclaw status
openclaw health
如果升级后出现问题，将 ~/.openclaw.bak.* 还原，再降级或等待修复版本。
十四、常见问题排查
Q：安装时报内存错误？
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
Q：Gateway 无法启动？
sudo lsof -i :18789 # 检查端口占用
openclaw doctor # 综合诊断
openclaw gateway --verbose # 详细日志
python3 -m json.tool ~/.openclaw/openclaw.json # 检查配置文件格式
Q：退出 SSH 后 Gateway 自动停了？
sudo loginctl enable-linger openclaw
Q：Telegram Bot 无响应？
openclaw gateway status
openclaw pairing list telegram
# 如果有待审批配对码：
openclaw pairing approve telegram <CODE>
Q：MCP Server 显示 error: spawn npx ENOENT？
which npx && npx --version
# 如不可用：
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs
Q：修改 openclaw.json 后 Gateway 拒绝启动？
python3 -m json.tool ~/.openclaw/openclaw.json # 检查 JSON 格式
openclaw doctor
Q：配置修改后 MCP 不生效？
openclaw gateway restart
十五、核心命令速查
| 阶段 | 命令 | 说明 |
|---|---|---|
| 安装 | curl -fsSL https://openclaw.ai/install.sh \| bash |
官方安装脚本 |
| Onboarding | openclaw onboard --install-daemon |
引导配置 + 安装守护进程 |
| 打开控制台 | openclaw dashboard |
浏览器控制台，先在这确认能跑 |
| 健康检查 | openclaw doctor |
安装后第一步 |
| 调试启动 | openclaw gateway --port 18789 |
前台运行查看日志 |
| 安装服务 | openclaw gateway install |
注册为系统服务 |
| 保活设置 | sudo loginctl enable-linger openclaw |
退出登录后服务不停 |
| 查看状态 | openclaw gateway status |
服务运行状态 |
| 重启服务 | openclaw gateway restart |
重启 Gateway |
| 实时日志 | openclaw logs --follow |
日常运维首选 |
| 详细日志 | openclaw gateway --verbose |
调试启动问题 |
| 配置 | openclaw configure |
交互式配置菜单 |
| Telegram 配对 | openclaw pairing list telegram |
查看待批准配对码 |
| 批准配对 | openclaw pairing approve telegram <CODE> |
批准 Telegram 接入 |
| MCP 列表 | openclaw mcp list |
查看已加载 Server |
| 版本查看 | openclaw --version |
当前版本号 |
本文基于 OpenClaw 2026.x 版本及两轮官方文档校对修订。如遇版本差异，请以 docs.openclaw.ai 官方文档为准。