Ubuntu安装OpenClaw

2026年3月5日 · 阅读需 11 分钟

本文档说明在 Ubuntu 系统上安装 Node.js 22、安装 OpenClaw，并配置 阿里云百炼千问 模型的完整步骤。

一、环境要求

系统：Ubuntu（推荐 20.04 / 22.04 LTS）
Node.js：≥ 22.12.0（OpenClaw 强制要求）
内存：建议 ≥ 4GB
网络：可访问阿里云百炼 API（dashscope.aliyuncs.com）

二、安装 Node.js 22

NodeSource PPA（推荐，系统级安装）

# 更新并安装依赖
sudo apt update && sudo apt install -y curl

# 添加 Node.js 22 源并安装
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs build-essential

# 验证
node -v   # 应显示 v22.x.x
npm -v

三、安装 OpenClaw

一键安装（推荐）

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

脚本会自动检测/安装 Node.js 并安装 OpenClaw。安装完成后执行：

openclaw onboard --install-daemon

按向导完成：工作区、安全设置、频道等；模型可先跳过，后面单独配置百炼。

使用 npm 安装（已具备 Node 22 时）

sudo npm install -g openclaw@latest
openclaw onboard --install-daemon

四、获取阿里云百炼 API Key

登录阿里云百炼（Model Studio）（默认地域：华北2 北京）。
进入 「密钥管理」，点击 「创建 API Key」。
复制生成的 API Key（仅创建时可见，请妥善保存）。

新用户可在百炼平台领取免费调用额度用于测试。

五、配置阿里云百炼千问模型

百炼提供 OpenAI 兼容接口，OpenClaw 通过 baseUrl + apiKey 即可接入。

5.1 编辑 OpenClaw 配置文件

配置文件路径：~/.openclaw/openclaw.json。

在 models.providers 中新增百炼 provider（或合并到现有 JSON），例如：

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "YOUR_DASHSCOPE_API_KEY",
        "api": "openai-completions",
        "models": [
          { "id": "qwen-plus", "name": "通义千问 Plus" },
          { "id": "qwen-turbo", "name": "通义千问 Turbo" },
          { "id": "qwen-max", "name": "通义千问 Max" },
          { "id": "qwen3-max", "name": "通义千问3 Max" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "bailian/qwen-plus" },
      "models": {
        "bailian/qwen-plus": { "alias": "千问" },
        "bailian/qwen-turbo": {},
        "bailian/qwen-max": {},
        "bailian/qwen3-max": {}
      }
    }
  }
}

说明：

baseUrl（按地域选一）：
- 华北2（北京）：https://dashscope.aliyuncs.com/compatible-mode/v1
apiKey：替换为你的百炼 API Key；若已设置 DASHSCOPE_API_KEY，部分版本支持在 apiKey 处填 "dashscope" 从环境变量读取。
agents.defaults.model.primary：默认使用的模型，如 bailian/qwen-plus。
模型 ID 以百炼文档为准，常见：qwen-turbo、qwen-plus、qwen-max、qwen3-max 等。

若已有其他 provider（如 qwen-portal），保留原有配置，在 providers 下增加 bailian 即可。

5.2 使用 CLI 设置默认模型（可选）

openclaw models set primary bailian/qwen-plus
openclaw models list

六、开启远程访问

OpenClaw 不允许对非本机地址使用明文 ws://（会报 SECURITY ERROR 并导致网关退出）。远程访问请二选一：

推荐：方案 A — 网关保持 bind: "loopback"，用 SSH 隧道 从本机访问（无需在公网暴露 18789，最安全）。
方案 B — 若必须用公网 IP 直连，需在网关前配置 HTTPS/WSS（如 Nginx/Caddy 反向代理或 Tailscale），使用 wss:// 后再设 bind: "lan"。

6.1 方案 A：loopback + SSH 隧道（推荐）

网关只监听本机，远程通过 SSH 端口转发访问，无需放行 18789、也无明文暴露。

（1）编辑 ~/.openclaw/openclaw.json，在 gateway 段中确保：

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "controlUi": {
    "allowedOrigins": [
      "http://127.0.0.1:18789",
      "http://localhost:18789"
    ]
  },
  "auth": {
    "mode": "token",
    "token": "你的访问令牌"
  }
}

说明：mode: "local" 表示本机/隧道访问；若设为 "remote"，OpenClaw 会要求先完成远程配置（如 WSS），否则网关进程会拒绝启动并报错 "Gateway start blocked"（见常见问题）。

（2）在服务器上启动网关

openclaw gateway start
# 或：systemctl --user restart openclaw-gateway.service

（3）在你自己的电脑上建立 SSH 隧道

ssh -N -L 18789:127.0.0.1:18789 user@YOUR_SERVER_IP

