OpenClaw 安装与配置 —— 安装方式、配置文件结构、Provider 设置

简介

在上一篇中，我们全面了解了 OpenClaw 的定位、核心特性以及与 Hermes Agent 的关系。我们知道了 OpenClaw 是一个轻量级、低资源消耗的 AI 编程 Agent，适合快速原型、脚本编写和资源受限环境。

但理论知识只是第一步。要真正使用 OpenClaw，你需要完成安装和配置——这也是很多新手最容易卡住的地方。

OpenClaw 以"配置简单"著称，但"简单"不代表"不需要学习"。一个配置错误的 Provider 会导致每次请求都失败，一个不当的内存设置会让你的 VPS 变得卡顿，一个遗漏的 API Key 会让整个工具变成摆设。

本文将带你从零开始，完整走一遍 OpenClaw 的安装、配置和诊断流程。无论你是想在本地开发机上使用、在 VPS 上部署、还是在 Docker 容器中运行，都能在这里找到对应的方案。

正确花 15 分钟完成初始配置，将为后续的高效使用打下坚实基础。

一、安装方式对比与选型
二、方式一：pip 安装（推荐）
三、方式二：二进制直装
四、方式三：Docker 安装
五、验证安装
六、配置文件结构详解
七、Provider 设置
八、环境变量 vs 配置文件
九、openclaw doctor 诊断工具
十、常见问题排查
总结与下篇预告

一、安装方式对比与选型

OpenClaw 提供了三种安装方式，覆盖从「最便捷」到「最隔离」的全部场景：

安装方式	适用平台	自动更新	依赖要求	推荐场景
pip	全平台	`pip install -U openclaw`	Python 3.9+	首选推荐，覆盖 90% 场景
二进制直装	Linux / macOS	手动下载	无	无 Python 环境、CI/CD
Docker	全平台	`docker pull`	Docker	隔离环境、团队部署

前置要求

无论选择哪种安装方式，请确保：

操作系统：macOS 11+、Ubuntu 20.04+、Debian 11+、Windows 10/11（WSL2 推荐）
Python（pip 安装需要）：Python 3.9 或更高版本
网络：能够访问所选 Provider 的 API 端点
磁盘空间：至少 100MB 可用空间（实际占用约 50MB）
内存：建议至少 256MB（OpenClaw 自身仅需 ~128MB）

二、方式一：pip 安装（推荐）

这是最通用、最推荐的安装方式。

2.1 检查 Python 版本

bash

python3 --version
# 期望输出: Python 3.9.x 或更高

如果版本过低，请先升级：

bash

# Ubuntu / Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv

# macOS (使用 Homebrew)
brew install python

# 或使用 pyenv 管理多版本
curl https://pyenv.run | bash
pyenv install 3.12.0
pyenv global 3.12.0

2.2 安装 OpenClaw

bash

# 推荐：使用虚拟环境安装（避免污染系统 Python）
python3 -m venv ~/.openclaw-venv
source ~/.openclaw-venv/bin/activate

# 安装 OpenClaw
pip install openclaw

text

