OpenClaw 安装指南（面向开发人员）

本文档旨在帮助开发人员快速上手 OpenClaw，无论是本地开发调试、集成自定义 AI 模型，还是为 OpenClaw 贡献代码。你将了解多种安装方式、配置选项、渠道接入以及调试技巧。

---

简介

OpenClaw 是一个可扩展的 AI 助手框架，支持接入多种消息渠道（Web、WhatsApp、Telegram、Discord 等）和自定义 AI 模型。开发者可以通过配置文件、插件系统或直接修改源码来定制功能。

---

前提条件

• Node.js 18+ 和 npm / yarn / pnpm
• Git（用于源码安装）
• 一个可用的 AI 服务 API Key（如 OpenAI、Azure OpenAI、通义千问等，或使用本地模型）
• （可选）Docker 用于容器化部署
• 熟悉命令行和基本的环境变量配置

---

安装方式

1. 快速安装脚本（推荐快速体验）

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

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

脚本会自动安装 Node.js（如缺失）并运行初始化向导。完成后可通过 openclaw 命令管理。

2. 源码安装（适合开发/定制）

git clone https://github.com/openclaw/core.git
cd core
npm install  # 或 yarn / pnpm install

复制环境变量模板并编辑：

cp .env.example .env
# 编辑 .env 填入你的 AI 提供商配置

3. Docker 部署

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/data:/app/data \
  -e OPENAI_API_KEY=your_key \
  openclaw/core:latest

或使用 docker-compose（参考项目中的 docker-compose.yml 示例）。

---

配置

环境变量

核心配置通过 .env 文件或系统环境变量设置。主要变量包括：

变量名	说明	示例
AI_PROVIDER	AI 提供商	openai, azure, qwen
OPENAI_API_KEY	API 密钥	sk-xxx
OPENAI_MODEL	模型名称	gpt-4
PORT	Web 服务端口	18789
DATABASE_URL	数据库连接（可选）	postgresql://user:pass@localhost/db

配置文件

高级配置可放在 config/default.json 或 config/production.json 中（遵循 node-config 规范）。示例：

{
  "ai": {
    "provider": "openai",
    "options": {
      "temperature": 0.7,
      "maxTokens": 2000
    }
  },
  "channels": {
    "web": { "enabled": true },
    "telegram": {
      "enabled": false,
      "botToken": "xxx"
    }
  }
}

多渠道接入

在配置文件中启用相应渠道并填写凭证：

• Telegram: 创建 Bot 获取 token，设置 channels.telegram.botToken
• WhatsApp: 通过 WhatsApp Business API 或第三方服务，配置相应接入点
• Discord: 创建 Bot 并获取 token，设置 channels.discord.botToken

详细说明请参考官方文档。

自定义 AI 模型

除预置提供商外，可通过实现 AIAdapter 接口接入自定义模型。在 src/ai/adapters 中添加适配器，并在配置中指定。

---

运行

开发模式（支持热重载）

npm run dev

生产模式

npm run build
npm start

作为后台服务运行

使用 openclaw CLI（安装后）：

openclaw gateway start
openclaw dashboard  # 打开管理界面

或使用 PM2：

pm2 start npm --name "openclaw" -- start

---

验证

浏览器打开 http://localhost:18789，你应该能看到 OpenClaw 的 Web 聊天界面。发送一条消息测试响应。

---

调试与日志

• 设置环境变量 DEBUG=openclaw:* 开启调试日志。
• 日志文件默认位于 logs/ 目录（可通过 LOG_DIR 修改）。
• 使用 openclaw doctor 诊断常见问题。
• 查看服务状态：openclaw gateway status。

---

扩展开发

• 插件系统：在 plugins/ 目录下创建插件，遵循插件开发指南。
• 自定义技能：通过编写 skills/ 中的函数扩展 AI 能力。
• 贡献代码：Fork 项目，提交 PR，请确保通过测试 npm test。

---

常见问题

1. openclaw 命令找不到

确保安装脚本执行后，重新打开终端或手动将 ~/.openclaw/bin 加入 PATH。

2. 数据库连接失败

如果使用 SQLite，确保数据库文件可写；若使用 PostgreSQL，检查连接字符串和网络。

3. AI 模型返回超时

检查网络代理设置，或调整 AI_REQUEST_TIMEOUT 环境变量。

4. 如何切换 AI 提供商？

修改 .env 中的 AI_PROVIDER 和对应密钥，重启服务。

---

后续学习

• 阅读官方文档了解更多功能。
• 查看 API 参考 进行二次开发。
• 加入开发者社区（Discord 链接见项目主页）。
  现在你可以开始构建自己的 AI 助手了！

推荐学习企业级AI智能体架构

基于.NET构建的企业级SaaS——AI智能体应用架构，RAGAI检索增强：

• 项目地址：github：https://github.com/junkai-li/NetCoreKevin
  Gitee: https://gitee.com/netkevin-li/NetCoreKevin