保持该终端不关闭。然后在浏览器打开：http://localhost:18789（或带 Token：http://localhost:18789/?token=你的访问令牌）。
注意：Token 必须用 查询参数 ?token=xxx，不要用 #token=xxx（井号是锚点，不会发给服务器）。此时流量经 SSH 加密，无需在安全组开放 18789。

6.2 方案 B：公网 IP 直连（需 HTTPS/WSS）

若必须通过 http://<公网IP>:18789 直接访问，OpenClaw 要求使用 wss://，不能使用明文 ws://。做法是：

用 Nginx/Caddy 等反向代理在 443 上提供 HTTPS，并代理 WebSocket 到 http://127.0.0.1:18789。
网关保持 bind: "loopback"，仅被反向代理访问。
浏览器和 CLI 使用 https://你的域名 / wss://你的域名，不要用 http://IP:18789。

也可使用 Tailscale Serve/Funnel 等方式提供 HTTPS 远程访问。具体反向代理配置可参考官方文档。

若之前已设置 bind: "lan" 且出现 SECURITY ERROR，请先改回 bind: "loopback" 并用方案 A 或完成 WSS 后再考虑 lan。

6.3 使用 CLI 设置（可选）

# 使用本机模式 + 本机监听（推荐，配合 SSH 隧道）
openclaw config set gateway.mode "local"
openclaw config set gateway.bind "loopback"

6.4 重启网关使配置生效

systemctl --user restart openclaw-gateway.service
# 或
openclaw gateway start

6.5 访问方式小结

本机：http://localhost:18789 或 http://127.0.0.1:18789
远程（方案 A）：先执行 ssh -N -L 18789:127.0.0.1:18789 user@服务器IP，再访问 http://localhost:18789（带 Token 时用 ?token=你的令牌，不要用 #token=...）
远程（方案 B）：通过已配置的 HTTPS 地址访问（如 https://你的域名）

不能通过 http://公网IP:18789 直连：OpenClaw 禁止对非本机使用明文 WebSocket，网关在 loopback 时也不会监听公网口，会连接失败或由前置代理返回 502。请用方案 A（SSH 隧道）或方案 B（HTTPS 反向代理）。

七、端口与防火墙

若使用方案 A（SSH 隧道）：无需在安全组开放 18789，只需保证 SSH（22）可访问即可。
若使用方案 B（HTTPS 直连）：在安全组放行 443（及 80，若用 HTTP 跳转 HTTPS）；网关仍只监听本机，不直接暴露 18789。

若有回调需求（如部分频道），再按需放行 80 等端口。

八、启动与验证

# 若已安装 daemon，可直接启动网关
openclaw gateway start

# 或以后台/服务方式运行（根据你 onboard 时是否安装了 daemon）
# 例如：systemctl start openclaw 或使用 openclaw 自带 daemon

本地访问：http://localhost:18789
远程访问：先建立 SSH 隧道（见第六节），再访问 http://localhost:18789；或使用已配置的 HTTPS 地址

在控制台 Models 或对话页选择千问（或对应 alias）发起对话，能正常回复即表示百炼千问已接通。

九、常用命令

命令	说明
`openclaw doctor`	检查环境与配置
`openclaw models list`	列出已配置模型
`openclaw models set primary <provider/model>`	设置默认模型
`openclaw config get models.providers.bailian.baseUrl`	查看某 provider 配置
`openclaw gateway start`	启动网关

十、常见问题

