OpenClaw安装全指南：安装优化 + 模型配置 + 工具启用完整教程

OpenClaw作为2026年最热门的开源AI Agent之一，以其可爱的龙虾吉祥物和强大的多平台消息整合能力吸引了大量用户。但很多新手在安装和配置过程中会遇到各种问题。本文将提供一份完整的OpenClaw安装指南，涵盖安装优化、模型配置和工具启用三大核心环节，帮助你从零开始搭建属于自己的AI助手。

一、系统要求与安装前准备

1.1 系统要求

组件	要求	备注
操作系统	macOS / Linux / Windows (WSL2)	Windows原生支持正在完善中
Node.js	v22 或更高版本（推荐LTS）	v22.14+为最低要求
内存	4GB+	运行本地模型需要更多
网络	联网	调用AI API需要，本地模型可离线

1.2 安装前准备清单

AI模型API Key：至少准备一个（Anthropic Claude、OpenAI GPT、Google Gemini等）
消息平台账号：建议从Telegram开始（最简单），后续可添加WhatsApp、Discord等
终端工具：支持二维码渲染的终端（用于WhatsApp扫码）

二、安装方式详解

2.1 方式一：官方一键安装脚本（推荐）

这是最简单快捷的安装方式，适合大多数用户：

# macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows (PowerShell)
# 使用WSL2运行上述命令

安装脚本会自动：

检查并安装Node.js（如需要）
全局安装OpenClaw CLI
启动onboard配置向导

2.2 方式二：npm/pnpm包管理器安装

适合需要灵活管理版本的用户：

# 使用npm
npm install -g openclaw

# 或使用pnpm（推荐）
pnpm add -g openclaw

# 启动配置向导
openclaw onboard

2.3 方式三：Docker安装（稳定运行推荐）

适合需要7×24小时稳定运行的场景：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 使用Docker Compose启动
docker-compose up -d

# 查看日志
docker-compose logs -f

2.4 方式四：源码编译（开发者）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm run build
pnpm run openclaw onboard

三、安装验证与故障排查

3.1 验证安装

# 检查版本
openclaw --version

# 诊断安装问题
openclaw doctor

# 查看运行状态
openclaw status

3.2 常见问题解决

问题	原因	解决方案
命令未找到	终端未重新加载	关闭并重新打开终端
权限不足	需要管理员权限	macOS/Linux加sudo，Windows以管理员运行
端口被占用	18789端口被占用	PORT=18790 openclaw gateway
Node版本太旧	低于v22	nvm install –lts && nvm use –lts
WhatsApp二维码不显示	终端不支持	换用iTerm2、Windows Terminal等

四、模型配置详解

4.1 配置文件位置

OpenClaw的核心配置文件位于：

~/.openclaw/openclaw.json

4.2 Claude模型配置（Anthropic原生格式）

使用Claude原生格式可获得完整功能（Prompt Caching、Extended Thinking等）：

{
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "https://api.anthropic.com",
        "apiKey": "sk-your-anthropic-key",
        "api": "anthropic-messages",
        "authHeader": true,
        "headers": {
          "anthropic-version": "2023-06-01"
        },
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": true,
            "input": ["text", "image"]
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

4.3 OpenAI模型配置

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-your-openai-key",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "contextWindow": 128000,
            "maxTokens": 16384
          },
          {
            "id": "gpt-5.2",
            "name": "GPT-5.2",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

4.4 Google Gemini模型配置

{
  "models": {
    "providers": {
      "google": {
        "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
        "apiKey": "your-gemini-api-key",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3.1-pro-preview",
            "name": "Gemini 3.1 Pro",
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      }
    }
  }
}

4.5 本地模型配置（Ollama）

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "api": "ollama",
        "models": [
          {
            "id": "llama3.1",
            "name": "Llama 3.1",
            "contextWindow": 128000
          },
          {
            "id": "qwen2.5",
            "name": "Qwen 2.5",
            "contextWindow": 128000
          }
        ]
      }
    }
  }
}

4.6 多模型聚合平台配置示例

以第三方API聚合平台为例，统一配置多个模型：

{
  "models": {
    "mode": "merge",
    "providers": {
      "api-aggregator": {
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "sk-your-key",
        "api": "openai-completions",
        "models": [
          {"id": "gpt-5.4", "name": "GPT-5.4"},
          {"id": "claude-sonnet-4-6", "name": "Claude Sonnet"},
          {"id": "deepseek-v3", "name": "DeepSeek V3"},
          {"id": "gemini-3-flash", "name": "Gemini Flash"}
        ]
      }
    }
  }
}

4.7 设置默认模型

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

配置完成后重启网关生效：

openclaw gateway restart

五、工具启用与配置

5.1 工具配置文件

OpenClaw提供了一等公民级别的Agent工具，涵盖browser、canvas、nodes和cron等。在openclaw.json中配置：

