03-OpenClaw 环境搭建与配置完全指南

OpenClaw 环境搭建与配置完全指南

在前两篇博客中，我们介绍了 OpenClaw 的核心理念和基础概念。现在，让我们进入实践环节——本文将详细讲解如何搭建和配置 OpenClaw 运行环境。无论你是在本地开发、服务器部署，还是使用容器化方案，这篇指南都将帮助你快速完成环境准备。

1. 安装指南：多种部署方式

OpenClaw 提供了多种灵活的安装方式，适应不同用户的使用场景。根据你的需求选择最适合的方案。

1.1 Docker 安装（推荐）

Docker 是 OpenClaw 推荐的部署方式，具有环境隔离、易于管理和版本控制的优势。

前置要求

Docker 20.10 或更高版本
Docker Compose 2.0 或更高版本（可选，用于编排）

安装步骤

方式一：使用官方 Docker 镜像

# 拉取最新镜像docker pull openclaw/openclaw:latest# 创建本地配置目录mkdir -p ~/.openclaw# 运行容器docker run -d \  --name openclaw \  -p 19001:19001 \  -v ~/.openclaw:/root/.openclaw \  -v /var/run/docker.sock:/var/run/docker.sock \  openclaw/openclaw:latest

方式二：使用 Docker Compose

创建 docker-compose.yml 文件：

version: '3.8'services:  openclaw:    image: openclaw/openclaw:latest    container_name: openclaw    restart: unless-stopped    ports:      - "19001:19001"    volumes:      - ~/.openclaw:/root/.openclaw      - /var/run/docker.sock:/var/run/docker.sock      - ./workspace:/root/.openclaw/workspace    environment:      - OPENCLAW_LOG_LEVEL=info      - OPENCLAW_GATEWAY_PORT=19001    networks:      - openclaw-netnetworks:  openclaw-net:    driver: bridge

启动服务：

docker-compose up -d

Docker 安装的优势

特性	说明
环境隔离	不影响宿主机系统环境
快速部署	一条命令即可完成部署
版本管理	可自由切换不同版本
跨平台	支持 Linux、macOS、Windows

1.2 npm/pnpm 安装

如果你希望在本地直接运行 OpenClaw CLI，可以使用 npm 或 pnpm 安装。

前置要求

Node.js 18.x 或更高版本
npm 9.x 或 pnpm 8.x

使用 npm 安装

# 全局安装npm install -g openclaw# 验证安装openclaw --version

使用 pnpm 安装（推荐）

pnpm 具有更快的安装速度和更优的磁盘空间利用：

# 全局安装pnpm install -g openclaw# 或者使用 pnpm 执行无需安装pnpm dlx openclaw@latest --help

配置环境变量

将 OpenClaw 的二进制目录添加到 PATH：

# 添加到 ~/.bashrc 或 ~/.zshrcexport PATH="$HOME/.local/share/pnpm:$PATH"# 立即生效source ~/.bashrc

1.3 源码编译安装

如果你需要深度定制或参与 OpenClaw 开发，可以从源码编译安装。

前置要求

Git
Node.js 18.x+
pnpm 8.x+
Rust 工具链（用于编译原生模块，可选）

编译步骤

# 1. 克隆仓库git clone https://github.com/openclaw/openclaw.gitcd openclaw# 2. 安装依赖pnpm install# 3. 编译项目pnpm build# 4. 链接到全局（开发模式）pnpm link --global# 5. 验证openclaw --version

开发模式运行

# 启动开发服务器pnpm dev# 运行测试pnpm test# 构建发行版pnpm package

1.4 平台支持说明

OpenClaw 支持多种操作系统和架构：

平台	x64	ARM64	备注
Linux	✅	✅	Ubuntu 20.04+, Debian 11+, CentOS 8+
macOS	✅	✅	macOS 12+ (Intel & Apple Silicon)
Windows	✅	✅	Windows 10/11
Docker	✅	✅	所有支持 Docker 的平台

最低系统要求：

内存：2GB RAM（推荐 4GB+）
磁盘：500MB 可用空间
网络：能够访问模型 API 端点

2. 配置文件详解：profiles.yaml

OpenClaw 使用 profiles.yaml（或 openclaw.json）作为核心配置文件，管理所有运行时参数。

2.1 配置文件位置

# 查看当前配置文件路径openclaw config file# 默认位置~/.openclaw/openclaw.json

2.2 完整配置示例

以下是一个完整的生产环境配置示例：

