OpenClaw 从安装到稳定运行：超详细配置教程（Debian/Ubuntu/WSL，含工具权限/浏览器/通道/排错）

2.1 推荐环境#

• 系统：Debian / Ubuntu（WSL 同样适用）

  完全体的 OpenClaw 还是建议在 macOS 上运行，不过不是所有人都有Mac Mini，也不是所有人都有一个云端或者本地的 Linux 环境，因此如果你是 Windows 用户，更建议你使用 WSL 安装 OpenClaw。

  虽然 OpenClaw官方支持 Windows 平台，你也能在 Windows 平台上安装 OpenClaw，但是目前所有模型对于 Powershell 命令的支持并不好，因此不建议使用 Windows 部署。

• 用户：建议使用普通用户运行（非 root）

  如果你跟笔者一样对于 Linux 系统足够有信心，选择 root 用户也未尝不可。

• 网络：可访问 OpenClaw 官方脚本地址、你使用的模型 API 地址。

  一般来说服务器在中国香港或者国外则没有配置门槛，唯一需要担心的是 IP Quality，即 IP 要足够干净才能正常访问 ChatGPT 或是 Gemini。

2.2 基础依赖#

1
sudo apt update && sudo apt upgrade -y
2
sudo apt install -y curl git jq

2.3 可选但建议的前置检查#

1
# 时间是否正确（证书和 API 请求很依赖时间）
2
date
3

4
# DNS 基础可用性
5
getent hosts openclaw.ai
6

7
# 当前是否已装过 openclaw
8
command -v openclaw || echo "openclaw not found"

3.1 nvm && npm 安装#

Install & Update Script

遵循上面的安装教程。先执行

1
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

或

1
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

安装后让环境变量立即在当前 session 生效：

1
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
2
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

然后执行下面命令以安装npm和node：

1
nvm install --lts

3.1 npm 换源#

如果你的部署机器在国内，为了加速下载，可将 npm 换为国内淘宝源。

1
npm config set registry https://registry.npmmirror.com
2
npm config get registry # 查看当前镜像源

如果命令无效，请关闭终端重新打开

3.2 npm 安装 openclaw#

1
npm i -g openclaw

3.2 安装后第一轮验收#

1
openclaw --version
2
openclaw status

如果命令不存在，大概率是 PATH 未生效，开一个新终端再试。

4.1 向导配置#

如果安装后没自动进入向导，需要手动执行：

1
openclaw onboard

4.2 安全警告#

等待了一会，出现了安全警示，使用键盘的方向键调整到 Yes ，点击回车

4.3 快速开始#

此处选用快速开始，方便快速配置。

4.4 模型提供商#

向导里最重要的是模型部分（Model / Provider）：

• 你可以选官方提供方
• 也可以选 Custom Provider（兼容 OpenAI/Anthropic 的自建端点）

如果是 Custom Provider，通常需填写：

• baseUrl（常见为 https://xxx/v1）
• apiKey
• modelId

这里我们选用来自互联网大善人 OpenAI 的 ChatGPT（实际上是 Codex），个人免费账户有一定的额度但不多，这边建议购买一个月抛的 Team 席位。

你可前往小黄鱼购买，也可使用笔者提供的这两个链接：

ChatGPT Business Team 自助开通

Team Invite

购买成功后去邮箱里加入团队空间即可。

说明：开通后团队席位有效30天，30天后工作空间将无法进入。因此到期后你在工作空间里的聊天记录将不可访问。这里我们主要用到的是 Team 版的 Codex 额度，因此有关聊天记录在空间之间迁移的教程不做说明。

选择 OpenAI 后回车，使用 OAuth 方法登录。

这里需要保证你的配置机器可以访问 OpenAI。如果你在 WSL 中部署，请试图打开相关代理软件的虚拟网卡模式，或自行搜索 WSL 如何配置代理。连接实验室 WIFI OnePlus 13T 6666的同学可以直接使用，无需进行代理配置。

按住 Ctrl，单击链接，用本机浏览器打开 OpenAI OAuth 页面。登录你的 ChatGPT 账户，选择团队空间后登录。如果没有显示团队空间，请检查是否已经同意邀请加入团队空间。登录完成后会跳转到 localhost 页面，此时复制地址栏中地址粘贴回终端的 Paste the redirect URL处回车即可。如图所示。

选择模型，若无特殊需求选择最前沿模型即可。笔者这里选择了 openai-codex/gpt-5.4

4.5 配置消息渠道#

此处以 Telegram 渠道为例，如果你想配置 QQ 渠道，请先选择Skip for now。如果你想配置其他渠道，请查阅对应文档。

此处配置以 Telegram 渠道为例。同样的，需要保证你的机器支持连接 Telegram。假定你有 Telegram 账号，给 @BotFather 发消息 /newbot 创建新机器人。

新版 Telegram 似乎会在新弹出的窗口中让你创建机器人，如下图所示。

点击 Create a New Bot， 创建一个新机器人。

请详细阅读页面上的说明。机器人名字任取，但机器人的 username 需要以 _bot 结尾。