# 安装输出示例
Collecting openclaw
  Downloading openclaw-2.1.0-py3-none-any.whl (2.3 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.3/2.3 MB 3.2 MB/s
Collecting pyyaml>=6.0
  Downloading PyYAML-6.0.2-cp312-cp312-manylinux_2_17_x86_64.whl
Collecting httpx>=0.27.0
  Downloading httpx-0.27.2-py3-none-any.whl
Installing collected packages: pyyaml, httpx, openclaw
Successfully installed openclaw-2.1.0 pyyaml-6.0.2 httpx-0.27.2

2.3 全局安装（可选）

如果你不想使用虚拟环境，也可以全局安装：

bash

# 全局安装（需要管理员权限）
pip install --user openclaw

# 确保 ~/.local/bin 在 PATH 中
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

三、方式二：二进制直装

适合不想安装 Python 或需要在 CI/CD 中使用的环境。

3.1 Linux 安装

bash

# 下载最新版本
curl -fsSL https://github.com/nousresearch/openclaw/releases/latest/download/openclaw-linux-amd64 \
  -o /usr/local/bin/openclaw

# 添加执行权限
chmod +x /usr/local/bin/openclaw

# 验证
openclaw --version
# openclaw version 2.1.0

3.2 macOS 安装

bash

# 下载最新版本
curl -fsSL https://github.com/nousresearch/openclaw/releases/latest/download/openclaw-darwin-arm64 \
  -o /usr/local/bin/openclaw

# 添加执行权限
chmod +x /usr/local/bin/openclaw

# macOS 可能需要解除隔离
xattr -d com.apple.quarantine /usr/local/bin/openclaw

# 验证
openclaw --version

3.3 Windows 安装

powershell

# PowerShell 下载
Invoke-WebRequest -Uri "https://github.com/nousresearch/openclaw/releases/latest/download/openclaw-windows-amd64.exe" `
  -OutFile "$env:USERPROFILE\bin\openclaw.exe"

# 添加到 PATH
$env:PATH += ";$env:USERPROFILE\bin"

# 验证
openclaw --version

3.4 二进制安装的优势与局限

优势	局限
无需 Python 环境	需要手动更新
单个文件，部署简单	不同平台需下载不同二进制
启动速度更快	不支持 Python 插件
适合 CI/CD 环境	无法自定义编译选项

四、方式三：Docker 安装

适合需要环境隔离或团队统一部署的场景。

4.1 拉取镜像

bash

docker pull nousresearch/openclaw:latest

4.2 基本使用

bash

# 单次任务模式
docker run --rm \
  -v "$PWD:/workspace" \
  -e OPENCLAW_API_KEY="your-api-key" \
  nousresearch/openclaw:latest \
  "分析当前目录下的 Python 代码质量"

4.3 Docker Compose 配置

yaml

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: nousresearch/openclaw:latest
    volumes:
      - ./workspace:/workspace
      - ./config:/root/.config/openclaw
    environment:
      - OPENCLAW_API_KEY=${OPENCLAW_API_KEY}
      - OPENCLAW_PROVIDER=${OPENCLAW_PROVIDER:-openai}
      - OPENCLAW_MODEL=${OPENCLAW_MODEL:-gpt-4o-mini}
    working_dir: /workspace
    stdin_open: true
    tty: true

bash

# 使用 Docker Compose 运行
OPENCLAW_API_KEY="sk-xxx" OPENCLAW_PROVIDER="openai" \
  docker compose run openclaw "生成一个 Python 快排实现"

4.4 Docker 模式的最佳实践

dockerfile

# 自定义 Dockerfile
FROM nousresearch/openclaw:latest

# 安装额外工具（如 linter、formatter）
RUN apt-get update && apt-get install -y \
    python3-pip \
    flake8 \
    black \
    && rm -rf /var/lib/apt/lists/*

# 复制自定义配置
COPY config.yaml /root/.config/openclaw/config.yaml

# 设置工作目录
WORKDIR /workspace

五、验证安装

无论使用哪种安装方式，安装完成后都应进行验证：

bash

# 1. 检查版本
openclaw --version
# 期望输出: openclaw version 2.1.0

# 2. 检查帮助
openclaw --help

# 3. 检查配置路径
openclaw config path
# 期望输出: /home/user/.config/openclaw/config.yaml

# 4. 运行诊断（首次会提示配置）
openclaw doctor

六、配置文件结构详解

OpenClaw 使用 YAML 格式的配置文件，默认路径为 ~/.config/openclaw/config.yaml。

6.1 完整配置模板

yaml

# ~/.config/openclaw/config.yaml

# ============ Provider 配置 ============
provider:
  # Provider 类型: openai, anthropic, google, ollama, custom
  type: openai

  # 模型名称
  model: gpt-4o-mini

  # API Key（也可通过环境变量设置）
  api_key: sk-your-api-key-here

  # API Base URL（自定义端点时使用）
  base_url: https://api.openai.com/v1

  # 超时设置（秒）
  timeout: 60

  # 重试配置
  retry:
    max_attempts: 3
    backoff_factor: 1.5

# ============ 编辑器配置 ============
editor:
  # 编辑策略: block（块级）, precise（精确行级，如果后端支持）
  strategy: block

  # 块大小（上下文窗口中的 token 限制）
  block_size: 2048

  # 自动格式化（写入文件前）
  auto_format: true

# ============ Shell 配置 ============
shell:
  # Shell 执行模式: restricted（受限）, full（完全）
  mode: restricted

  # 允许的命令白名单
  allowed_commands:
    - ls
    - cat
    - grep
    - find
    - python3
    - pip
    - git

  # 禁止的命令黑名单
  blocked_commands:
    - rm -rf /
    - sudo
    - mkfs

  # 命令超时（秒）
  timeout: 30

# ============ 插件配置 ============
plugins:
  # Python Linter
  - name: python-linter
    enabled: true
    config:
      linter: flake8
      ignore: ["E501", "W503"]
      max_line_length: 100

  # 代码格式化
  - name: formatter
    enabled: true
    config:
      tool: black
      line_length: 88

  # 类型检查
  - name: type-checker
    enabled: false
    config:
      tool: mypy
      strict: false

# ============ 输出配置 ============
output:
  # 输出格式: text, json, markdown
  format: text

  # 是否显示思考过程
  show_thinking: false

  # 是否显示工具调用
  show_tool_calls: false

  # 最大输出长度（字符）
  max_length: 10000

# ============ 日志配置 ============
logging:
  # 日志级别: debug, info, warning, error
  level: warning

  # 日志文件路径
  file: ~/.config/openclaw/openclaw.log

  # 是否输出到控制台
  console: true

# ============ 高级配置 ============
advanced:
  # 并发请求数
  max_concurrency: 2

  # 本地缓存（用于代码索引）
  cache:
    enabled: true
    dir: ~/.cache/openclaw
    max_size: 500  # MB

  # 实验性功能
  experimental:
    multi_file_edit: false
    semantic_search: false

6.2 配置文件路径优先级

OpenClaw 按以下优先级查找配置文件：

text

1. 命令行指定: openclaw --config /path/to/config.yaml
2. 环境变量: OPENCLAW_CONFIG=/path/to/config.yaml
3. 项目级: ./openclaw.yaml（当前目录）
4. 用户级: ~/.config/openclaw/config.yaml
5. 默认配置（内置默认值）

bash

# 查看当前生效的配置文件
openclaw config path

# 查看当前配置（合并后）
openclaw config show

七、Provider 设置

Provider 是 OpenClaw 连接 AI 模型的桥梁。正确配置 Provider 是 OpenClaw 能正常工作的前提。

7.1 支持的 Provider 类型

text

┌───────────────────────────────────────────────────────────┐
│                    支持的 Provider                          │
├─────────────┬───────────────────┬─────────────────────────┤
│ Provider    │ 推荐模型          │ 备注                    │
├─────────────┼───────────────────┼─────────────────────────┤
│ openai      │ gpt-4o-mini       │ 性价比最高              │
│ anthropic   │ claude-3-haiku    │ 代码理解强              │
│ google      │ gemini-1.5-flash  │ 免费额度大              │
│ ollama      │ codellama:7b      │ 完全本地运行            │
│ custom      │ 自定义            │ 兼容 OpenAI 接口的服务   │
└─────────────┴───────────────────┴─────────────────────────┘

7.2 OpenAI Provider 配置

yaml

# 方式一：配置文件中设置
provider:
  type: openai
  model: gpt-4o-mini
  api_key: sk-your-openai-key-here
  base_url: https://api.openai.com/v1

# 方式二：环境变量设置
export OPENAI_API_KEY="sk-your-openai-key-here"
export OPENCLAW_PROVIDER="openai"
export OPENCLAW_MODEL="gpt-4o-mini"

7.3 Anthropic Provider 配置

yaml

provider:
  type: anthropic
  model: claude-3-haiku-20240307
  api_key: your-anthropic-api-key-here
  base_url: https://api.anthropic.com

  # Anthropic 特有的参数
  max_tokens: 4096

bash

# 环境变量方式
export ANTHROPIC_API_KEY="your-anthropic-api-key-here"
export OPENCLAW_PROVIDER="anthropic"
export OPENCLAW_MODEL="claude-3-haiku-20240307"

7.4 Google Provider 配置

yaml

provider:
  type: google
  model: gemini-1.5-flash
  api_key: your-google-api-key-here
  base_url: https://generativelanguage.googleapis.com/v1beta

bash

# 环境变量方式
export GOOGLE_API_KEY="your-google-api-key-here"
export OPENCLAW_PROVIDER="google"
export OPENCLAW_MODEL="gemini-1.5-flash"

7.5 Ollama Provider 配置（完全本地）

yaml

provider:
  type: ollama
  model: codellama:7b
  base_url: http://localhost:11434

  # Ollama 特有参数
  num_ctx: 4096
  temperature: 0.1

bash

# 需要先启动 Ollama 服务
ollama serve &
ollama pull codellama:7b

# 环境变量方式
export OPENCLAW_PROVIDER="ollama"
export OPENCLAW_MODEL="codellama:7b"
export OPENCLAW_BASE_URL="http://localhost:11434"

7.6 自定义 Provider（兼容 OpenAI 接口）

很多国内大模型服务商提供兼容 OpenAI 接口的 API，可以使用 custom 类型：

yaml

provider:
  type: custom
  model: your-model-name
  api_key: your-custom-api-key
  base_url: https://your-custom-endpoint.com/v1

  # 自定义请求头
  headers:
    X-Custom-Header: custom-value

7.7 Provider 快速切换

bash

# 通过环境变量快速切换
export OPENCLAW_PROVIDER="openai"
export OPENCLAW_MODEL="gpt-4o-mini"
openclaw "写一个快速排序"

export OPENCLAW_PROVIDER="ollama"
export OPENCLAW_MODEL="codellama:7b"
openclaw "同样的，再写一个归并排序"

# 通过命令行参数覆盖
openclaw --provider anthropic --model claude-3-haiku "分析这段代码"

八、环境变量 vs 配置文件

OpenClaw 支持两种配置方式，各有适用场景：

8.1 对比表

特性	配置文件 (config.yaml)	环境变量
适用场景	持久化配置	临时覆盖、CI/CD
安全性	文件权限控制	进程级隔离
优先级	低	高
版本控制	❌ 不建议提交 API Key	❌ 不建议写入脚本
多环境支持	需要多个文件	通过 .env 文件切换

8.2 推荐实践

bash

# 推荐：使用 .env 文件管理环境变量
# .env 文件（不要提交到版本控制）
OPENCLAW_PROVIDER=openai
OPENCLAW_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-your-key-here

# 加载环境变量
set -a
source .env
set +a

# 然后运行 openclaw
openclaw "检查项目中的 TODO 注释"

yaml

# 配置文件只放非敏感设置
# ~/.config/openclaw/config.yaml
provider:
  type: ${OPENCLAW_PROVIDER}
  model: ${OPENCLAW_MODEL}
  # api_key 不写在这里，通过环境变量提供

editor:
  strategy: block
  auto_format: true

shell:
  mode: restricted

九、openclaw doctor 诊断工具

openclaw doctor 是内置的诊断工具，可以自动检查配置和连接问题。

9.1 基本用法

bash

openclaw doctor

9.2 诊断输出示例

text

╔══════════════════════════════════════════════╗
║          OpenClaw 健康诊断报告                ║
╠══════════════════════════════════════════════╣
║                                              ║
║  [✓] OpenClaw 版本: 2.1.0                    ║
║  [✓] Python 版本: 3.12.3                     ║
║  [✓] 配置文件: ~/.config/openclaw/config.yaml ║
║  [✓] Provider: openai                        ║
║  [✓] 模型: gpt-4o-mini                       ║
║  [✓] API Key: 已配置                         ║
║  [✓] 网络连接: 正常                          ║
║  [✓] API 连接: 正常 (延迟 230ms)             ║
║  [✓] 模型可用性: gpt-4o-mini ✓              ║
║  [!] 日志文件: 不存在（首次运行后自动创建）   ║
║  [✓] 缓存目录: 正常 (12MB / 500MB)           ║
║                                              ║
║  状态: ✅ 一切正常                            ║
╚══════════════════════════════════════════════╝

9.3 常见问题诊断

bash

# 详细诊断模式
openclaw doctor --verbose

# 只检查特定项目
openclaw doctor --path /path/to/project

# 输出 JSON 格式（适合自动化检查）
openclaw doctor --format json

十、常见问题排查

10.1 API Key 无效

bash

# 症状: 401 Unauthorized 错误

# 排查步骤:
# 1. 确认 API Key 是否正确
echo $OPENAI_API_KEY | cut -c1-10

# 2. 检查配置文件中的 Key 是否被环境变量覆盖
openclaw config show | grep api_key

# 3. 测试 API 连接
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

10.2 网络连接超时

bash

# 症状: Connection timeout / Request timed out

# 排查步骤:
# 1. 检查网络连通性
ping api.openai.com

# 2. 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 3. 增加超时时间
# 在 config.yaml 中:
# provider:
#   timeout: 120

10.3 模型不支持

bash

# 症状: Model not found / Invalid model

# 排查步骤:
# 1. 确认模型名称拼写正确
openclaw config show | grep model

# 2. 查看支持的模型列表
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models | grep -o '"id":"[^"]*"'

# 3. 更换为已知可用的模型
export OPENCLAW_MODEL="gpt-4o-mini"

10.4 Python 版本不兼容

bash

# 症状: ImportError / SyntaxError

# 排查步骤:
python3 --version  # 需要 3.9+

# 升级 Python
# Ubuntu
sudo apt install python3.12 python3.12-venv

# 重新安装
pip uninstall openclaw
pip install openclaw

总结

本篇我们完成了 OpenClaw 从安装到配置的全流程：

✅ 三种安装方式：pip（推荐）、二进制直装、Docker
✅ 配置文件结构：完整的 config.yaml 模板，覆盖所有配置项
✅ Provider 设置：OpenAI、Anthropic、Google、Ollama、自定义
✅ 环境变量与配置文件：优先级、适用场景、推荐实践
✅ 诊断工具：openclaw doctor 的使用和常见问题排查

关键要点：

pip 安装是最推荐的方式，覆盖 90% 的使用场景
API Key 建议通过环境变量管理，不要写在配置文件中
openclaw doctor 是排查问题的第一工具
对于 CI/CD 场景，Docker 安装是最佳选择

下篇预告

在下一篇 《基础使用》 中，我们将进入 OpenClaw 的实战环节：

🎯 单任务模式：openclaw "指令" 的基本用法
💬 交互模式：连续对话与多轮任务
⚡ 命令执行：Shell 集成与自动化
📋 输出管理：格式控制、文件输出、管道集成
🔄 会话控制：上下文管理与历史记录

无论你是想快速生成一段代码，还是想搭建完整的自动化工作流，下一篇都将为你提供实用的实战指南。