# profiles.yaml 完整配置示例meta:  lastTouchedVersion: "2026.3.11"  lastTouchedAt: "2026-03-21T16:08:53.003Z"# 向导配置wizard:  lastRunAt: "2026-03-21T16:04:42.707Z"  lastRunVersion: "2026.3.11"  lastRunCommand: "onboard"  lastRunMode: "local"# 智能体默认配置agents:  defaults:    workspace: "/root/.openclaw/workspace"    compaction:      mode: "safeguard"  # 上下文压缩模式    model:      primary: "tencentcodingplan/tc-code-latest"    reasoning: true      # 启用推理能力# 工具配置tools:  profile: "full"        # 工具集配置：minimal/standard/full  deny:                  # 禁用特定工具    - "browser"    - "web_search"    - "web_fetch"# 命令执行配置commands:  native: "auto"         # 原生命令执行模式  nativeSkills: "auto"  restart: true  ownerDisplay: "raw"# 会话配置session:  dmScope: "per-channel-peer"# Gateway 服务配置gateway:  port: 19001  mode: "local"          # local/server  bind: "loopback"       # loopback/lan/tailnet/auto/custom  # 控制面板配置  controlUi:    allowedOrigins:      - "http://localhost:19001"      - "http://127.0.0.1:19001"    allowInsecureAuth: false    dangerouslyDisableDeviceAuth: false    basePath: "/v9lwve"  # 认证配置  auth:    mode: "token"        # none/token/password/trusted-proxy    token: "your-secure-token-here"  # Tailscale 集成  tailscale:    mode: "off"          # off/serve/funnel    resetOnExit: false# 技能配置skills:  install:    nodeManager: "npm"   # npm/pnpm/yarn    registry: ""         # 自定义 npm 镜像# 插件配置plugins:  entries:    feishu:      enabled: true    wecom:      enabled: true    discord:      enabled: false    telegram:      enabled: false# 模型提供商配置models:  mode: "merge"          # merge/override  providers:    # OpenAI 配置    openai:      baseUrl: "https://api.openai.com/v1"      apiKey: "sk-..."      api: "openai-completions"      models:        - id: "gpt-4-turbo"          name: "GPT-4 Turbo"        - id: "gpt-4o"          name: "GPT-4o"        - id: "gpt-3.5-turbo"          name: "GPT-3.5 Turbo"    # Anthropic Claude 配置    anthropic:      baseUrl: "https://api.anthropic.com/v1"      apiKey: "sk-ant-..."      api: "anthropic-messages"      models:        - id: "claude-3-opus-20240229"          name: "Claude 3 Opus"        - id: "claude-3-sonnet-20240229"          name: "Claude 3 Sonnet"        - id: "claude-3-haiku-20240307"          name: "Claude 3 Haiku"    # 本地 Ollama 配置    ollama:      baseUrl: "http://localhost:11434"      api: "ollama-chat"      models:        - id: "llama3.2:latest"          name: "Llama 3.2"        - id: "codellama:latest"          name: "Code Llama"    # 腾讯云配置    tencentcodingplan:      baseUrl: "https://api.lkeap.cloud.tencent.com/coding/v3"      apiKey: "sk-..."      api: "openai-completions"      models:        - id: "tc-code-latest"          name: "腾讯代码助手"        - id: "hunyuan-2.0-thinking"          name: "混元 2.0 思考"  # 模型回退配置  fallbacks:    - "gpt-4-turbo"    - "claude-3-sonnet-20240229"    - "tc-code-latest"# 通道配置channels:  feishu:    enabled: true    appId: "cli_xxxxxxxxxx"    appSecret: "xxxxxxxxxx"    domain: "feishu"    groupPolicy: "open"  discord:    enabled: false    token: ""    applicationId: ""    publicKey: ""  telegram:    enabled: false    token: ""# 日志配置logging:  level: "info"          # silent/fatal/error/warn/info/debug/trace  file: true  console: true  maxSize: "100mb"  maxFiles: 7

2.3 配置项详解

模型配置（models）

模型配置是 OpenClaw 的核心，支持多提供商、多模型的灵活切换：

models:  mode: "merge"  # merge 模式会合并默认配置，override 会完全覆盖  providers:    provider-name:      baseUrl: "API 基础地址"      apiKey: "API 密钥"      api: "API 类型标识"      models:        - id: "模型 ID"          name: "显示名称"

支持的 API 类型：

openai-completions
: OpenAI 兼容 API
anthropic-messages
: Anthropic Messages API
ollama-chat
: Ollama 本地模型
openrouter
: OpenRouter 统一接口

安全设置（security）

gateway:  auth:    mode: "token"  # 认证模式选择    # none: 无认证（仅本地开发）    # token: Token 认证（推荐）    # password: 密码认证    # trusted-proxy: 信任代理模式

通道配置（channels）

通道配置决定 OpenClaw 可以接入哪些消息平台：

channels:  platform-name:    enabled: true/false    # 平台特定的配置项

3. 多平台集成配置

OpenClaw 支持接入多种消息平台，下面详细介绍各平台的配置方法。

3.1 Discord 配置

创建 Discord Bot

