OpenClaw（龙虾）WSL Ubuntu 环境安装配置完整指南

从零开始在 WSL Ubuntu 中安装 OpenClaw配置公司中转站解决各种问题最终成功运行。目录环境准备OpenClaw 安装配置文件详解常见问题与解决方案日常使用指南完整配置模板一、环境准备1.1 确认 WSL Ubuntu 环境# 查看 Ubuntu 版本 lsb_release -a # 查看当前用户 whoami # 查看 Node.js 版本需要 22 node -v1.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.13npm install -g openclaw2026.3.13⚠️版本说明2026.4.1有已知 BugURL 解析、会话问题2026.3.29不存在于 npm2026.3.13是当前稳定版本2.2 验证安装openclaw --version # 应显示 2026.3.13三、配置文件详解使用中专站的模型做的配置原理图3.1 配置文件位置~/.openclaw/openclaw.json3.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.2baseUrl公司中转站地址http://192.100.30.115:18080/v1apiKey公司分配的个人 Keysk-xxxxxapiAPI 类型openai-completionsauth.mode网关认证调试时用nonenone四、常见问题与解决方案4.1 问题openclaw: command not found原因npm 全局路径未加入 PATH解决# 查看 npm 全局路径 npm prefix -g # 添加到 PATH echo export PATH$(npm prefix -g)/bin:$PATH ~/.bashrc source ~/.bashrc4.2 问题ETARGET No matching version found原因指定的版本不存在于 npm解决# 查看可用版本 npm view openclaw versions --json | tail -20 # 安装存在的版本 npm install -g openclaw2026.3.134.3 问题网关启动失败 / systemd 不可用原因WSL 默认不支持 systemd解决# 方案1前台运行 openclaw gateway start --foreground # 方案2后台运行 nohup openclaw gateway start /tmp/openclaw.log 21 # 方案3启用 WSL systemd编辑 /etc/wsl.conf [boot] systemdtrue4.4 问题Model specified without provider原因配置中模型名没有带提供商前缀解决# 修改配置 sed -i s/model: deepseek-v3.2/model: siact-local\/deepseek-v3.2/ ~/.openclaw/openclaw.json4.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:你好}]}更新配置文件中的 Keysed -i s/旧Key/新Key/g ~/.openclaw/openclaw.json4.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 model4.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 openclaw2026.3.13 # 5. 恢复配置 mkdir -p ~/.openclaw cp ~/openclaw.json.backup ~/.openclaw/openclaw.json五、日常使用指南5.1 启动 OpenClaw# 启动网关 systemctl --user start openclaw-gateway.service # 进入 TUI openclaw tui5.2 TUI 常用命令命令功能/model查看/切换模型/provider查看/切换提供商/help查看帮助CtrlC退出 TUI5.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 -f5.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 openclaw2026.3.13查看版本openclaw --version运行诊断openclaw doctor启动网关systemctl --user start openclaw-gateway.service进入 TUIopenclaw tui查看日志journalctl --user -u openclaw-gateway.service -f停止网关systemctl --user stop openclaw-gateway.service完全卸载npm uninstall -g openclaw rm -rf ~/.openclaw