5.2 工具白名单配置

{
  "tools": {
    "profile": "full",
    "allow": ["browser", "web_search", "exec", "read", "write"],
    "deny": []
  }
}

可选的profile配置：

minimal：仅session_status
coding：文件系统、运行时、会话、内存、图像
messaging：消息相关工具
full：无限制

5.3 工具组快捷配置

工具组	包含工具
group:runtime	exec, bash, process
group:fs	read, write, edit, apply_patch
group:sessions	sessions_list, sessions_history, sessions_send等
group:memory	memory_search, memory_get
group:web	web_search, web_fetch
group:ui	browser, canvas
group:messaging	message

5.4 按提供商限制工具

{
  "tools": {
    "profile": "coding",
    "byProvider": {
      "google-antigravity": {
        "profile": "minimal"
      },
      "openai/gpt-5.2": {
        "allow": ["group:fs", "sessions_list"]
      }
    }
  }
}

5.5 Skills技能系统

Skills是OpenClaw的扩展能力系统：

# 查看可用技能
openclaw skills list

# 安装技能
openclaw skills install [skill-name]

# 启用技能
openclaw skills enable [skill-name]

# 禁用技能
openclaw skills disable [skill-name]

六、消息平台连接配置

6.1 Telegram（推荐新手）

在Telegram中搜索@BotFather
发送/newbot创建新机器人
复制生成的API Token
在onboard向导中粘贴Token

6.2 WhatsApp

运行openclaw onboard
选择WhatsApp连接
终端显示二维码
用WhatsApp手机版扫码

6.3 Discord

访问Discord Developer Portal
创建New Application
在Bot页面获取Token
配置必要的权限范围

七、安全最佳实践

7.1 API Key安全存储

❌ 不要在配置文件中明文存储API Key。使用环境变量：

# ~/.openclaw/env
ANTHROPIC_API_KEY=sk-your-key
OPENAI_API_KEY=sk-your-key

在配置文件中引用：

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

7.2 工作目录限制

{
  "workspace": {
    "path": "~/Documents/OpenClaw",
    "allowedPaths": ["~/Documents/OpenClaw", "~/Desktop"],
    "excludedPaths": ["~/.ssh", "~/Documents/Private"]
  }
}

7.3 DM策略配置

{
  "channels": {
    "dmPolicy": {
      "mode": "pairing",
      "allowedUsers": ["your-telegram-id"]
    }
  }
}

mode可选值：

open：允许任何人DM
pairing：仅允许配对用户
closed：禁止DM

八、性能优化技巧

8.1 模型选择策略

任务类型	推荐模型	成本对比
简单问答	DeepSeek / GPT-3.5	比GPT-4便宜30倍
代码生成	Claude Sonnet / GPT-4	平衡性能与成本
复杂推理	Claude Opus / GPT-4	高质量输出
长文档处理	Gemini 3.1 Pro	100万token上下文

8.2 成本控制建议

为不同任务配置不同模型
启用Prompt Caching（Claude原生格式支持）
限制工具调用频率
定期审查技能使用情况

九、完整配置示例

以下是一个生产环境推荐的完整配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "baseUrl": "https://api.anthropic.com",
        "apiKey": "${ANTHROPIC_API_KEY}",
        "api": "anthropic-messages",
        "authHeader": true,
        "headers": {
          "anthropic-version": "2023-06-01"
        },
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      }
    }
  },
  "tools": {
    "profile": "coding",
    "allow": ["group:fs", "group:web", "browser"],
    "deny": ["group:runtime"]
  },
  "workspace": {
    "path": "~/Documents/OpenClaw",
    "allowedPaths": ["~/Documents/OpenClaw"],
    "excludedPaths": ["~/.ssh", "~/.env"]
  },
  "channels": {
    "dmPolicy": {
      "mode": "pairing",
      "allowedUsers": []
    }
  }
}

十、总结

OpenClaw的安装和配置虽然有一定门槛，但一旦搭建完成，你将拥有一个真正属于自己的AI助手。本文涵盖了：

四种安装方式（一键脚本、npm、Docker、源码）
多平台模型配置（Claude、GPT、Gemini、Ollama）
工具启用与权限管理
消息平台连接（Telegram、WhatsApp、Discord）
安全最佳实践
性能优化建议

建议新手从Telegram + Claude Sonnet开始，逐步探索更多功能。记住，OpenClaw的真正价值在于它是一个”活”的系统——随着你的使用，它会越来越了解你的需求。

如果在配置过程中遇到问题，可以运行openclaw doctor进行诊断，或访问官方文档docs.openclaw.ai获取更多帮助。

本文基于OpenClaw 2026年5月最新版本编写，配置方式可能随版本更新而变化。

🤖 阿里云 · 大模型 AI 套餐