访问 Discord Developer Portal
点击 “New Application” 创建应用
在 Bot 选项卡中点击 “Add Bot”
复制 Bot Token（妥善保存）
在 OAuth2 → URL Generator 中勾选 bot 和 applications.commands 权限

配置 OpenClaw

# 添加 Discord 通道openclaw channels add \  --channel discord \  --token "YOUR_BOT_TOKEN" \  --application-id "YOUR_APP_ID" \  --public-key "YOUR_PUBLIC_KEY"# 或者通过配置文件

channels:  discord:    enabled: true    token: "MTAxMjM0NTY3ODkw.t0k3n.v4lu3"    applicationId: "1012345678901234567"    publicKey: "your-public-key-here"

邀请 Bot 到服务器

使用 OAuth2 URL Generator 生成邀请链接，选择以下权限：

Send Messages
Read Message History
Use Slash Commands
Add Reactions

3.2 Telegram 配置

创建 Telegram Bot

在 Telegram 中找到 @BotFather
发送 /newbot 命令
按提示设置 Bot 名称和用户名
保存返回的 Bot Token

配置 OpenClaw

openclaw channels add \  --channel telegram \  --token "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"

channels:  telegram:    enabled: true    token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"

获取 Chat ID

给 Bot 发送任意消息
访问 https://api.telegram.org/bot<YourBOTToken>/getUpdates
在返回的 JSON 中找到 chat.id

3.3 Slack 配置

创建 Slack App

访问 Slack API
点击 “Create New App” → “From scratch”
选择工作空间
在 OAuth & Permissions 中添加以下 Scope：

chat:write
chat:write.public
im:history
channels:history
app_mentions:read

安装并获取 Token

点击 “Install to Workspace”
复制 “Bot User OAuth Token”

配置 OpenClaw

channels:  slack:    enabled: true    token: "xoxb-your-bot-token"    signingSecret: "your-signing-secret"

3.4 飞书（Feishu）配置

创建飞书应用

访问飞书开放平台
点击 “创建企业自建应用”
进入 “凭证与基础信息” 获取 App ID 和 App Secret
在 “权限管理” 中添加以下权限：

im:chat:readonly
im:message:send
im:message.group_msg

配置事件订阅

开启 “机器人” 功能
设置事件订阅 URL（如使用 OpenClaw Gateway）
订阅消息事件

配置 OpenClaw

openclaw channels add \  --channel feishu \  --app-id "cli_xxxxxxxxxxxx" \  --app-secret "xxxxxxxxxxxxxxxx"

channels:  feishu:    enabled: true    appId: "cli_a93556b6bab85bce"    appSecret: "your-app-secret"    domain: "feishu"  # 或 "lark" 国际版    groupPolicy: "open"  # open/invite-only

3.5 企业微信配置

配置步骤

在企业微信管理后台创建应用
获取企业 ID、应用 ID 和 Secret
配置接收消息的服务器 URL

OpenClaw 配置

channels:  wecom:    enabled: true    corpId: "wwxxxxxxxxxxxxxxxx"    agentId: "1000002"    secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"    token: "your-token"    encodingAesKey: "your-aes-key"

3.6 Webhook 自定义配置

OpenClaw 支持通过 Webhook 接收自定义事件：

webhooks:  custom-endpoint:    enabled: true    path: "/webhooks/custom"    secret: "your-webhook-secret"    events:      - "message.received"      - "agent.completed"

# 查看 Webhook 配置openclaw webhooks list# 测试 Webhookcurl -X POST http://localhost:19001/webhooks/custom \  -H "Content-Type: application/json" \  -H "X-Webhook-Secret: your-webhook-secret" \  -d '{"event": "test", "data": {}}'

4. Gateway 服务管理

Gateway 是 OpenClaw 的核心服务，负责处理所有请求和消息路由。

4.1 服务启动/停止/重启

前台运行（开发调试）

# 启动 Gateway（前台）openclaw gateway run# 指定端口openclaw gateway run --port 18080# 开发模式（隔离配置）openclaw --dev gateway run# 强制启动（杀掉占用端口的进程）openclaw gateway run --force

后台服务管理

# 安装为系统服务openclaw gateway install# 启动服务openclaw gateway start# 停止服务openclaw gateway stop# 重启服务openclaw gateway restart# 查看服务状态openclaw gateway status# 卸载服务openclaw gateway uninstall

支持的系统服务

系统	服务管理器
Linux	systemd
macOS	launchd
Windows	schtasks

4.2 状态查看

# 基础状态openclaw gateway status# 详细探针信息openclaw gateway probe# 健康检查openclaw gateway healthopenclaw health# 使用成本统计openclaw gateway usage-cost

状态输出示例：

Gateway Status==============Service: runningPID: 12345Uptime: 2h 34mPort: 19001Bind: 127.0.0.1Health Check============API: OKChannels: 3 connectedMemory: 128MB / 512MB