在此页面复制你的机器人密钥。请注意一定要妥善保管你的密钥，不要泄露。

此处选择 Enter Telegram bot token 后回车。

粘贴密钥后回车

4.6 配置Web Search服务#

这一块先跳过，因为这些api注册有点麻烦，箭头移动到最后的 Skip for now 暂时跳过。

4.7配置 Skills#

选择你想安装的 Skills，按空格打上勾，然后回车。

大部分 Skills 还是为 macOS 而设计，Skills 也可以后续让 AI 自动配置，因此如果这里你不想配置那么用空格打上 Skip for now 的勾然后回车。

4.8 其他 API 配置#

这些目前都不需要配置，不影响使用。如果你懂如何配置，请自行配置。

4.9 配置 Hooks#

这里这四个都要启用，然后回车。

4.10 完成配置#

如图正在安装 OpenClaw Gateway。

此处选择 Do this later，因为你目前没有配置 ssh隧道，也没有图形化浏览器

完成后先不要急着聊天，先体检：

1
openclaw config validate
2
openclaw doctor --deep

4.11 Telegram 侧配置#

Telegram 私聊默认通常是 pairing 机制（首次联系人需要配对批准）。

先查看待批准配对请求：

1
openclaw pairing list telegram

再用机器人回复给你的 code 进行批准：

1
openclaw pairing approve telegram <PAIRING_CODE>

例如 openclaw pairing approve telegram JNCRAMPD。

搜索找到你当时创建的机器人。例如我的是：@mjy_oc_bot

点击 消息（或 Message），输入 Start

按照提示在终端进行配置（把 code 换成你自己的）：

1
openclaw pairing approve telegram <PAIRING_CODE>

而后在 Telegram 对话窗口再次输入 /start

按照 AI 回复你的提示配置你的专属 OpenClaw。直接用中文回复即可。

4.12 配置与自检#

配置文件一般在：~/.openclaw/openclaw.json 每次改完配置建议先跑：

1
openclaw doctor --fix

再重启网关：

1
openclaw gateway stop
2
openclaw gateway start

5.1 远程服务器访问 Dashboard（SSH 隧道）#

如果 OpenClaw 跑在远程服务器，本地用 SSH 隧道访问最稳：

1
# 本地电脑执行
2
ssh -N -L 18789:127.0.0.1:18789 <user>@<server-ip>

然后本地浏览器打开：http://127.0.0.1:18789

如果页面提示未授权，先在服务器执行 openclaw dashboard --no-open，复制带 token 的地址打开即可。

8.1 无头服务器（Debian/Ubuntu）推荐方案#

1
# 1. 更新本地软件包索引，确保获取最新的依赖信息
2
sudo apt update
3
# dl.google.com 可能需要国际互联网连接
4
# 2. 下载适用于 Debian/Ubuntu 的 64位安装包 (.deb 格式)
5
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
6
# 3. 安装 Google Chrome
7
# apt install 会自动处理并安装缺失的依赖库（如 libgbm1, xdg-utils 等）
8
sudo apt install -y ./google-chrome-stable_current_amd64.deb
9
# 4. 安装中文字体，防止中文网页显示为方框（Tofu）
10
sudo apt install -y fonts-noto-cjk

1
# 1. 使用独立浏览器需要此配置
2
openclaw config set browser.defaultProfile "openclaw"
3
# 2. 服务器没有显示器，必须开启 无头模式 才能在后台静默运行
4
openclaw config set browser.headless true
5
# 3. 在 Linux 服务器（尤其是以 root 身份运行时）必须开启 禁用沙盒模式 ，否则 Chrome 会因权限安全机制无法启动
6
openclaw config set browser.noSandbox true
7
# 4. 使用 $(which google-chrome) 自动获取二进制文件的实际安装路径（通常是 /usr/bin/google-chrome），动态设置 Chrome 可执行文件路径
8
openclaw config set browser.executablePath "$(which google-chrome)"
9
# 5. 重启 openclaw 网关
10
openclaw gateway restart
11
# 6. 为 openclaw 打开浏览器
12
openclaw browser start

1
openclaw gateway restart
2
openclaw browser --browser-profile openclaw start
3
openclaw browser --browser-profile openclaw tabs
4
openclaw browser --browser-profile openclaw open https://example.com
5
openclaw browser --browser-profile openclaw snapshot

8.2 WSL 场景（Xvfb 虚拟显示）#

当你需要 headed 行为时，可用 Xvfb 包一层 Chromium：

1
sudo apt install -y chromium xvfb
2
mkdir -p ~/.local/bin
3

4
cat > ~/.local/bin/chromium-xvfb << 'EOF'
5
#!/usr/bin/env bash
6
if ! pgrep -f "Xvfb :99" >/dev/null 2>&1; then
7
  Xvfb :99 -screen 0 1920x1080x24 -ac +extension GLX +render -noreset &
8
  sleep 1
9
fi
10
export DISPLAY=:99
11
exec /usr/bin/chromium "$@"
12
EOF
13

14
chmod +x ~/.local/bin/chromium-xvfb
15

