一、OpenClaw 简介
OpenClaw 是一个面向开发者的 AI Agent 协作平台，基于 Claude Code 构建，支持多模型接入、多智能体协作和飞书深度集成。平台采用模块化架构，允许开发者自定义 Agent 行为、接入自有大模型 API，并实现与企业协作工具的无缝对接。无论是构建内部知识助手、自动化工作流，还是构建多Agent客服系统，OpenClaw 都能提供灵活的基础设施支持。
本文将详细介绍 OpenClaw 的三种安装路径、环境配置、初始化流程以及常见问题的解决方案，帮助技术人员快速搭建并运行自己的 AI Agent 协作平台。
二、环境准备
在开始安装 OpenClaw 之前，需要确保系统满足以下依赖要求。
操作系统要求：macOS 12.0 及以上版本，Linux 发行版（Ubuntu 20.04+、Debian 11+），Windows WSL2 环境。推荐使用 macOS 以获得最佳开发体验。
运行时依赖：
- Node.js：需要 v18.0.0 或更高版本。建议使用 nvm 进行版本管理，执行
nvm install 18 && nvm use 18可快速完成安装。验证安装：node -v应返回 v18.x.x 或更高版本。 - npm：随 Node.js 一起安装，验证命令
npm -v应返回 9.x.x 或更高版本。 - Git：用于代码版本管理和插件安装，macOS 用户可通过
xcode-select --install安装，Linux 用户使用apt install git安装。 - Python（可选）：如果需要使用 Python 扩展或脚本组件，建议安装 Python 3.10+。
网络要求：OpenClaw 需要访问 OpenAI/Anthropic/MiniMax 等模型 API 服务器，请确保开发环境可以访问相关域名。如遇到网络问题，可配置代理或使用国内模型提供商（如 MiniMax）。
存储空间：OpenClaw 核心程序约占用 200MB 空间，加上模型缓存和工作区文件，建议预留至少 2GB 可用磁盘空间。
三、安装步骤
OpenClaw 提供三种安装路径，分别适用于不同的使用场景。以下详细介绍每种方式的安装步骤。
3.1 方式一：Homebrew 安装（推荐 macOS 用户）
Homebrew 是 macOS 上最方便的包管理工具，通过 brew 安装可以自动处理依赖和路径配置。
第一步：添加 OpenClaw Tap
打开终端，执行以下命令添加 OpenClaw 的 Homebrew 仓库：
brew tap openclaw-projects/openclaw
如果遇到权限问题，可能需要先创建 tap 目录：mkdir -p $(brew --prefix)/Library/Taps/openclaw-projects/
第二步：安装 OpenClaw
执行安装命令：
brew install openclaw
第三步：验证安装
检查安装结果：
openclaw --version
正常情况下会返回版本号，如 openclaw v2026.3.23。
卸载命令：
brew uninstall openclaw
3.2 方式二：npm 全局安装（跨平台推荐）
npm 安装方式适用于 macOS、Linux 和 Windows（WSL）环境，是最通用的安装方式。
第一步：检查 Node.js 环境
确保 Node.js 和 npm 已正确安装：
node -v # 应返回 v18.0.0 或更高
npm -v # 应返回 9.0.0 或更高
如未安装，请访问 Node.js 官网下载 LTS 版本，或使用 nvm 管理。
第二步：全局安装 OpenClaw
使用 npm 全局安装：
npm install -g @openclaw/core
如果遇到权限错误（EACCES），有两种解决方案：
方案 A：创建 npm 全局目录并配置环境变量：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
方案 B：使用 sudo（不推荐，生产环境避免使用）：
sudo npm install -g @openclaw/core
第三步：验证安装
openclaw --version
claude --version # 检查底层 Claude Code 版本
更新命令：
npm update -g @openclaw/core
卸载命令：
npm uninstall -g @openclaw/core
3.3 方式三：源码安装（开发者自定义）
源码安装适合需要深度定制 OpenClaw 或参与开发的用户。
第一步：克隆代码仓库
git clone https://github.com/openclaw-projects/openclaw.git
cd openclaw
第二步：安装依赖
npm install
这会根据 package.json 自动安装所有运行时和开发依赖。如果需要安装特定版本：
npm install --package-lock-only
npm install <version>
第三步：构建项目
npm run build
构建成功后会生成 dist 目录，包含编译后的 JavaScript 文件。
第四步：链接到全局
在源码目录执行链接命令，使 openclaw 命令全局可用：
npm link
验证链接：
openclaw --version
开发模式：如需修改代码并实时生效：
npm run dev
这会启动监听模式，代码修改后自动重新构建。
四、配置引导
安装完成后，需要进行初始化配置才能正常使用 OpenClaw。本节详细介绍配置流程。
4.1 初始化配置
启动配置向导：
openclaw configure
该命令会引导你完成以下配置项：
- 工作区目录：选择 OpenClaw 的工作目录，默认
~/.openclaw/workspace-<username>。建议使用独立目录以便管理多个项目。 - 默认模型：选择默认使用的大模型。可选模型包括 Claude 系列、MiniMax 系列等。
- 日志级别：设置日志详细程度，可选 debug、info、warn、error。
配置完成后，所有配置会保存在 ~/.openclaw/openclaw.json 文件中。手动编辑此文件也可以修改配置：
vim ~/.openclaw/openclaw.json
4.2 配置 API Key
OpenClaw 需要接入大模型 API 才能正常工作。以下是配置方法。
MiniMax 配置（国内推荐）：
- 访问 MiniMax 开放平台（https://platform.minimaxi.com）注册账号
- 在控制台创建 API Key
- 编辑配置文件
~/.openclaw/openclaw.json：
{"auth": {"profiles": {"minimax:cn": {"provider": "minimax","mode": "api_key","api_key": "your-api-key-here"}}},"models": {"providers": {"minimax": {"baseUrl": "https://api.minimaxi.com/anthropic","models": [{"id": "MiniMax-M2.7","name": "MiniMax M2.7"}]}}}
}
Anthropic Claude 配置：
- 访问 Anthropic Console（https://console.anthropic.com）获取 API Key
- 配置文件中添加：
{"auth": {"profiles": {"anthropic:default": {"provider": "anthropic","mode": "api_key","api_key": "sk-ant-api03-your-key-here"}}}
}
多模型切换：使用 --model 参数指定模型：
openclaw chat --model minimax/MiniMax-M2.7
4.3 飞书集成配置
OpenClaw 支持与飞书（ Lark / Feishu）深度集成，实现企业协作场景。
第一步：创建飞书应用
- 访问飞书开放平台（https://open.feishu.cn）
- 创建企业自建应用
- 配置应用权限：im:message、im:chat:readonly、contacts:readonly 等
第二步：获取应用凭���
在飞书应用后台获取 App ID 和 App Secret。
第三步：配置 OpenClaw
编辑 ~/.openclaw/openclaw.json，添加飞书配置：
{"feishu": {"enabled": true,"app_id": "cli_xxxxxxxxxxxxxx","app_secret": "your-app-secret"}
}
第四步：验证连接
openclaw feishu test
正常情况下会返回飞书机器人状态信息。
配置 Webhook（可选）：如需接收飞书消息：
openclaw feishu webhook --enable
这会创建一个 HTTP 服务器监听飞书事件的回调。
五、启动验证
完成配置后，开始验证 OpenClaw 是否正常工作。
5.1 服务启动
启动交互式对话：
openclaw chat
这会启动一个交互式对话界面，输入你的问题后按回车发送。使用 Ctrl+C 或 exit 命令退出。
单次请求：
openclaw chat --prompt "你好，请介绍一下 OpenClaw" --stream
--stream 参数开启流式输出，更适合长文本响应。
指定 Agent：
openclaw run --agent academic-geographer "介绍一下北京的地理环境"
5.2 状态检查
检查配置状态：
openclaw status
返回内容包括：工作区路径、当前模型、API Key 配置状态、飞书连接状态等。
检查模型连接：
openclaw models list
列出所有可用的模型及其状态。
查看日志：
openclaw logs --tail 50
查看最近 50 行日志，用于排查问题。日志文件位于 ~/.openclaw/logs/ 目录。
六、常见问题 FAQ
Q1：npm install -g 报 EACCES 错误？
这是权限问题。解决方案：创建 npm 全局目录并配置 PATH，或使用 Homebrew 安装方式。详见 3.2 节。
Q2：启动时报 "API Key not found" 错误？
请确认已在 ~/.openclaw/openclaw.json 中正确配置 API Key，检查 Key 是否过期或额度是否用完。
Q3：飞书消息发送失败？
检查以下三点：1）应用是否已添加机器人到群聊；2）App ID 和 App Secret 是否正确；3）应用权限是否足够。
Q4：模型响应速度慢？
可能是网络延迟问题。检查开发环境到 API 服务器的网络状况，或考虑使用国内模型提供商（如 MiniMax）。
Q5：如何查看 OpenClaw 版本？
执行 openclaw --version。使用 npm list -g @openclaw/core 可查看已安装的具体版本号。
Q6：配置文件在哪里？
主配置文件位于 ~/.openclaw/openclaw.json，历史备份位于 ~/.openclaw/openclaw.json.bak*。使用 openclaw configure 可交互式修改配置。
以上为 OpenClaw 安装教程的全部内容。如需了解更多高级功能，如自定义 Agent、多模型切换策略、高级飞书集成等，请参考 OpenClaw 官方文档。祝你使用愉快！