4.3 日志管理

# 实时查看日志openclaw logs# 查看最近 100 行openclaw logs --lines 100# 指定日志级别openclaw logs --level debug# 查看通道日志openclaw channels logs# 导出日志openclaw logs > openclaw.log

日志文件位置：

~/.openclaw/logs/├── gateway.log      # 主日志├── channels.log     # 通道日志└── agent.log        # 智能体日志

5. 模型配置与切换

OpenClaw 支持灵活的多模型配置和智能切换策略。

5.1 OpenAI 模型配置

models:  providers:    openai:      baseUrl: "https://api.openai.com/v1"      apiKey: "sk-..."      api: "openai-completions"      models:        - id: "gpt-4-turbo-preview"          name: "GPT-4 Turbo"        - id: "gpt-4o"          name: "GPT-4o"          # 模型特定配置          maxTokens: 4096          temperature: 0.7        - id: "gpt-3.5-turbo"          name: "GPT-3.5 Turbo"

5.2 Claude 模型配置

models:  providers:    anthropic:      baseUrl: "https://api.anthropic.com/v1"      apiKey: "sk-ant-..."      api: "anthropic-messages"      models:        - id: "claude-3-opus-20240229"          name: "Claude 3 Opus"        - id: "claude-3-sonnet-20240229"          name: "Claude 3 Sonnet"        - id: "claude-3-haiku-20240307"          name: "Claude 3 Haiku"

5.3 本地模型（Llama 等）

使用 Ollama 运行本地模型：

# 安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh# 拉取模型ollama pull llama3.2ollama pull codellamaollama pull qwen2.5# 启动 Ollama 服务ollama serve

models:  providers:    ollama:      baseUrl: "http://localhost:11434"      api: "ollama-chat"      models:        - id: "llama3.2:latest"          name: "Llama 3.2"        - id: "codellama:latest"          name: "Code Llama"        - id: "qwen2.5:latest"          name: "Qwen 2.5"

5.4 多模型切换策略

使用命令行切换

# 列出可用模型openclaw models list# 设置默认模型openclaw models set openai/gpt-4o# 设置图像模型openclaw models set-image openai/dall-e-3# 查看模型状态openclaw models status

配置模型别名

# 创建模型别名openclaw models aliases add fast gpt-3.5-turboopenclaw models aliases add smart claude-3-opus-20240229openclaw models aliases add coding tc-code-latest# 使用别名openclaw agent --model fast

配置模型回退

# 设置回退顺序openclaw models fallbacks set \  openai/gpt-4o \  anthropic/claude-3-sonnet-20240229 \  tencentcodingplan/tc-code-latest

models:  fallbacks:    - "openai/gpt-4-turbo"    - "anthropic/claude-3-sonnet-20240229"    - "ollama/llama3.2:latest"  image-fallbacks:    - "openai/dall-e-3"    - "openai/dall-e-2"

会话级模型切换

在对话中动态切换模型：

/model use gpt-4o/model use claude-3-opus/model list

6. 常见问题解答（FAQ）

Q1: 安装时遇到权限错误怎么办？

问题：EACCES: permission denied

解决：

# 方法1：使用 sudo（不推荐长期使用）sudo npm install -g openclaw# 方法2：更改 npm 默认目录mkdir ~/.npm-globalnpm config set prefix '~/.npm-global'echo 'export PATH=~/.npm-global/bin:OPENAI_API_KEY"

Q6: 如何完全重置 OpenClaw？

解决：

# 软重置（保留 CLI）openclaw reset# 完全卸载（包括 CLI）openclaw uninstall# 手动清理rm -rf ~/.openclaw

Q7: 配置文件验证失败？

解决：

# 验证配置文件openclaw config validate# 查看配置错误详情openclaw config validate --verbose

Q8: 如何备份和迁移配置？

解决：

# 创建备份openclaw backup create# 备份文件位置~/.openclaw/backups/# 手动备份tar -czvf openclaw-backup.tar.gz ~/.openclaw# 恢复到新机器tar -xzvf openclaw-backup.tar.gz -C ~/

总结

本文详细介绍了 OpenClaw 的环境搭建与配置方法，涵盖：

多种安装方式
：Docker、npm/pnpm、源码编译，适应不同场景
完整配置详解
：从基础的 Gateway 配置到复杂的模型管理
多平台集成
：Discord、Telegram、Slack、飞书、企业微信的详细配置步骤
服务管理
：Gateway 的启动、停止、监控和日志管理
模型策略
：多模型配置、切换和回退策略

完成环境搭建后，你就可以开始探索 OpenClaw 的强大功能了。下一篇文章，我们将一起开发你的第一个 Skill，真正开始 OpenClaw 的实战之旅。

相关资源：

官方文档
GitHub 仓库
ClawHub 技能市场