Loading...
Loading...
Compare original and translation side by side
undefinedundefined| 序号 | 准备什么 | 说明 | 必需？ |
|---|---|---|---|
| 1 | 一台 Linux 服务器 | 最低 1GB 内存 + 500MB 磁盘，支持 SSH 登录 | 必需 |
| 2 | SSH 免密登录 | 确保本机能 | 必需 |
| 3 | AI 模型 API Key | 智谱GLM / DeepSeek / OpenAI / Claude / Kimi / 通义 任选 | 必需 |
| 4 | 聊天频道 Bot Token | Telegram(@BotFather) 或 Discord 或 飞书，也可以暂不配 | 可选 |
| 5 | 代理地址 | 中国大陆服务器 + 海外频道(Telegram/Discord)时需要 | 视情况 |
| 6 | 浏览器控制 | 让 Bot 能操控浏览器搜索/截图/填表，需额外安装 Playwright | 可选 |
---| 序号 | 准备什么 | 说明 | 必需？ |
|---|---|---|---|
| 1 | 一台 Linux 服务器 | 最低 1GB 内存 + 500MB 磁盘，支持 SSH 登录 | 必需 |
| 2 | SSH 免密登录 | 确保本机能 | 必需 |
| 3 | AI 模型 API Key | 智谱GLM / DeepSeek / OpenAI / Claude / Kimi / 通义 任选 | 必需 |
| 4 | 聊天频道 Bot Token | Telegram(@BotFather) 或 Discord 或 飞书，也可以暂不配 | 可选 |
| 5 | 代理地址 | 中国大陆服务器 + 海外频道(Telegram/Discord)时需要 | 视情况 |
| 6 | 浏览器控制 | 让 Bot 能操控浏览器搜索/截图/填表，需额外安装 Playwright | 可选 |
---/newbotcurl -s --connect-timeout 3 https://api.telegram.org/newbotcurl -s --connect-timeout 3 https://api.telegram.orgssh <SSH_ARGS> "echo '=== CPU ===' && nproc && echo '=== 内存 ===' && free -h && echo '=== 磁盘 ===' && df -h / && echo '=== 系统 ===' && uname -a && echo '=== Node.js ===' && node -v 2>/dev/null || echo '未安装' && echo '=== npm ===' && npm -v 2>/dev/null || echo '未安装' && echo '=== 包管理器 ===' && which pacman apt yum dnf 2>/dev/null && echo '=== OpenClaw ===' && openclaw --version 2>/dev/null || echo '未安装'"ssh <SSH_ARGS> "echo '=== CPU ===' && nproc && echo '=== 内存 ===' && free -h && echo '=== 磁盘 ===' && df -h / && echo '=== 系统 ===' && uname -a && echo '=== Node.js ===' && node -v 2>/dev/null || echo '未安装' && echo '=== npm ===' && npm -v 2>/dev/null || echo '未安装' && echo '=== 包管理器 ===' && which pacman apt yum dnf 2>/dev/null && echo '=== OpenClaw ===' && openclaw --version 2>/dev/null || echo '未安装'"| 包管理器 | 命令 |
|---|---|
| pacman (Arch) | |
| apt (Debian/Ubuntu) | |
| dnf (RHEL/Fedora) | |
| yum (CentOS) | |
node -v && npm -v| 包管理器 | 命令 |
|---|---|
| pacman (Arch) | |
| apt (Debian/Ubuntu) | |
| dnf (RHEL/Fedora) | |
| yum (CentOS) | |
node -v && npm -vcurl -fsSL https://openclaw.ai/install.sh | bash重要：安装脚本会尝试启动交互式 onboarding wizard，在非 TTY 环境会报错误。这是正常的，OpenClaw 本体已安装成功。/dev/tty: No such device or address
openclaw --versioncurl -fsSL https://openclaw.ai/install.sh | bash重要：安装脚本会尝试启动交互式 onboarding wizard，在非 TTY 环境会报错误。这是正常的，OpenClaw 本体已安装成功。/dev/tty: No such device or address
openclaw --version~/.openclaw/openclaw.json~/.openclaw/openclaw.json{
"models": {
"mode": "merge",
"providers": {
"<PROVIDER_NAME>": {
"baseUrl": "<BASE_URL>",
"apiKey": "<API_KEY>",
"api": "openai-completions",
"models": [
{
"id": "<MODEL_ID>",
"name": "<DISPLAY_NAME>",
"reasoning": false,
"input": ["text"],
"contextWindow": 128000,
"maxTokens": 32000
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "<PROVIDER_NAME>/<MODEL_ID>"
},
"memorySearch": {
"enabled": false
}
}
},
"gateway": {
"mode": "local"
}
}{
"models": {
"mode": "merge",
"providers": {
"<PROVIDER_NAME>": {
"baseUrl": "<BASE_URL>",
"apiKey": "<API_KEY>",
"api": "openai-completions",
"models": [
{
"id": "<MODEL_ID>",
"name": "<DISPLAY_NAME>",
"reasoning": false,
"input": ["text"],
"contextWindow": 128000,
"maxTokens": 32000
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "<PROVIDER_NAME>/<MODEL_ID>"
},
"memorySearch": {
"enabled": false
}
}
},
"gateway": {
"mode": "local"
}
}| Provider 名 | MODEL_ID | baseUrl |
|---|---|---|
| zhipu | glm-5 | |
| openai | gpt-4o | |
| deepseek | deepseek-chat | |
| kimi | moonshot-v1-128k | |
| qwen | qwen-max | |
| anthropic | claude-sonnet-4-5-20250929 | |
注意：Anthropic 模型的字段应为api而非"anthropic-messages"。"openai-completions"
mkdir -p ~/.openclaw/agents/main/sessions ~/.openclaw/credentials
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json| Provider 名 | MODEL_ID | baseUrl |
|---|---|---|
| zhipu | glm-5 | |
| openai | gpt-4o | |
| deepseek | deepseek-chat | |
| kimi | moonshot-v1-128k | |
| qwen | qwen-max | |
| anthropic | claude-sonnet-4-5-20250929 | |
注意：Anthropic 模型的字段应为api而非"anthropic-messages"。"openai-completions"
mkdir -p ~/.openclaw/agents/main/sessions ~/.openclaw/credentials
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.jsonundefinedundefined
等待 3 秒后验证：
```bash
systemctl --user status openclaw-gateway.service | head -10Active: active (running)
等待 3 秒后验证：
```bash
systemctl --user status openclaw-gateway.service | head -10Active: active (running)undefinedundefined
---
---openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken '<BOT_TOKEN>'
openclaw config set channels.telegram.dmPolicy pairingopenclaw config set channels.discord.enabled true
openclaw config set channels.discord.botToken '<BOT_TOKEN>'
openclaw config set channels.discord.dmPolicy pairingopenclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.token '<BOT_TOKEN>'
openclaw config set channels.feishu.dmPolicy pairingopenclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken '<BOT_TOKEN>'
openclaw config set channels.telegram.dmPolicy pairingopenclaw config set channels.discord.enabled true
openclaw config set channels.discord.botToken '<BOT_TOKEN>'
openclaw config set channels.discord.dmPolicy pairingopenclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.token '<BOT_TOKEN>'
openclaw config set channels.feishu.dmPolicy pairing适用场景：服务器在中国大陆，且频道是 Telegram 或 Discord（需访问海外 API）。 飞书是国内服务，不需要代理。
undefined适用场景：服务器在中国大陆，且频道是 Telegram 或 Discord（需访问海外 API）。 飞书是国内服务，不需要代理。
undefined
如果超时/失败，说明需要代理。用用户提供的代理测试：
```bash
export http_proxy='<PROXY_URL>' && export https_proxy='<PROXY_URL>'
curl -s --connect-timeout 5 https://api.telegram.org/bot<BOT_TOKEN>/getMe重要：proxy.conf 必须一次性写完所有环境变量（代理 + no_proxy + DISPLAY）， 不要分多次追加，后续浏览器步骤也不需要再改这个文件。
mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d
cat > ~/.config/systemd/user/openclaw-gateway.service.d/proxy.conf << EOF
[Service]
Environment="http_proxy=<PROXY_URL>"
Environment="https_proxy=<PROXY_URL>"
Environment="no_proxy=127.0.0.1,localhost,::1"
Environment="NO_PROXY=127.0.0.1,localhost,::1"
Environment="DISPLAY=:99"
EOF为什么要：没有它，OpenClaw 连本地 Chrome CDP 端口也会走代理， 导致浏览器启动成功但 OpenClaw 检测不到，报no_proxy。 即使当前不配浏览器，也要加上Failed to start Chrome CDP，防止后续开启浏览器时踩坑。no_proxy
为什么要：浏览器需要显示服务器，即使 headless 模式也需要。 如果不配浏览器，这个变量无害。DISPLAY=:99
如果超时/失败，说明需要代理。用用户提供的代理测试：
```bash
export http_proxy='<PROXY_URL>' && export https_proxy='<PROXY_URL>'
curl -s --connect-timeout 5 https://api.telegram.org/bot<BOT_TOKEN>/getMe重要：proxy.conf 必须一次性写完所有环境变量（代理 + no_proxy + DISPLAY）， 不要分多次追加，后续浏览器步骤也不需要再改这个文件。
mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d
cat > ~/.config/systemd/user/openclaw-gateway.service.d/proxy.conf << EOF
[Service]
Environment="http_proxy=<PROXY_URL>"
Environment="https_proxy=<PROXY_URL>"
Environment="no_proxy=127.0.0.1,localhost,::1"
Environment="NO_PROXY=127.0.0.1,localhost,::1"
Environment="DISPLAY=:99"
EOF为什么要：没有它，OpenClaw 连本地 Chrome CDP 端口也会走代理， 导致浏览器启动成功但 OpenClaw 检测不到，报no_proxy。 即使当前不配浏览器，也要加上Failed to start Chrome CDP，防止后续开启浏览器时踩坑。no_proxy
为什么要：浏览器需要显示服务器，即使 headless 模式也需要。 如果不配浏览器，这个变量无害。DISPLAY=:99
关键坑点：会触发内部热重启，但热重启不会加载 systemd 的环境变量（代理）。 所有涉及频道/代理的配置改完后，必须用openclaw config set来重启。systemctl --user restart
export XDG_RUNTIME_DIR=/run/user/$(id -u)
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service关键坑点：会触发内部热重启，但热重启不会加载 systemd 的环境变量（代理）。 所有涉及频道/代理的配置改完后，必须用openclaw config set来重启。systemctl --user restart
export XDG_RUNTIME_DIR=/run/user/$(id -u)
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.serviceopenclaw channels statusenabled, configured, runningfetch failedNetwork request failedopenclaw channels statusenabled, configured, runningfetch failedNetwork request failed关键坑点：配对命令是， 不是openclaw pairing approve <channel> <CODE>（那个会报openclaw devices approve <CODE>）。unknown requestId
undefined关键坑点：配对命令是， 不是openclaw pairing approve <channel> <CODE>（那个会报openclaw devices approve <CODE>）。unknown requestId
undefined
配对码有效期约 1 小时。如果过期，让用户重新发消息即可生成新码。
---
配对码有效期约 1 小时。如果过期，让用户重新发消息即可生成新码。
---让 Bot 能操控浏览器，执行搜索、截图、填表等操作。 如果第一步用户选了「暂不配置」，跳过此步。
让 Bot 能操控浏览器，执行搜索、截图、填表等操作。 如果第一步用户选了「暂不配置」，跳过此步。
不要用系统自带的 Chromium。滚动发行版（Arch 等）会出现 ICU/libFLAC 等库版本不匹配， 稳定发行版也可能版本过旧。统一用 Playwright 自带的 Chromium，一条命令解决。
undefined不要用系统自带的 Chromium。滚动发行版（Arch 等）会出现 ICU/libFLAC 等库版本不匹配， 稳定发行版也可能版本过旧。统一用 Playwright 自带的 Chromium，一条命令解决。
undefined
验证 Playwright Chromium 可运行：
```bash
PLAYWRIGHT_CHROME=$(find ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome 2>/dev/null | head -1)
$PLAYWRIGHT_CHROME --version
验证 Playwright Chromium 可运行：
```bash
PLAYWRIGHT_CHROME=$(find ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome 2>/dev/null | head -1)
$PLAYWRIGHT_CHROME --version为什么需要 wrapper：
- OpenClaw 自动检测
来启动浏览器，wrapper 让它用 Playwright 版本/usr/bin/chromium- Chromium 不支持
URL 中嵌入的认证（http_proxy），会报user:pass@hostERR_INVALID_AUTH_CREDENTIALS- wrapper 自动 unset 代理环境变量，改用
指向本地无认证代理中继--proxy-server
undefined为什么需要 wrapper：
- OpenClaw 自动检测
来启动浏览器，wrapper 让它用 Playwright 版本/usr/bin/chromium- Chromium 不支持
URL 中嵌入的认证（http_proxy），会报user:pass@hostERR_INVALID_AUTH_CREDENTIALS- wrapper 自动 unset 代理环境变量，改用
指向本地无认证代理中继--proxy-server
undefined
> **架构说明**：
> ```
> Chrome --proxy-server=127.0.0.1:7891 → proxy-relay（无认证）→ 上游代理（带认证）→ 海外网站
> ```
**创建 wrapper**（根据是否需要代理，选择对应版本）：
```bash
> **架构说明**：
> ```
> Chrome --proxy-server=127.0.0.1:7891 → proxy-relay（无认证）→ 上游代理（带认证）→ 海外网站
> ```
**创建 wrapper**（根据是否需要代理，选择对应版本）：
```bash
> **注意**：写 wrapper 文件时避免通过 SSH 传递 `#!/bin/bash`，
> 某些 shell（zsh）会把 `!` 转义为 `\!`。建议用 `scp` 或在远程服务器上直接编辑。
> **注意**：写 wrapper 文件时避免通过 SSH 传递 `#!/bin/bash`，
> 某些 shell（zsh）会把 `!` 转义为 `\!`。建议用 `scp` 或在远程服务器上直接编辑。cat > ~/.config/systemd/user/xvfb.service << 'EOF'
[Unit]
Description=Xvfb Virtual Framebuffer
Before=openclaw-gateway.service
[Service]
ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x720x24 -nolisten tcp
Restart=always
RestartSec=3
[Install]
WantedBy=default.target
EOF
export XDG_RUNTIME_DIR=/run/user/$(id -u)
systemctl --user daemon-reload
systemctl --user enable --now xvfb.servicecat > ~/.config/systemd/user/xvfb.service << 'EOF'
[Unit]
Description=Xvfb Virtual Framebuffer
Before=openclaw-gateway.service
[Service]
ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x720x24 -nolisten tcp
Restart=always
RestartSec=3
[Install]
WantedBy=default.target
EOF
export XDG_RUNTIME_DIR=/run/user/$(id -u)
systemctl --user daemon-reload
systemctl --user enable --now xvfb.service三个配置缺一不可，否则 Chrome 无法在无头服务器上以 root 运行：
openclaw config set browser.enabled true
openclaw config set browser.headless true # 无头模式，不开会尝试打开 GUI
openclaw config set browser.noSandbox true # root 运行必须，否则 Chrome 静默崩溃openclaw browser create-profile --name headless --driver openclaw --color '#0066CC'
openclaw config set browser.defaultProfile headless不要用默认的 extension driver。extension driver 需要在 Chrome 里安装 OpenClaw 扩展， 无头服务器上不可能操作。使用 Playwright 直接驱动。--driver openclaw
三个配置缺一不可，否则 Chrome 无法在无头服务器上以 root 运行：
openclaw config set browser.enabled true
openclaw config set browser.headless true # 无头模式，不开会尝试打开 GUI
openclaw config set browser.noSandbox true # root 运行必须，否则 Chrome 静默崩溃openclaw browser create-profile --name headless --driver openclaw --color '#0066CC'
openclaw config set browser.defaultProfile headless不要用默认的 extension driver。extension driver 需要在 Chrome 里安装 OpenClaw 扩展， 无头服务器上不可能操作。使用 Playwright 直接驱动。--driver openclaw
如果第 7 步已经写了 proxy.conf（含和no_proxy），这里不需要再改。 如果第 7 步没配代理（不需要代理的场景），这里只需加DISPLAY=:99：DISPLAY
undefined如果第 7 步已经写了 proxy.conf（含和no_proxy），这里不需要再改。 如果第 7 步没配代理（不需要代理的场景），这里只需加DISPLAY=:99：DISPLAY
undefinedundefinedundefined重要：先运行清理可能的无效配置 key， 避免网关因配置校验失败反复崩溃重启。openclaw doctor --fix
undefined重要：先运行清理可能的无效配置 key， 避免网关因配置校验失败反复崩溃重启。openclaw doctor --fix
undefinedundefinedundefined适用场景：树莓派、ARM 开发板等低功耗设备。x86 服务器通常不需要。 核心问题：Chrome 使用（CPU 软件渲染），ARM CPU 处理复杂页面极慢。 内存不是瓶颈（8GB 足够），CPU 才是。swiftshader-webgl
timeoutMs: 2e4undefined适用场景：树莓派、ARM 开发板等低功耗设备。x86 服务器通常不需要。 核心问题：Chrome 使用（CPU 软件渲染），ARM CPU 处理复杂页面极慢。 内存不是瓶颈（8GB 足够），CPU 才是。swiftshader-webgl
timeoutMs: 2e4undefined
**问题 2：Playwright CDP 连接超时太短**
Playwright 连接 Chrome 有 3 次重试（5s/7s/9s），ARM 设备上不够。改为 15s/20s/25s：
```bash
**问题 2：Playwright CDP 连接超时太短**
Playwright 连接 Chrome 有 3 次重试（5s/7s/9s），ARM 设备上不够。改为 15s/20s/25s：
```bash
**问题 3：Chrome 重启后恢复旧标签**
Chrome 从 user-data 恢复上次会话的所有标签页，在低功耗设备上多标签会耗尽 CPU。
每次重启网关前需要清理：
```bash
**问题 3：Chrome 重启后恢复旧标签**
Chrome 从 user-data 恢复上次会话的所有标签页，在低功耗设备上多标签会耗尽 CPU。
每次重启网关前需要清理：
```bash
> **注意**：以上源码修改会在 OpenClaw 更新后被覆盖，需要重新执行。
**低功耗设备浏览器使用建议**：
- 避免重型 SPA（Google News、Twitter 等），超过 60 秒仍会超时
- 优先用轻量级/文本版网站（CNN Lite、RSS feeds、API 接口）
- 简单页面（example.com、百度）通常 3-5 秒内完成
- 首次浏览器操作较慢（Playwright 需建立 CDP 连接），后续操作快很多
> **注意**：以上源码修改会在 OpenClaw 更新后被覆盖，需要重新执行。
**低功耗设备浏览器使用建议**：
- 避免重型 SPA（Google News、Twitter 等），超过 60 秒仍会超时
- 优先用轻量级/文本版网站（CNN Lite、RSS feeds、API 接口）
- 简单页面（example.com、百度）通常 3-5 秒内完成
- 首次浏览器操作较慢（Playwright 需建立 CDP 连接），后续操作快很多适用场景：让 Bot 能以已登录身份浏览 X/Twitter（查看时间线、搜索等）。 需要先完成 8a-8f 的浏览器配置。
auth_token核心经验：不要尝试在服务器上自动化登录流程！ 直接注入 auth_token 是唯一可靠方案。 我们尝试过 7+ 种登录方案全部失败（见踩坑总结 22-30），原因包括：
- X 的登录页在 ARM + swiftshader 上无法渲染
- API 登录流程会触发 IP 限频（error 399）
- Python HTTP 客户端被 Cloudflare TLS 指纹识别拦截
- Chrome 跨域请求（CORS）限制无法绕过
- CDP Fetch 拦截开启后 fetch 调用全部报错
适用场景：让 Bot 能以已登录身份浏览 X/Twitter（查看时间线、搜索等）。 需要先完成 8a-8f 的浏览器配置。
auth_token核心经验：不要尝试在服务器上自动化登录流程！ 直接注入 auth_token 是唯一可靠方案。 我们尝试过 7+ 种登录方案全部失败（见踩坑总结 22-30），原因包括：
- X 的登录页在 ARM + swiftshader 上无法渲染
- API 登录流程会触发 IP 限频（error 399）
- Python HTTP 客户端被 Cloudflare TLS 指纹识别拦截
- Chrome 跨域请求（CORS）限制无法绕过
- CDP Fetch 拦截开启后 fetch 调用全部报错
https://x.comauth_token关键理解：之前"成功登录"实际上不是在服务器上完成登录，而是复用了一个已有的有效 auth_token。 本质是"贴了一张有效的门票"，不是"重新买票"。服务器上没有任何可靠方式完成 X 的登录流程。
https://x.comauth_token关键理解：之前"成功登录"实际上不是在服务器上完成登录，而是复用了一个已有的有效 auth_token。 本质是"贴了一张有效的门票"，不是"重新买票"。服务器上没有任何可靠方式完成 X 的登录流程。
undefinedundefinedundefinedundefined大坑：不带Network.setCookie参数时，cookie 只存在内存中， Chrome 重启后全部丢失，Twitter 检测到 session 断开会吊销 auth_token。 一旦 token 被吊销就永久失效，必须用户重新在电脑上登录获取新 token。expires
expiresct0twidNetwork.setCookieexpiresall_ck = c.cmd("Network.getAllCookies")
auth = [ck for ck in all_ck.get("cookies", []) if ck["name"] == "auth_token"]
print(f"auth_token exists: {len(auth) > 0}")大坑：不带Network.setCookie参数时，cookie 只存在内存中， Chrome 重启后全部丢失，Twitter 检测到 session 断开会吊销 auth_token。 一旦 token 被吊销就永久失效，必须用户重新在电脑上登录获取新 token。expires
expiresct0twidNetwork.setCookieexpiresall_ck = c.cmd("Network.getAllCookies")
auth = [ck for ck in all_ck.get("cookies", []) if ck["name"] == "auth_token"]
print(f"auth_token exists: {len(auth) > 0}")Home / XLoginct0twidx.com/homeundefinedHome / XLoginct0twidx.com/homeundefined
> **重要**：`ct0` cookie 是 httpOnly 的，**只能通过 CDP `Network.getAllCookies` 读取**，
> 不能用 `document.cookie` 读（会返回空）。这是一个常见误判——看到 `ct0: none` 就以为登录失败，
> 实际上页面标题 `Home / X` 已经证明登录成功了。
**安装 x-tweet-fetcher skill（可选）：**
让 Bot 能通过命令获取 X/Twitter 推文内容：
```bash
> **重要**：`ct0` cookie 是 httpOnly 的，**只能通过 CDP `Network.getAllCookies` 读取**，
> 不能用 `document.cookie` 读（会返回空）。这是一个常见误判——看到 `ct0: none` 就以为登录失败，
> 实际上页面标题 `Home / X` 已经证明登录成功了。
**安装 x-tweet-fetcher skill（可选）：**
让 Bot 能通过命令获取 X/Twitter 推文内容：
```bash
> **坑**：`fetch_tweet.py` 使用 `urllib.request.urlopen()`，这个函数**不会自动使用 `https_proxy` 环境变量**。
> 如果服务器需要代理才能访问外网，必须手动添加 ProxyHandler：
```python
> **坑**：`fetch_tweet.py` 使用 `urllib.request.urlopen()`，这个函数**不会自动使用 `https_proxy` 环境变量**。
> 如果服务器需要代理才能访问外网，必须手动添加 ProxyHandler：
```python
---
---undefinedundefined
全部通过后，输出总结表格：
| 项目 | 状态 |
|------|------|
| OpenClaw | 版本号 |
| 模型 | provider/model-id |
| 网关 | systemd active (running) |
| Linger | 已启用 |
| 频道 | 频道名 + running |
| Bot 链接 | t.me/xxx_bot |
| 代理 | 有/无 |
| 浏览器 | running / 未配置 |
---
全部通过后，输出总结表格：
| 项目 | 状态 |
|------|------|
| OpenClaw | 版本号 |
| 模型 | provider/model-id |
| 网关 | systemd active (running) |
| Linger | 已启用 |
| 频道 | 频道名 + running |
| Bot 链接 | t.me/xxx_bot |
| 代理 | 有/无 |
| 浏览器 | running / 未配置 |
---文件名：openclaw-credentials.txt
内容：服务器地址、Bot 名称、Bot Token、模型 provider文件名：openclaw-credentials.txt
内容：服务器地址、Bot 名称、Bot Token、模型 provider| 编号 | 坑 | 原因 | 正确做法 |
|---|---|---|---|
| 1 | 安装脚本报 | 非交互式 SSH 无 TTY | 忽略，OpenClaw 已装好，手动写配置 |
| 2 | | Telegram 不是通过 | 用 |
| 3 | Telegram API 连不上（ | 中国大陆无法直连 api.telegram.org | 必须配代理，写入 systemd 环境变量 |
| 4 | 代理配了但重启后还是 | | 必须用 |
| 5 | | 用错命令了 | 正确命令： |
| 6 | | 必须指定频道参数 | |
| 7 | 配置验证报错 | open 模式需要显式设置 allowFrom | 用 |
| 8 | gateway 需要 | 手动写配置时漏了 | 配置文件里加 |
| 9 | | 首次安装未创建必要目录 | |
| 10 | 退出 SSH 后网关停止 | systemd user session 无 linger | |
| 11 | 系统 Chromium 启动报库版本不匹配 | Arch 等滚动发行版 ICU/libFLAC 版本不兼容 | 用 Playwright 自带 Chromium，创建 wrapper 替换 |
| 12 | | 默认 profile 用 extension driver，需要 Chrome 扩展 | 创建 headless profile： |
| 13 | | | systemd 环境变量加 |
| 14 | 浏览器导航报 | Chromium 不支持 | wrapper 脚本中 |
| 15 | | 默认都是 false，root 无头运行必须开启 | |
| 16 | 浏览器操作超时 | OpenClaw 硬编码 20 秒超时，ARM 设备 CPU 软件渲染太慢 | 修改源码 |
| 17 | Playwright CDP 连接超时 | 首次连接重试 5s/7s/9s 不够，ARM 上 Chrome 初始化慢 | 修改源码 |
| 18 | 重启后浏览器操作卡死（14 个标签恢复） | Chrome 从 user-data 恢复旧会话标签，多标签耗尽 CPU | 重启前用 CDP API 关闭多余标签，或清理 user-data |
| 19 | Google News 等重型 SPA 始终超时 | ARM + swiftshader 软件渲染，复杂 JS/CSS 渲染超过 60 秒 | 用轻量级网站或 RSS/API 替代，无法通过增加超时解决 |
| 20 | Chrome 能访问国内站但无法访问海外站 | wrapper 中 unset 了代理变量，Chrome 无法直连海外 | 搭建本地代理中继 + |
| 21 | SSH 传输 wrapper 脚本 shebang 变成 | zsh 的历史扩展把 | 用 scp 传输文件，或在远程服务器上直接编辑 |
| 22 | X 登录页显示 "Something went wrong" | ARM + swiftshader 软件渲染无法运行 X 的 React SPA | 不要用浏览器自动化登录，直接注入 auth_token |
| 23 | Twitter API 登录返回 error 399 "Could not log you in now" | 多次失败尝试触发 IP 级别限频 | 不要反复重试登录 API，一旦被限频需等待数小时 |
| 24 | Python twikit/httpx 被 Cloudflare 403 拦截 | Python HTTP 客户端的 TLS 指纹与浏览器不同 | 只能通过真实浏览器（Chrome CDP）发起请求 |
| 25 | Chrome fetch + | x.com 向 api.twitter.com 带凭据的跨域请求触发 preflight 失败 | 用 CDP |
| 26 | | ct0 是 httpOnly cookie，JS 无权访问 | 用 CDP |
| 27 | | urllib 的 urlopen 默认不使用 | 显式创建 |
| 28 | env 文件 source 报 | 密码/token 中含 | env 文件中所有值用单引号包裹 |
| 29 | Chrome 重启后 X 登录丢失，auth_token 被吊销 | | 注入 cookie 时必须带 |
| 30 | 服务器上所有自动登录方案均失败（API/twikit/CDP Fetch/Chrome JS/CORS） | ARM 软件渲染 + Cloudflare TLS 指纹 + CORS 限制 = 无法在服务器完成登录 | 放弃在服务器登录，让用户在自己电脑浏览器获取 auth_token 后注入 |
| 编号 | 坑 | 原因 | 正确做法 |
|---|---|---|---|
| 1 | 安装脚本报 | 非交互式 SSH 无 TTY | 忽略，OpenClaw 已装好，手动写配置 |
| 2 | | Telegram 不是通过 | 用 |
| 3 | Telegram API 连不上（ | 中国大陆无法直连 api.telegram.org | 必须配代理，写入 systemd 环境变量 |
| 4 | 代理配了但重启后还是 | | 必须用 |
| 5 | | 用错命令了 | 正确命令： |
| 6 | | 必须指定频道参数 | |
| 7 | 配置验证报错 | open 模式需要显式设置 allowFrom | 用 |
| 8 | gateway 需要 | 手动写配置时漏了 | 配置文件里加 |
| 9 | | 首次安装未创建必要目录 | |
| 10 | 退出 SSH 后网关停止 | systemd user session 无 linger | |
| 11 | 系统 Chromium 启动报库版本不匹配 | Arch 等滚动发行版 ICU/libFLAC 版本不兼容 | 用 Playwright 自带 Chromium，创建 wrapper 替换 |
| 12 | | 默认 profile 用 extension driver，需要 Chrome 扩展 | 创建 headless profile： |
| 13 | | | systemd 环境变量加 |
| 14 | 浏览器导航报 | Chromium 不支持 | wrapper 脚本中 |
| 15 | | 默认都是 false，root 无头运行必须开启 | |
| 16 | 浏览器操作超时 | OpenClaw 硬编码 20 秒超时，ARM 设备 CPU 软件渲染太慢 | 修改源码 |
| 17 | Playwright CDP 连接超时 | 首次连接重试 5s/7s/9s 不够，ARM 上 Chrome 初始化慢 | 修改源码 |
| 18 | 重启后浏览器操作卡死（14 个标签恢复） | Chrome 从 user-data 恢复旧会话标签，多标签耗尽 CPU | 重启前用 CDP API 关闭多余标签，或清理 user-data |
| 19 | Google News 等重型 SPA 始终超时 | ARM + swiftshader 软件渲染，复杂 JS/CSS 渲染超过 60 秒 | 用轻量级网站或 RSS/API 替代，无法通过增加超时解决 |
| 20 | Chrome 能访问国内站但无法访问海外站 | wrapper 中 unset 了代理变量，Chrome 无法直连海外 | 搭建本地代理中继 + |
| 21 | SSH 传输 wrapper 脚本 shebang 变成 | zsh 的历史扩展把 | 用 scp 传输文件，或在远程服务器上直接编辑 |
| 22 | X 登录页显示 "Something went wrong" | ARM + swiftshader 软件渲染无法运行 X 的 React SPA | 不要用浏览器自动化登录，直接注入 auth_token |
| 23 | Twitter API 登录返回 error 399 "Could not log you in now" | 多次失败尝试触发 IP 级别限频 | 不要反复重试登录 API，一旦被限频需等待数小时 |
| 24 | Python twikit/httpx 被 Cloudflare 403 拦截 | Python HTTP 客户端的 TLS 指纹与浏览器不同 | 只能通过真实浏览器（Chrome CDP）发起请求 |
| 25 | Chrome fetch + | x.com 向 api.twitter.com 带凭据的跨域请求触发 preflight 失败 | 用 CDP |
| 26 | | ct0 是 httpOnly cookie，JS 无权访问 | 用 CDP |
| 27 | | urllib 的 urlopen 默认不使用 | 显式创建 |
| 28 | env 文件 source 报 | 密码/token 中含 | env 文件中所有值用单引号包裹 |
| 29 | Chrome 重启后 X 登录丢失，auth_token 被吊销 | | 注入 cookie 时必须带 |
| 30 | 服务器上所有自动登录方案均失败（API/twikit/CDP Fetch/Chrome JS/CORS） | ARM 软件渲染 + Cloudflare TLS 指纹 + CORS 限制 = 无法在服务器完成登录 | 放弃在服务器登录，让用户在自己电脑浏览器获取 auth_token 后注入 |