Node 版本不足
执行 node -v，若低于 22，请用第二节中 NodeSource 安装 Node 22 后重装 OpenClaw。
百炼调用失败 / 401
- 检查 apiKey 是否正确、未过期。
- 确认百炼控制台已开通对应模型（如 qwen-plus）。
- 若用环境变量，确认 source ~/.bashrc 后当前 shell 中 echo $DASHSCOPE_API_KEY 有值。
无法访问控制台
- 确认 openclaw gateway start 已运行。
- 检查安全组是否放行 18789。
能打开页面但显示"与网关断开"或无法连接
- 若用 SSH 隧道，确保隧道已建立且浏览器访问的是 http://localhost:18789。
- 检查 gateway.controlUi.allowedOrigins 是否包含你实际访问的 Origin（本机访问时需有 http://127.0.0.1:18789、http://localhost:18789）。
- 修改配置后需重启网关：systemctl --user restart openclaw-gateway.service 或重新执行 openclaw gateway start。
远程访问出现 502 Bad Gateway
- 若用 SSH 隧道：502 多为网关未运行或隧道未生效。在服务器上执行 openclaw gateway status 确认 Runtime 为 running；在本机确认隧道进程在运行，浏览器访问 http://localhost:18789（不要用 127.0.0.1 或其它地址）。
- 若用 Nginx/Caddy 等反向代理：502 表示代理无法从上游 http://127.0.0.1:18789 拿到正常响应。请先：
  1. 在服务器上确认网关在运行：curl -I http://127.0.0.1:18789/ 应返回 200 或 3xx。
  2. 代理需正确转发 WebSocket（Upgrade、Connection: upgrade、proxy_http_version 1.1），例如 Nginx：
    location / { proxy_pass http://127.0.0.1:18789; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }
  3. 重载代理配置后重启网关：systemctl --user restart openclaw-gateway.service。
SECURITY ERROR: Gateway URL uses plaintext ws:// to a non-loopback address
- OpenClaw 禁止对非本机使用明文 WebSocket（ws://），否则会退出。
- 处理：将 gateway.bind 改为 "loopback"，用 SSH 隧道远程访问（见第六节方案 A）；或先配置好 HTTPS/WSS 再使用 bind: "lan"。
- 可执行 openclaw doctor --fix 按提示修复，或参考官方文档。
Gateway start blocked: set gateway.mode=local (current: remote) or pass --allow-unconfigured
- 当 gateway.mode 为 "remote" 时，OpenClaw 要求完成远程配置（如 WSS）才允许网关子进程启动，否则会直接退出（exit 1）。
- 处理：若使用 loopback + SSH 隧道，将 gateway.mode 改为 "local"：
```
openclaw config set gateway.mode "local"
systemctl --user restart openclaw-gateway.service
```
- 若必须保留 mode: "remote"，可在 systemd 服务中为网关命令加上 --allow-unconfigured（需自行编辑 ~/.config/systemd/user/openclaw-gateway.service 的 ExecStart）。
网关启动后立即退出（Runtime: stopped, last exit 1 / RPC probe: 1006 abnormal closure）
- 说明进程启动后很快崩溃，需看具体报错。在服务器上执行：
```
cat /tmp/openclaw/openclaw-YYYY-MM-DD.log
journalctl --user -u openclaw-gateway.service -n 100 --no-pager
```
- 常见原因：gateway.mode=remote 未配置完成（见上条）、Node 版本不足（需 ≥ 22）、端口被占用、配置文件 JSON 或某字段错误、工作区/目录权限。
- 可先运行 openclaw doctor 做环境检查；再前台启动看报错：
```
openclaw gateway --port 18789
```
  根据终端输出或日志中的堆栈信息排查。
国内服务器选地域
使用华北2（北京）时，百炼 baseUrl 用 https://dashscope.aliyuncs.com/compatible-mode/v1 即可。
No API key found for provider "anthropic"

报错说明当前 agent 在尝试使用 Anthropic（Claude），但未配置对应 API key。若你只使用千问、未购买 Anthropic，应让 agent 使用百炼并为其配置认证。
处理步骤（在服务器上执行）：
1. 确认实际生效的配置：OpenClaw 读取的是 ~/.openclaw/openclaw.json（不是项目里的副本）。若你是在本仓库改的配置，请把 models 与 agents.defaults.model / agents.defaults.models 同步到服务器上的 ~/.openclaw/openclaw.json，并确保 agents.defaults.model.primary 为 bailian/qwen-plus（或你使用的千问模型）。
2. 为 agent 配置百炼认证：在服务器上执行（将 main 换成报错里提到的 agent id）：
```
openclaw agents add main
```
  按提示为 bailian（或 dashscope）provider 配置 API key；若已设置环境变量 DASHSCOPE_API_KEY，可查看文档是否支持填 dashscope 或留空从环境变量读取。
3. （可选）仅用千问、禁用 anthropic：若希望该 agent 只使用百炼，可在该 agent 的配置或频道中指定模型为 bailian/qwen-plus，避免默认或技能去选 anthropic。
若报错提示从 main agent 复制 auth：说明是某个子 agent 缺少 auth 文件，可把主 agent 的 auth 复制过去（仅当主 agent 已配置好百炼认证时有用）：
```
cp ~/.openclaw/agents/main/agent/auth-profiles.json ~/.openclaw/agents/<报错中的agentDir>/auth-profiles.json
```
复制后确认该 auth 文件中包含 bailian/dashscope 的配置，且默认模型为千问。

一、环境要求​

二、安装 Node.js 22​

NodeSource PPA（推荐，系统级安装）​

三、安装 OpenClaw​

一键安装（推荐）​

使用 npm 安装（已具备 Node 22 时）​

四、获取阿里云百炼 API Key​

五、配置阿里云百炼千问模型​

5.1 编辑 OpenClaw 配置文件​

5.2 使用 CLI 设置默认模型（可选）​

六、开启远程访问​

6.1 方案 A：loopback + SSH 隧道（推荐）​

6.2 方案 B：公网 IP 直连（需 HTTPS/WSS）​

6.3 使用 CLI 设置（可选）​

6.4 重启网关使配置生效​

6.5 访问方式小结​

七、端口与防火墙​

八、启动与验证​

九、常用命令​

十、常见问题​

十一、参考链接​