16
openclaw config set browser.defaultProfile "openclaw"
17
openclaw config set browser.headless false
18
openclaw config set browser.executablePath "$HOME/.local/bin/chromium-xvfb"
19
openclaw gateway restart
20
openclaw browser --browser-profile openclaw start

8.3 本地桌面 Chrome 扩展接管（可选）#

如果你想让 OpenClaw 接管已有 Chrome 标签页：

1
openclaw browser extension install
2
openclaw browser extension path

然后去 chrome://extensions：

1. 打开开发者模式
2. 加载 unpacked 扩展目录（上一步输出路径）
3. 使用 --browser-profile chrome 进行操作

9.1 Telegram 示例#

1
openclaw channels add --channel telegram --token <BOT_TOKEN>
2
openclaw channels status
3
openclaw channels list

9.2 QQ 机器人配置#

此处教程来源：猫猫摸大鱼 原文地址：https://iloli.love/archives/1772284805466

也可参考仓库README：sliverp/qqbot: qqbot

运行下面的命令，安装 QQ 通道插件

1
openclaw plugins install @sliverp/qqbot@latest

然后创建 QQ 机器人，访问 QQ 开放平台 https://q.qq.com/

2026.03.08 更新，QQ 官方推出了一键配置页面，可直接配置，下面的教程就不需要看了：https://q.qq.com/qqbot/openclaw/login.html

如果你尚未注册过，需要先注册账号（需要实名信息，扫脸，以及一个 QQ 号作为管理员 QQ 号），非常简单，这里就不赘述了。

登录你的 QQ 开放平台账号，进入后台后，点击机器人，点击创建机器人。

填写机器人名称，上传机器人头像，填写机器人描述，点击确认。

点击提交创建。

点击刚刚创建的机器人。

点击开发管理，复制 App ID，生成 App Secret。

扫码认证后，复制 App Secret，勾选，点击关闭。

点击沙箱配置，点击添加成员，把自己勾选上，点击确认。

点击这个二维码的图标，使用自己的 QQ 扫描弹出的二维码，在手机上添加使用。

在创建 QQ 机器人的这一段时间，QQ 渠道插件也应该安装好了。

接下来运行以下命令对接 QQ 渠道（将其中的 App ID 和 App Secret 更改为你刚刚创建的 App ID 和 App Secret ），如下图。

**然后，踩坑，我实在忍不住吐槽：我真的不理解为什么向导里选择自定义API接口，会给我默认配置仅仅 4096 的上下文窗口和最大Token，这是人能干出来的事😅？

所以接下来做两件重要的事：添加插件信任白名单，以及修改模型上下文窗口和最大Token。

打开 /root/.openclaw/openclaw.json 文件，进行修改。

找到 plugins ，添加以下代码，如图。

1
"allow": ["qqbot"],

然后找到 models ，修改 contextWindow 和 maxTokens。

我这里使用的 gemini-3-flash 理论上支持 100 万的上下文窗口和 6.4 万的最大输出，但是稳妥起见，我们在这里设置 128K 的上下文窗口和 8192 的最大输出。

都修改完了以后，不要忘记保存，然后运行以下命令，重启网关。

1
openclaw gateway restart

到此就已经搭建并初步配置完成了，现在去 QQ 对话，验证一下，可以看到已经成功了。

9.3 排查通道问题#

1
openclaw channels status
2
openclaw channels logs --channel all
3
openclaw status --deep

12.1 “没有权限执行此操作”#

1. 检查 tools.profile
2. 切到 coding 试一次
3. 重启 gateway
4. 再看 openclaw status --deep

1
openclaw config get tools.profile
2
openclaw config set tools.profile coding
3
openclaw gateway restart

12.2 Gateway 起不来 / 重启失败#

1
openclaw config validate
2
openclaw doctor --repair
3
openclaw gateway restart
4
openclaw gateway status

如仍失败，再做服务重装：

1
openclaw gateway install --force
2
openclaw gateway restart

12.3 浏览器起不来#

按顺序检查：

1. browser.executablePath 是否真实存在
2. 无头机是否 browser.headless true
3. root 环境是否需 browser.noSandbox true
4. 端口/多实例冲突（先 stop 再 start）

12.4 通道显示连接异常（尤其 Telegram）#

先跑一遍标准梯子：

1
openclaw status
2
openclaw gateway status
3
openclaw logs --follow
4
openclaw doctor
5
openclaw channels status --probe

如果是 Telegram，再补：

1
openclaw pairing list telegram
2
openclaw channels logs --channel all

优先确认：

• token 是否正确
• 网络是否可达（尤其 api.telegram.org）
• 是否卡在 pairing 未批准
• 登录是否过期（尤其网页版通道）

仍不行就走“删除后重配”最省时间：

1
openclaw channels remove --channel telegram --delete
2
openclaw channels add --channel telegram --token <BOT_TOKEN>

如果日志是典型网络栈问题（fetch failed / getUpdates failed），加：

1
openclaw config set channels.telegram.network.autoSelectFamily false
2
openclaw config set channels.telegram.network.dnsResultOrder ipv4first
3
openclaw gateway restart