1. 为什么 OpenClaw 在 Linux 上装完却跑不起来OpenClaw 是一个可本地部署的 AI 助手框架支持接入 OpenAI、Claude 等模型也能对接本地推理服务适合想在自己服务器上跑一套对话与自动化能力的开发者。它本身不复杂真正让人卡住的往往不是 OpenClaw而是 Linux 环境Python 版本不对、Node 依赖拉不下来、systemd 服务路径写错、Nginx 反代 502。这篇就按“首次部署”的视角把 Ubuntu 22.04 / Debian 12 / CentOS Stream 9 三条线的安装流程走一遍每一步都给可复制命令和验证方式。我试过在一台 4GB 内存的轻量服务器上从零装 OpenClaw第一次启动失败的原因很典型虚拟环境没激活就跑了 uvicorn报ModuleNotFoundError。所以下面每个环节我都会带上“怎么确认这一步真的成功了”而不是装完就往下走。你如果是第一次在 Linux 上部署这类服务跟着做基本能一次跑通。需要提前说明的是OpenClaw 调用模型需要一个兼容 OpenAI 协议的 API 入口。本文用 TaoToken 作为模型接入层来演示配置它的 API 地址是https://taotoken.net/api兼容 OpenAI SDK 的调用方式这样你在.env里填 base_url 和 key 就能直接跑通对话验证。下面先把这个前置准备好再进入系统安装。2. 装 OpenClaw 前先把模型接入层配好OpenClaw 的模型调用走的是 OpenAI 兼容协议所以你需要一个 base_url 和一个 API Key。TaoToken 的控制台可以创建 key地址是https://taotoken.net/console创建完在 API Keys 页面复制即可。文档在https://taotoken.net/doc里面有各语言的调用示例配置 OpenClaw 时主要看 base_url 和鉴权头这两项。具体操作顺序是这样先注册登录进控制台创建 API Key然后确认你要用的模型名。OpenClaw 的.env里OPENAI_API_KEY填你创建的 keyOPENAI_BASE_URL填https://taotoken.net/api模型名按你实际开通的填。这样 OpenClaw 启动后调用模型时就会走这个入口而不是默认的官方地址。注意API Key 只显示一次创建后立刻复制保存。不要把它写进会提交到 Git 的文件里.env一定要加进.gitignore。如果你只是想先验证 key 能不能用可以先用模型对话页面发一条消息测试地址是https://taotoken.net/models。确认能正常返回内容后再往下装 OpenClaw这样能把“环境问题”和“鉴权问题”分开排查省很多时间。3. 系统依赖与 Python、Node 环境配置3.1 基础依赖安装Ubuntu / Debian 用 aptCentOS Stream 9 用 dnf。先装编译和网络工具后面装 Python 包和拉代码都要用# Ubuntu 22.04 / Debian 12 sudo apt update sudo apt upgrade -y sudo apt install -y vim git curl wget net-tools htop build-essential # CentOS Stream 9 sudo dnf update -y sudo dnf install -y vim git curl wget net-tools htop gcc gcc-c make装完验证一下 git 和 curl 是否可用git --version curl --version两条命令都能输出版本号说明基础环境没问题。如果git --version报 command not found说明上一步没装成功回去看 apt/dnf 的报错。3.2 Python 3.11 环境OpenClaw 建议 Python 3.11。Ubuntu 22.04 默认是 3.10需要额外装Debian 12 自带 3.11CentOS Stream 9 默认 3.9也要单独装。# Ubuntu 22.04 sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install -y python3.11 python3.11-venv python3.11-dev # Debian 12自带 3.11装 venv 即可 sudo apt install -y python3.11-venv python3.11-dev # CentOS Stream 9 sudo dnf install -y python3.11 python3.11-devel验证版本python3.11 --version # 预期输出Python 3.11.x然后创建项目目录和虚拟环境。虚拟环境这一步很关键后面所有 pip 安装都要在激活状态下执行sudo mkdir -p /opt/openclaw sudo chown -R $USER:$USER /opt/openclaw cd /opt/openclaw python3.11 -m venv venv source venv/bin/activate pip install --upgrade pip激活后命令行前面会出现(venv)前缀。如果没看到这个前缀说明没激活成功后面装依赖会装到系统 Python 里容易出权限和版本冲突。3.3 Node.js 22 环境OpenClaw 的前端构建需要 Node。用 NodeSource 仓库装 22.x# Ubuntu / Debian curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # CentOS Stream 9 curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - sudo dnf install -y nodejs验证node -v # 预期 v22.x.x npm -v # 预期 10.x.xnpm 建议配一下镜像源否则装前端依赖会很慢npm config set registry https://registry.npmmirror.com npm config get registry最后一条命令输出你设置的镜像地址说明配置生效。4. OpenClaw 源码安装与配置文件骨架4.1 拉取源码并安装依赖cd /opt/openclaw git clone https://github.com/open-claw/open-claw.git cd open-claw先装 Python 依赖注意此时虚拟环境必须是激活状态source /opt/openclaw/venv/bin/activate pip install -r requirements.txt装完验证关键依赖是否可导入python -c import fastapi, uvicorn, sqlalchemy; print(deps ok)输出deps ok就说明 Python 侧没问题。如果报ModuleNotFoundError八成是虚拟环境没激活重新source一次再装。再装前端依赖npm install npm run buildnpm run build会生成前端静态资源这一步耗时较长耐心等它跑完。如果中途报网络错误检查上一步的 npm 镜像源是否配好。4.2 配置文件骨架OpenClaw 用.env管理配置。在项目根目录创建nano /opt/openclaw/open-claw/.env填入以下内容重点是模型接入部分# 服务配置 PORT7860 HOST0.0.0.0 DEBUGfalse # 模型接入OpenAI 兼容协议 OPENAI_API_KEY你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODEL你开通的模型名 # 数据库 DATABASE_URLsqlite:////opt/openclaw/data/openclaw.db # 日志 LOG_LEVELINFO LOG_FILE/opt/openclaw/logs/openclaw.log # 安全 SECRET_KEY换成一串随机字符串创建数据目录并授权mkdir -p /opt/openclaw/data /opt/openclaw/logs chmod 755 /opt/openclaw/data /opt/openclaw/logs注意OPENAI_BASE_URL结尾不要带/v1OpenClaw 内部会自己拼接路径。填错会导致 404这是很常见的坑。把.env加入忽略列表避免密钥泄露echo .env /opt/openclaw/open-claw/.gitignore5. 启动验证与请求测试5.1 前台启动确认服务正常先用前台方式启动方便直接看日志source /opt/openclaw/venv/bin/activate cd /opt/openclaw/open-claw uvicorn app.main:app --host 0.0.0.0 --port 7860看到下面这几行就说明启动成功INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:78605.2 用 curl 验证接口另开一个终端先测健康检查curl http://localhost:7860/api/v1/health # 预期{status:healthy,version:1.0.0}再测一次模型对话确认接入层配置正确curl -X POST http://localhost:7860/api/v1/chat \ -H Content-Type: application/json \ -d {message:你好简单介绍一下你自己}如果返回了模型生成的文本说明 OpenClaw 到 TaoToken 的链路是通的。如果返回鉴权错误回去检查.env里的 key 和 base_url如果返回超时检查服务器出网是否正常。5.3 配置 systemd 常驻前台验证通过后用 systemd 托管实现开机自启。创建服务文件sudo nano /etc/systemd/system/openclaw.service内容如下[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple User你的用户名 WorkingDirectory/opt/openclaw/open-claw EnvironmentPATH/opt/openclaw/venv/bin:/usr/local/bin:/usr/bin:/bin ExecStart/opt/openclaw/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 7860 Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target加载并启动sudo systemctl daemon-reload sudo systemctl start openclaw sudo systemctl enable openclaw sudo systemctl status openclawstatus显示active (running)就成功了。看实时日志用sudo journalctl -u openclaw -f6. 本篇常见报错排查端口被占用报Address already in use。用sudo lsof -i :7860找到进程kill -9 PID结束或改.env里的PORT。systemd 启动失败先sudo journalctl -u openclaw -n 50看具体报错。常见原因是WorkingDirectory路径写错、User不存在、虚拟环境路径不对。改完服务文件记得daemon-reload。Nginx 反代 502说明 Nginx 连不上后端。先确认 OpenClaw 在跑systemctl status openclaw再确认proxy_pass指向127.0.0.1:7860最后看/var/log/nginx/error.log。pip 装依赖失败先pip install --upgrade pip再pip cache purge然后重试。如果是某个包编译失败检查build-essential是否装了。模型调用返回 401key 填错或没生效。确认.env里OPENAI_API_KEY是完整的改完.env后必须重启服务才会重新读取。模型调用返回 404base_url 多写了/v1。改成https://taotoken.net/api即可。权限错误报Permission denied。用sudo chown -R $USER:$USER /opt/openclaw修一下目录归属再重启服务。7. 后续接入与长期使用建议装完之后日常使用主要围绕两件事一是模型接入的稳定性二是服务本身的运维。模型侧如果只是偶尔对话验证用模型对话页面就够了如果要把 OpenClaw 接到编辑器或自动化流程里长期跑建议单独规划一个 Coding Plan把调用额度和 key 管理分开避免和测试用的 key 混在一起。接入文档里有完整的鉴权和请求示例配置新模型或换 key 时对照着改.env就行。API Keys 页面用来管理你创建的密钥建议按用途分多个 key出问题时能快速定位是哪个环节的配置出了偏差。最后提醒一句.env里的SECRET_KEY一定要换成随机字符串别用默认值服务器防火墙只放行 22、80、4437860 不要直接暴露到公网走 Nginx 反代更安全。装完这套之后下一篇可以接着做 Docker Compose 一键部署把数据库和缓存也容器化扩展起来会省事很多。
OpenClaw专栏第五篇：Linux系统保姆级安装教程（附完整截图）
1. 为什么 OpenClaw 在 Linux 上装完却跑不起来OpenClaw 是一个可本地部署的 AI 助手框架支持接入 OpenAI、Claude 等模型也能对接本地推理服务适合想在自己服务器上跑一套对话与自动化能力的开发者。它本身不复杂真正让人卡住的往往不是 OpenClaw而是 Linux 环境Python 版本不对、Node 依赖拉不下来、systemd 服务路径写错、Nginx 反代 502。这篇就按“首次部署”的视角把 Ubuntu 22.04 / Debian 12 / CentOS Stream 9 三条线的安装流程走一遍每一步都给可复制命令和验证方式。我试过在一台 4GB 内存的轻量服务器上从零装 OpenClaw第一次启动失败的原因很典型虚拟环境没激活就跑了 uvicorn报ModuleNotFoundError。所以下面每个环节我都会带上“怎么确认这一步真的成功了”而不是装完就往下走。你如果是第一次在 Linux 上部署这类服务跟着做基本能一次跑通。需要提前说明的是OpenClaw 调用模型需要一个兼容 OpenAI 协议的 API 入口。本文用 TaoToken 作为模型接入层来演示配置它的 API 地址是https://taotoken.net/api兼容 OpenAI SDK 的调用方式这样你在.env里填 base_url 和 key 就能直接跑通对话验证。下面先把这个前置准备好再进入系统安装。2. 装 OpenClaw 前先把模型接入层配好OpenClaw 的模型调用走的是 OpenAI 兼容协议所以你需要一个 base_url 和一个 API Key。TaoToken 的控制台可以创建 key地址是https://taotoken.net/console创建完在 API Keys 页面复制即可。文档在https://taotoken.net/doc里面有各语言的调用示例配置 OpenClaw 时主要看 base_url 和鉴权头这两项。具体操作顺序是这样先注册登录进控制台创建 API Key然后确认你要用的模型名。OpenClaw 的.env里OPENAI_API_KEY填你创建的 keyOPENAI_BASE_URL填https://taotoken.net/api模型名按你实际开通的填。这样 OpenClaw 启动后调用模型时就会走这个入口而不是默认的官方地址。注意API Key 只显示一次创建后立刻复制保存。不要把它写进会提交到 Git 的文件里.env一定要加进.gitignore。如果你只是想先验证 key 能不能用可以先用模型对话页面发一条消息测试地址是https://taotoken.net/models。确认能正常返回内容后再往下装 OpenClaw这样能把“环境问题”和“鉴权问题”分开排查省很多时间。3. 系统依赖与 Python、Node 环境配置3.1 基础依赖安装Ubuntu / Debian 用 aptCentOS Stream 9 用 dnf。先装编译和网络工具后面装 Python 包和拉代码都要用# Ubuntu 22.04 / Debian 12 sudo apt update sudo apt upgrade -y sudo apt install -y vim git curl wget net-tools htop build-essential # CentOS Stream 9 sudo dnf update -y sudo dnf install -y vim git curl wget net-tools htop gcc gcc-c make装完验证一下 git 和 curl 是否可用git --version curl --version两条命令都能输出版本号说明基础环境没问题。如果git --version报 command not found说明上一步没装成功回去看 apt/dnf 的报错。3.2 Python 3.11 环境OpenClaw 建议 Python 3.11。Ubuntu 22.04 默认是 3.10需要额外装Debian 12 自带 3.11CentOS Stream 9 默认 3.9也要单独装。# Ubuntu 22.04 sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install -y python3.11 python3.11-venv python3.11-dev # Debian 12自带 3.11装 venv 即可 sudo apt install -y python3.11-venv python3.11-dev # CentOS Stream 9 sudo dnf install -y python3.11 python3.11-devel验证版本python3.11 --version # 预期输出Python 3.11.x然后创建项目目录和虚拟环境。虚拟环境这一步很关键后面所有 pip 安装都要在激活状态下执行sudo mkdir -p /opt/openclaw sudo chown -R $USER:$USER /opt/openclaw cd /opt/openclaw python3.11 -m venv venv source venv/bin/activate pip install --upgrade pip激活后命令行前面会出现(venv)前缀。如果没看到这个前缀说明没激活成功后面装依赖会装到系统 Python 里容易出权限和版本冲突。3.3 Node.js 22 环境OpenClaw 的前端构建需要 Node。用 NodeSource 仓库装 22.x# Ubuntu / Debian curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # CentOS Stream 9 curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - sudo dnf install -y nodejs验证node -v # 预期 v22.x.x npm -v # 预期 10.x.xnpm 建议配一下镜像源否则装前端依赖会很慢npm config set registry https://registry.npmmirror.com npm config get registry最后一条命令输出你设置的镜像地址说明配置生效。4. OpenClaw 源码安装与配置文件骨架4.1 拉取源码并安装依赖cd /opt/openclaw git clone https://github.com/open-claw/open-claw.git cd open-claw先装 Python 依赖注意此时虚拟环境必须是激活状态source /opt/openclaw/venv/bin/activate pip install -r requirements.txt装完验证关键依赖是否可导入python -c import fastapi, uvicorn, sqlalchemy; print(deps ok)输出deps ok就说明 Python 侧没问题。如果报ModuleNotFoundError八成是虚拟环境没激活重新source一次再装。再装前端依赖npm install npm run buildnpm run build会生成前端静态资源这一步耗时较长耐心等它跑完。如果中途报网络错误检查上一步的 npm 镜像源是否配好。4.2 配置文件骨架OpenClaw 用.env管理配置。在项目根目录创建nano /opt/openclaw/open-claw/.env填入以下内容重点是模型接入部分# 服务配置 PORT7860 HOST0.0.0.0 DEBUGfalse # 模型接入OpenAI 兼容协议 OPENAI_API_KEY你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODEL你开通的模型名 # 数据库 DATABASE_URLsqlite:////opt/openclaw/data/openclaw.db # 日志 LOG_LEVELINFO LOG_FILE/opt/openclaw/logs/openclaw.log # 安全 SECRET_KEY换成一串随机字符串创建数据目录并授权mkdir -p /opt/openclaw/data /opt/openclaw/logs chmod 755 /opt/openclaw/data /opt/openclaw/logs注意OPENAI_BASE_URL结尾不要带/v1OpenClaw 内部会自己拼接路径。填错会导致 404这是很常见的坑。把.env加入忽略列表避免密钥泄露echo .env /opt/openclaw/open-claw/.gitignore5. 启动验证与请求测试5.1 前台启动确认服务正常先用前台方式启动方便直接看日志source /opt/openclaw/venv/bin/activate cd /opt/openclaw/open-claw uvicorn app.main:app --host 0.0.0.0 --port 7860看到下面这几行就说明启动成功INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:78605.2 用 curl 验证接口另开一个终端先测健康检查curl http://localhost:7860/api/v1/health # 预期{status:healthy,version:1.0.0}再测一次模型对话确认接入层配置正确curl -X POST http://localhost:7860/api/v1/chat \ -H Content-Type: application/json \ -d {message:你好简单介绍一下你自己}如果返回了模型生成的文本说明 OpenClaw 到 TaoToken 的链路是通的。如果返回鉴权错误回去检查.env里的 key 和 base_url如果返回超时检查服务器出网是否正常。5.3 配置 systemd 常驻前台验证通过后用 systemd 托管实现开机自启。创建服务文件sudo nano /etc/systemd/system/openclaw.service内容如下[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple User你的用户名 WorkingDirectory/opt/openclaw/open-claw EnvironmentPATH/opt/openclaw/venv/bin:/usr/local/bin:/usr/bin:/bin ExecStart/opt/openclaw/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 7860 Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target加载并启动sudo systemctl daemon-reload sudo systemctl start openclaw sudo systemctl enable openclaw sudo systemctl status openclawstatus显示active (running)就成功了。看实时日志用sudo journalctl -u openclaw -f6. 本篇常见报错排查端口被占用报Address already in use。用sudo lsof -i :7860找到进程kill -9 PID结束或改.env里的PORT。systemd 启动失败先sudo journalctl -u openclaw -n 50看具体报错。常见原因是WorkingDirectory路径写错、User不存在、虚拟环境路径不对。改完服务文件记得daemon-reload。Nginx 反代 502说明 Nginx 连不上后端。先确认 OpenClaw 在跑systemctl status openclaw再确认proxy_pass指向127.0.0.1:7860最后看/var/log/nginx/error.log。pip 装依赖失败先pip install --upgrade pip再pip cache purge然后重试。如果是某个包编译失败检查build-essential是否装了。模型调用返回 401key 填错或没生效。确认.env里OPENAI_API_KEY是完整的改完.env后必须重启服务才会重新读取。模型调用返回 404base_url 多写了/v1。改成https://taotoken.net/api即可。权限错误报Permission denied。用sudo chown -R $USER:$USER /opt/openclaw修一下目录归属再重启服务。7. 后续接入与长期使用建议装完之后日常使用主要围绕两件事一是模型接入的稳定性二是服务本身的运维。模型侧如果只是偶尔对话验证用模型对话页面就够了如果要把 OpenClaw 接到编辑器或自动化流程里长期跑建议单独规划一个 Coding Plan把调用额度和 key 管理分开避免和测试用的 key 混在一起。接入文档里有完整的鉴权和请求示例配置新模型或换 key 时对照着改.env就行。API Keys 页面用来管理你创建的密钥建议按用途分多个 key出问题时能快速定位是哪个环节的配置出了偏差。最后提醒一句.env里的SECRET_KEY一定要换成随机字符串别用默认值服务器防火墙只放行 22、80、4437860 不要直接暴露到公网走 Nginx 反代更安全。装完这套之后下一篇可以接着做 Docker Compose 一键部署把数据库和缓存也容器化扩展起来会省事很多。
