1. OpenClaw 安装前必须搞清楚的几件事OpenClaw 是一个基于 Python 的开源自动化工具能帮你把数据抓取、流程编排、API 测试这些重复劳动串成一条流水线。它适合谁适合需要在 Windows 10/11、macOS、Linux 三端快速部署自动化任务又不想被环境依赖折腾到崩溃的开发者。我试过在三台不同系统的机器上从零装一遍踩过的坑基本集中在 Python 版本、虚拟环境激活和系统级开发库缺失这三块。先说结论OpenClaw 本身安装不复杂复杂的是各平台的环境差异。Windows 的 PATH 和 PowerShell 执行策略、macOS 的 Homebrew 路径、Linux 的 apt 与 yum 包名差异每一个都可能让你卡在第一步。所以这篇教程不会只丢一句pip install openclaw就完事而是把三端的完整流程、一键脚本、以及装完之后怎么验证全部拆开讲。你需要提前确认的硬性条件操作系统 Windows 10 64 位或更高、macOS Catalina 10.15 以上、Linux 推荐 Ubuntu 20.04/22.04 或 CentOS 7/8内存至少 4GB跑复杂任务建议 8GB 以上磁盘预留 500MB 以上安装过程需要联网下载依赖。Linux 和 macOS 部分命令需要 sudo 权限Windows 建议用管理员身份打开 PowerShell。还有一个容易被忽略的点OpenClaw 依赖 Python 3.7 以上版本但很多系统预装的是 Python 2.7 或者版本过低的 Python 3。如果你直接pip install而不检查版本后面大概率会遇到语法不兼容或者依赖解析失败。所以第一步永远是确认 Python 版本而不是急着装包。另外虚拟环境不是可选项是强烈建议的必选项。原因很简单OpenClaw 会拉取一堆第三方库如果你把它装进系统全局环境哪天另一个项目需要不同版本的同一个库冲突就来了。虚拟环境能把 OpenClaw 的依赖隔离在一个独立目录里删掉整个文件夹就等于卸载干净不会污染系统。最后提醒一句网上有些一键脚本会让你直接curl | bash这种操作风险很高。本篇提供的脚本你可以先保存到本地打开看一遍每一行在做什么确认没问题再执行。安全习惯比省那几分钟重要得多。2. TaoToken 统一 Key 与 API 通道的前置配置OpenClaw 装好之后很多功能需要调用大模型能力比如任务编排时的自然语言解析、自动化流程中的内容生成。如果你每个模型都去单独申请 Key、单独配 Base URL管理起来会非常乱。TaoToken 的作用就是提供一个统一的 API 通道你只需要一个 Key就能在 OpenClaw 里切换不同的模型不用改代码。先解释一下 TaoToken 是什么它是一个大模型 API 聚合网关兼容 OpenAI 风格的接口协议。也就是说任何支持自定义 Base URL 和 API Key 的工具都能接进来。OpenClaw 的模型配置模块正好支持这种自定义接入方式。适合谁用适合需要在一个自动化流程里调用多个模型、又不想维护多套凭证的开发者。接入前你需要准备两样东西一个 TaoToken 的 API Key以及确认你要用的模型 ID。API Key 在控制台的 API Keys 页面创建模型 ID 可以在模型对话页面查看当前支持的列表。这两个信息后面配置 OpenClaw 时会用到。这里要强调一个概念Base URL 和 API Key 是配对使用的。Base URL 告诉 OpenClaw 请求发往哪里API Key 告诉网关你是谁、有没有权限。两者缺一不可而且 Key 不要硬编码在代码里建议放在环境变量或者独立的配置文件里。如果你还没创建 Key可以先去控制台生成一个。注意 Key 只在创建时完整显示一次关掉页面就看不到了所以创建后立刻复制保存到安全的地方。如果你用的是团队协作场景建议给每个成员单独创建 Key方便后续排查问题和回收权限。配置的核心逻辑是这样的OpenClaw 读取一个配置文件里面写明 provider 类型是 openai 兼容、base_url 指向 TaoToken 的 API 地址、api_key 填你的 Key、model 填模型 ID。这样 OpenClaw 发请求时就会走 TaoToken 的通道而不是直连某个模型厂商。对于长期跑编码任务或者 Agent 流程的场景可以考虑用 Coding Plan它在调用额度和并发上有更适合持续任务的配置。如果你只是偶尔验证一下模型能不能通用模型对话页面手动测一下就够了不用急着写配置。3. 三端可复制的安装命令与配置文件这一节是全文的核心我会把 Windows、macOS、Linux 三端的安装步骤和一键脚本都列出来并且给出 OpenClaw 接入 TaoToken 的完整配置片段。你直接复制对应系统的部分执行即可。3.1 Windows 10/11 安装与配置先装 Python。去 python.org 下载最新稳定版 3.x 的 64 位安装包运行安装程序时务必勾选 “Add Python 3.x to PATH”这一步漏了后面所有命令都会报 “python 不是内部或外部命令”。装完关闭并重新打开 PowerShell用管理员身份运行验证python --version pip --version看到版本号输出就说明 PATH 配好了。接下来创建项目目录和虚拟环境mkdir C:\OpenClawProjects cd C:\OpenClawProjects python -m venv openclaw-env .\openclaw-env\Scripts\Activate.ps1如果激活时报 “无法加载文件因为在此系统上禁止运行脚本”执行下面这行临时放开当前用户的策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned激活成功后提示符前面会出现(openclaw-env)。然后安装 OpenClawpip install --upgrade pip pip install openclawWindows 一键脚本保存为install_openclaw_win.ps1以管理员身份运行# install_openclaw_win.ps1 if (-not (Get-Command python -ErrorAction SilentlyContinue)) { Write-Host 未检测到 Python请先安装 Python 3.10 并勾选 Add to PATH -ForegroundColor Red exit 1 } $projectDir C:\OpenClawProjects if (-not (Test-Path $projectDir)) { New-Item -Path $projectDir -ItemType Directory | Out-Null } Set-Location $projectDir if (-not (Test-Path openclaw-env)) { python -m venv openclaw-env } .\openclaw-env\Scripts\Activate.ps1 pip install --upgrade pip pip install openclaw openclaw --version Write-Host 安装完成虚拟环境已激活 -ForegroundColor Green3.2 macOS 安装与配置macOS 先装 Homebrew再装 Python 3/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) brew install python python3 --version pip3 --version创建项目目录和虚拟环境mkdir -p ~/OpenClawProjects cd ~/OpenClawProjects python3 -m venv openclaw-env source openclaw-env/bin/activate pip install --upgrade pip pip install openclawmacOS 一键脚本保存为install_openclaw_mac.sh#!/bin/bash if ! command -v brew /dev/null; then /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) fi if ! command -v python3 /dev/null; then brew install python fi project_dir$HOME/OpenClawProjects mkdir -p $project_dir cd $project_dir || exit 1 if [ ! -d openclaw-env ]; then python3 -m venv openclaw-env; fi source openclaw-env/bin/activate pip install --upgrade pip pip install openclaw openclaw --version echo 安装完成虚拟环境已激活赋予执行权限后运行chmod x install_openclaw_mac.sh ./install_openclaw_mac.sh3.3 LinuxUbuntu/CentOS安装与配置Ubuntu/Debian 先更新并安装依赖sudo apt update sudo apt upgrade -y sudo apt install python3 python3-venv python3-pip build-essential libssl-dev libffi-dev -yCentOS 7/8 的包名不同sudo yum install epel-release -y sudo yum install python3 python3-pip python3-devel gcc openssl-devel libffi-devel -y创建虚拟环境并安装mkdir -p ~/OpenClawProjects cd ~/OpenClawProjects python3 -m venv openclaw-env source openclaw-env/bin/activate pip install --upgrade pip pip install openclawLinux 一键脚本保存为install_openclaw_linux.sh#!/bin/bash sudo apt update sudo apt install python3 python3-venv python3-pip build-essential libssl-dev libffi-dev -y project_dir$HOME/OpenClawProjects mkdir -p $project_dir cd $project_dir || exit 1 if [ ! -d openclaw-env ]; then python3 -m venv openclaw-env; fi source openclaw-env/bin/activate pip install --upgrade pip pip install openclaw openclaw --version echo 安装完成虚拟环境已激活3.4 OpenClaw 接入 TaoToken 的配置文件OpenClaw 的模型配置支持 OpenAI 兼容协议在项目根目录创建config.yaml写入以下内容。注意 Base URL 用https://taotoken.net/api不要加多余路径model: provider: openai base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} model_id: claude-sonnet-4-20250514 timeout: 60 max_retries: 3如果你更习惯用 JSON 格式等价配置如下{ model: { provider: openai, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model_id: claude-sonnet-4-20250514, timeout: 60, max_retries: 3 } }API Key 不要直接写死在文件里用环境变量注入。Linux/macOS 在~/.zshrc或~/.bashrc里加export TAOTOKEN_API_KEY你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key如果你用的是 Claude Code 这类工具配置方式类似核心三件套永远是 Base URL、API Key、Model ID。Cline 的 MCP 配置也是同样的逻辑把这三个值填进对应的字段即可。Codex 的auth.json里同样需要这三项格式按官方文档来。4. 验证安装与请求是否成功装完不验证等于没装。这一节给你三端通用的验证动作以及怎么确认 TaoToken 通道真的通了。第一步确认 OpenClaw 命令可用。在激活的虚拟环境里执行openclaw --version如果输出版本号说明安装成功。如果报 “command not found”先确认虚拟环境是否激活提示符前有没有(openclaw-env)再用pip show openclaw看安装路径。第二步验证 Python 能正常导入 OpenClaw 模块python -c import openclaw; print(openclaw.__version__)第三步验证 TaoToken 通道。写一个最小请求脚本test_taotoken.pyimport os from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 回复两个字通了}], ) print(resp.choices[0].message.content)运行python test_taotoken.py如果输出 “通了”说明 Base URL、Key、Model ID 三件套全部正确。如果报 401说明 Key 有问题如果报 model not found说明 Model ID 写错了如果报连接超时检查网络和 Base URL 是否有多余斜杠。第四步跑一个 OpenClaw 的示例任务。具体命令取决于你安装的版本常见的是openclaw run example_task.yaml观察输出是否符合预期。如果 OpenClaw 有日志目录去日志里看有没有报错堆栈。验证通过后建议把pip freeze requirements.txt执行一遍把当前依赖版本冻结下来。这样以后换机器或者重装直接pip install -r requirements.txt就能复现一模一样的环境不用再一个个排查版本。5. 常见报错排查清单这一节按真实报错信息来对照你遇到哪个就查哪个。报错一401 Unauthorized或invalid api key这是最常见的。原因通常是 Key 复制不完整、Key 已过期、或者环境变量没生效。排查步骤先echo $TAOTOKEN_API_KEYWindows 用echo $env:TAOTOKEN_API_KEY确认变量有值再检查 Key 前后有没有多余空格最后去控制台确认这个 Key 还在有效期内。如果都没问题重新创建一个 Key 再试。报错二local proxy failed或连接被拒绝这个报错说明请求根本没发出去卡在本地网络层。检查 Base URL 是不是写成了https://taotoken.net/api/带了尾部斜杠有些客户端会把斜杠拼成双斜杠导致路径错误。另外确认你的网络环境能正常访问外网 API公司内网可能需要配置出口规则。报错三reading choices或choices is null这个报错说明请求发出去了、也返回了但返回体里没有choices字段。常见原因是 Model ID 写错了网关找不到对应模型返回了一个错误结构。去模型对话页面确认当前可用的模型 ID复制准确的字符串填进配置。另一个可能是请求参数不合法比如max_tokens设成了负数。报错四OAuth相关错误或token expired如果你用的是需要 OAuth 的工具链报这个说明授权令牌过期了。重新走一遍授权流程或者换成 API Key 方式接入。TaoToken 的 API Key 方式不涉及 OAuth配置更简单推荐优先用这种方式。报错五ModuleNotFoundError: No module named openclaw说明 OpenClaw 没装进当前环境。先确认虚拟环境激活了没有再pip list | grep openclaw看有没有。如果没有重新pip install openclaw。如果装了但还是报错可能是装到了系统 Python 而不是虚拟环境用which python和which pip确认路径。报错六Permission denied或sudo: command not foundLinux/macOS 上权限问题。检查脚本有没有执行权限chmod x检查当前用户有没有 sudo 权限。Windows 上则是没以管理员身份运行 PowerShell关掉重新用管理员打开。报错七SSL certificate verify failed系统缺少根证书或者证书过期。Ubuntu 上sudo apt install ca-certificatesmacOS 上brew install ca-certificatesWindows 上更新系统根证书。如果公司网络有自签证书拦截需要把公司证书加到信任链里。报错八pip install卡在 building wheel说明某个依赖需要编译但系统缺少编译工具。Ubuntu 装build-essentialCentOS 装gcc和python3-develmacOS 装 Xcode Command Line Toolsxcode-select --installWindows 装 Visual C Build Tools。排查通用原则先看报错最后一行那通常是最具体的错误再看它上面几行的堆栈找到是哪个文件哪一行触发的最后对照本文的配置片段确认 Base URL、Key、Model ID 三个值没有写错。6. 装完之后怎么用起来安装只是起点真正省时间的是把 OpenClaw 接进你的日常工作流。我的建议是先从一个小任务开始比如每天定时抓一个页面的数据、或者把一段文本自动过一遍模型做摘要。跑通一个最小闭环之后再往上加复杂度。如果你要长期跑编码类任务或者 Agent 流程Coding Plan 在调用稳定性和额度上更适合持续使用。如果只是偶尔验证模型输出用模型对话页面手动测就行。接入文档里有各语言和各工具的完整配置示例遇到不确定的字段去那里对照。最后留一个实用习惯每次改完配置先跑一遍第 4 节的最小验证脚本确认通道通了再跑正式任务。这样能把配置问题和业务问题分开排查起来快很多。