从零开始在 WSL Ubuntu 中安装 OpenClaw，配置公司中转站，解决各种问题，最终成功运行。
目录
环境准备
OpenClaw 安装
配置文件详解
常见问题与解决方案
日常使用指南
完整配置模板
一、环境准备
1.1 确认 WSL Ubuntu 环境
# 查看 Ubuntu 版本 lsb_release -a # 查看当前用户 whoami # 查看 Node.js 版本（需要 >= 22） node -v
1.2 如果 Node.js 版本过低
# 安装 Node.js 22 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # 验证 node -v # 应显示 v22.x.x
二、OpenClaw 安装
2.1 安装稳定版本（推荐 2026.3.13）
npm install -g openclaw@2026.3.13
⚠️版本说明：
2026.4.1有已知 Bug（URL 解析、会话问题）
2026.3.29不存在于 npm
2026.3.13是当前稳定版本
2.2 验证安装
openclaw --version # 应显示 2026.3.13
三、配置文件详解
使用中专站的模型做的配置，原理图：
3.1 配置文件位置
~/.openclaw/openclaw.json
3.2 完整配置模板
{ "agents": { "defaults": { "workspace": "/home/你的用户名/.openclaw/workspace", "model": "siact-local/deepseek-v3.2" } }, "gateway": { "mode": "local", "auth": { "mode": "none" }, "port": 18789, "bind": "loopback" }, "models": { "providers": { "siact-local": { "baseUrl": "http://公司中转站IP:端口/v1", "apiKey": "你的API Key", "api": "openai-completions", "models": [ { "id": "siact-local/deepseek-v3.2", "name": "deepseek-v3.2", "api": "openai-completions", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 128000 } ] } } } }3.3 配置要点
| 字段 | 说明 | 示例 |
|---|---|---|
model | 默认模型（必须带提供商前缀） | siact-local/deepseek-v3.2 |
baseUrl | 公司中转站地址 | http://192.100.30.115:18080/v1 |
apiKey | 公司分配的个人 Key | sk-xxxxx |
api | API 类型 | openai-completions |
auth.mode | 网关认证（调试时用none） | none |
四、常见问题与解决方案
4.1 问题：openclaw: command not found
原因：npm 全局路径未加入 PATH
解决：
# 查看 npm 全局路径 npm prefix -g # 添加到 PATH echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
4.2 问题：ETARGET No matching version found
原因：指定的版本不存在于 npm
解决：
# 查看可用版本 npm view openclaw versions --json | tail -20 # 安装存在的版本 npm install -g openclaw@2026.3.13
4.3 问题：网关启动失败 / systemd 不可用
原因：WSL 默认不支持 systemd
解决：
# 方案1：前台运行 openclaw gateway start --foreground # 方案2：后台运行 nohup openclaw gateway start > /tmp/openclaw.log 2>&1 & # 方案3：启用 WSL systemd（编辑 /etc/wsl.conf） [boot] systemd=true
4.4 问题：Model specified without provider
原因：配置中模型名没有带提供商前缀
解决：
# 修改配置 sed -i 's/"model": "deepseek-v3.2"/"model": "siact-local\/deepseek-v3.2"/' ~/.openclaw/openclaw.json
4.5 问题：401 无效的令牌
原因：API Key 错误或过期
解决：
确认 Key 完全正确（注意大小写、字母数字）
用 curl 测试 Key 是否有效：
curl -X POST "http://公司IP:端口/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的Key" \ -d '{"model":"deepseek-v3.2","messages":[{"role":"user","content":"你好"}]}'更新配置文件中的 Key：
sed -i 's/旧Key/新Key/g' ~/.openclaw/openclaw.json
4.6 问题：网关配置不生效
原因：systemd 服务未重新加载配置
解决：
# 完全停止 systemctl --user stop openclaw-gateway.service pkill -f openclaw-gateway # 重新启动 systemctl --user start openclaw-gateway.service # 查看日志确认 journalctl --user -u openclaw-gateway.service -n 30 --no-pager | grep -i model
4.7 问题：需要完全卸载重装
# 1. 备份配置 cp ~/.openclaw/openclaw.json ~/openclaw.json.backup # 2. 卸载 openclaw uninstall --all --yes npm uninstall -g openclaw # 3. 清理残留 rm -rf ~/.openclaw # 4. 重新安装 npm install -g openclaw@2026.3.13 # 5. 恢复配置 mkdir -p ~/.openclaw cp ~/openclaw.json.backup ~/.openclaw/openclaw.json
五、日常使用指南
5.1 启动 OpenClaw
# 启动网关 systemctl --user start openclaw-gateway.service # 进入 TUI openclaw tui
5.2 TUI 常用命令
| 命令 | 功能 |
|---|---|
/model | 查看/切换模型 |
/provider | 查看/切换提供商 |
/help | 查看帮助 |
Ctrl+C | 退出 TUI |
5.3 管理命令
# 查看网关状态 systemctl --user status openclaw-gateway.service # 停止网关 systemctl --user stop openclaw-gateway.service # 重启网关 systemctl --user restart openclaw-gateway.service # 查看日志 journalctl --user -u openclaw-gateway.service -n 50 --no-pager # 实时日志 journalctl --user -u openclaw-gateway.service -f
5.4 设置开机自启
systemctl --user enable openclaw-gateway.service
六、完整配置模板
6.1 单模型配置
{ "agents": { "defaults": { "workspace": "/home/edy/.openclaw/workspace", "model": "siact-local/deepseek-v3.2" } }, "gateway": { "mode": "local", "auth": { "mode": "none" }, "port": 18789, "bind": "loopback" }, "models": { "providers": { "siact-local": { "baseUrl": "http://192.100.30.115:18080/v1", "apiKey": "你的API Key", "api": "openai-completions", "models": [ { "id": "siact-local/deepseek-v3.2", "name": "deepseek-v3.2", "api": "openai-completions", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 128000 } ] } } } }6.2 多模型配置
在models数组中添加更多模型：
"models": [ { "id": "siact-local/deepseek-v3.2", "name": "deepseek-v3.2" }, { "id": "siact-local/kimi-k2.5", "name": "kimi-k2.5" }, { "id": "siact-local/qwen3-coder-plus", "name": "qwen3-coder-plus" } ]附录：命令速查表
| 操作 | 命令 |
|---|---|
| 安装稳定版 | npm install -g openclaw@2026.3.13 |
| 查看版本 | openclaw --version |
| 运行诊断 | openclaw doctor |
| 启动网关 | systemctl --user start openclaw-gateway.service |
| 进入 TUI | openclaw tui |
| 查看日志 | journalctl --user -u openclaw-gateway.service -f |
| 停止网关 | systemctl --user stop openclaw-gateway.service |
| 完全卸载 | npm uninstall -g openclaw && rm -rf ~/.openclaw |
