OpenClaw 安装与使用指南

forcedRegCsdn

586人浏览 · 2026-03-19 08:00:00

forcedRegCsdn · 2026-03-19 08:00:00 发布

简介

OpenClaw 是一个适用于任何操作系统的 AI 智能体 Gateway 网关，支持 WhatsApp、Telegram、Discord、iMessage 等多种消息渠道。通过单个 Gateway 网关进程，将聊天应用连接到 Pi 等编程智能体。

核心功能

功能	说明
多渠道网关	通过单个 Gateway 进程连接 WhatsApp、Telegram、Discord 和 iMessage
插件渠道	通过扩展包添加 Mattermost、飞书等更多渠道
多智能体路由	按智能体工作区或发送者隔离会话
媒体支持	发送和接收图片、音频和文档
Web 控制界面	浏览器仪表板用于聊天配置、会话和节点管理
移动节点	配对 iOS 和 Android 节点，支持 Canvas

工作原理

Gateway 网关是会话路由和渠道连接的唯一事实来源。所有渠道通过 Gateway 连接，实现统一的消息路由和管理。

系统要求

Node.js: 推荐 Node 24，兼容 Node 22 LTS（22.16+）
操作系统: macOS、Linux 或 Windows
Windows 用户: 强烈建议在 WSL2 下运行

如果缺失 Node.js，安装脚本会自动安装 Node 24。

安装方法

方法一：安装脚本（推荐）

安装脚本会一步完成 Node 检测、安装和新手引导。

macOS / Linux / WSL2:

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

Windows (PowerShell):

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

如需跳过新手引导，只安装二进制文件：

macOS / Linux / WSL2:

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

Windows (PowerShell):

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

方法二：npm / pnpm

如果你已自行管理 Node 环境：

使用 npm:

npm install -g openclaw@latest
openclaw onboard --install-daemon

使用 pnpm:

pnpm add -g openclaw@latest
pnpm approve-builds -g        # 批准 openclaw、node-llama-cpp、sharp 等
openclaw onboard --install-daemon

方法三：从源码安装

适用于贡献者或需要从本地运行的用户：

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

其他安装方式

Docker: 容器化部署
Nix: 声明式包管理
Ansible: 自动化部署
Bun: 实验性支持

快速入门

第一步：安装 OpenClaw

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

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

第二步：运行新手引导

openclaw onboard --install-daemon

新手引导会配置：

认证设置
Gateway 网关设置
可选渠道配置

第三步：检查 Gateway 网关状态

openclaw gateway status

如果已安装服务，它应该已经在运行。

第四步：打开控制界面

openclaw dashboard

如果 Control UI 能加载，你的 Gateway 网关就已准备就绪。

本地访问: http://127.0.0.1:18789/
远程访问: 通过 Web 界面或 Tailscale

第五步：配对渠道并启动网关

# 配对 WhatsApp（需扫描二维码）
openclaw channels login

# 启动 Gateway 网关
openclaw gateway --port 18789

配置说明

配置文件位于 ~/.openclaw/openclaw.json

默认行为

如果你不做任何修改，OpenClaw 将：

使用内置的 Pi 二进制文件以 RPC 模式运行
按发送者创建独立会话

基础配置示例

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

常用环境变量

变量	说明
`OPENCLAW_HOME`	设置主目录，用于内部路径解析
`OPENCLAW_STATE_DIR`	覆盖状态目录
`OPENCLAW_CONFIG_PATH`	覆盖配置文件路径

消息渠道配置

支持的渠道

渠道	说明	设置难度
Telegram	Bot API，支持群组	简单（推荐入门）
WhatsApp	需二维码配对	中等
Discord	Bot API + Gateway	简单
BlueBubbles	推荐 iMessage 方案	中等
Signal	signal-cli，注重隐私	中等
Slack	Bolt SDK，工作区应用	简单
飞书	飞书/Lark 机器人，需插件	中等
Mattermost	Bot API + WebSocket，需插件	中等

提示: 最快的设置方式通常是 Telegram，只需简单的机器人令牌。

Telegram 配置

1. 创建机器人

打开 Telegram，搜索 @BotFather
运行 /newbot，按提示设置名称和用户名
复制返回的 token

2. 配置 Token

方式一：环境变量

export TELEGRAM_BOT_TOKEN="your-bot-token"

方式二：配置文件

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

3. 隐私模式设置

Telegram 机器人默认启用隐私模式，限制接收群组消息。如需机器人看到所有群组消息：

方式一：通过 @BotFather 的 /setprivacy 禁用隐私模式
方式二：将机器人添加为群组管理员

WhatsApp 配置

# 登录并配对
openclaw channels login

# 配置示例

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+15555550123"]
    }
  }
}

群组消息规则

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-1001234567890": {
          "requireMention": false
        }
      }
    }
  }
}

模型提供商配置

支持的提供商

提供商	说明
Anthropic	API + Claude Code CLI
OpenAI	API + Codex
Ollama	本地模型运行（详见下方章节）
OpenRouter	多模型聚合
GLM	智谱 AI 模型
Qwen	通义千问
Moonshot AI	Kimi + Kimi Coding
MiniMax	MiniMax 模型
Amazon Bedrock	AWS 云服务
vLLM	本地模型

配置默认模型

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

身份验证

# 通过新手引导配置
openclaw onboard

或手动设置环境变量：

export ANTHROPIC_API_KEY="your-api-key"
export OPENAI_API_KEY="your-api-key"

Ollama 集成

Ollama 是一个本地运行大语言模型的工具，OpenClaw 支持与 Ollama 无缝集成，让你可以使用本地模型运行 AI 智能体。

前置条件

安装 Ollama

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

# 或访问 https://ollama.ai 下载

启动 Ollama 服务

ollama serve

拉取模型

# 查看已安装的模型
ollama list

# 拉取支持工具调用的模型
ollama pull llama3.3
ollama pull qwen2.5-coder:32b
ollama pull deepseek-r1:32b

基本设置（隐式发现）

启用 Ollama 最简单的方式是通过环境变量：

export OLLAMA_API_KEY="ollama-local"

设置后，OpenClaw 会自动发现本地运行的 Ollama 实例（默认 http://localhost:11434），并自动检测支持工具调用的模型。

显式配置（手动模型）

在以下情况使用显式配置：

Ollama 运行在其他主机/端口上
需要强制指定上下文窗口或模型列表
需要包含不报告工具支持的模型

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://ollama-host:11434",
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [
          {
            "id": "gpt-oss:20b",
            "name": "GPT-OSS 20B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 8192,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

自定义基础 URL

如果 Ollama 运行在不同的主机或端口上：

{
  "models": {
    "providers": {
      "ollama": {
        "apiKey": "ollama-local",
        "baseUrl": "http://192.168.1.100:11434"
      }
    }
  }
}

注意: 显式配置会禁用自动发现，因此需要手动定义模型。

模型选择

配置完成后，可以指定使用 Ollama 模型：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/llama3.3",
        "fallbacks": ["ollama/qwen2.5-coder:32b", "ollama/deepseek-r1:32b"]
      }
    }
  }
}

模型	说明	工具调用
`llama3.3`	Meta Llama 3.3，综合能力强	支持
`qwen2.5-coder:32b`	通义千问代码模型	支持
`deepseek-r1:32b`	DeepSeek 推理模型	支持
`gpt-oss:20b`	GPT-OSS 开源模型	支持

高级功能

推理模型

当 Ollama 在 /api/show 中报告 thinking 时，OpenClaw 会将模型标记为具有推理能力：

ollama pull deepseek-r1:32b

流式配置

OpenClaw 的 Ollama 集成默认使用原生 Ollama API（/api/chat），完全支持同时进行流式传输和工具调用，无需特殊配置。

旧版 OpenAI 兼容模式

如果需要使用 OpenAI 兼容端点：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "api": "openai-completions",
        "apiKey": "ollama-local",
        "models": [...]
      }
    }
  }
}

注意: OpenAI 兼容端点可能不支持同时进行流式传输和工具调用，可能需要使用 params: { streaming: false } 禁用流式传输。

上下文窗口

对于自动发现的模型，OpenClaw 使用 Ollama 报告的上下文窗口（如果可用），否则默认为 8192。可以在显式配置中覆盖：

{
  "models": {
    "providers": {
      "ollama": {
        "models": [
          {
            "id": "llama3.3",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

Ollama 故障排除

Ollama 未被检测到

检查 Ollama 是否运行：

ollama serve

验证 API 可访问：

curl http://localhost:11434/api/tags

确保设置了 OLLAMA_API_KEY，并且未定义显式的 models.providers.ollama 条目（让 OpenClaw 自动发现）。

没有可用模型

OpenClaw 只会自动发现报告工具支持的模型。如果模型未列出：

# 查看已安装的模型
ollama list

# 拉取支持工具调用的模型
ollama pull llama3.3
ollama pull qwen2.5-coder:32b

或在 models.providers.ollama 中显式定义该模型。

连接被拒绝

# 检查 Ollama 是否在运行
ps aux | grep ollama

# 重启 Ollama
ollama serve

# 检查端口
lsof -i :11434

常用命令

Gateway 管理

# 检查网关状态
openclaw gateway status

# 前台运行网关
openclaw gateway --port 18789

# 安装为系统服务
openclaw onboard --install-daemon

消息发送

# 发送测试消息
openclaw message send --target +15555550123 --message "Hello from OpenClaw"

渠道管理

# 登录渠道
openclaw channels login

# 查看渠道状态
openclaw channels status

仪表板

# 打开控制界面
openclaw dashboard

故障排除

找不到 openclaw 命令

原因: PATH 环境变量未正确配置

解决方案:

# 检查 npm 全局安装路径
npm config get prefix

# 添加到 PATH（bash）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 或重新安装
npm install -g openclaw@latest

sharp 构建错误

解决方案:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Gateway 无法启动

检查端口是否被占用：

lsof -i :18789

检查配置文件语法：

cat ~/.openclaw/openclaw.json

查看日志：

openclaw logs

更新与卸载

更新 OpenClaw

npm install -g openclaw@latest

或使用安装脚本：

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

卸载 OpenClaw

npm uninstall -g openclaw

清理配置文件（可选）：

rm -rf ~/.openclaw

部署选项

OpenClaw 支持多种部署方式：

平台	说明
VPS 托管	自有服务器部署
Fly.io	云平台部署
Hetzner	云服务器
GCP	Google Cloud Platform
Railway	PaaS 平台
Render	云平台部署
Docker	容器化部署

所有评论(0)

查看更多评论

forcedRegCsdn

@forcedRegCsdn

已为社区贡献5条内容

OpenClaw 安装与使用指南

forcedRegCsdn

简介

核心功能

工作原理

系统要求

安装方法

方法一：安装脚本（推荐）

方法二：npm / pnpm

方法三：从源码安装

其他安装方式

快速入门

第一步：安装 OpenClaw

第二步：运行新手引导

第三步：检查 Gateway 网关状态

第四步：打开控制界面

第五步：配对渠道并启动网关

配置说明

默认行为

基础配置示例

常用环境变量

消息渠道配置

支持的渠道

Telegram 配置

1. 创建机器人

2. 配置 Token

3. 隐私模式设置

WhatsApp 配置

群组消息规则

模型提供商配置

支持的提供商

配置默认模型

身份验证

Ollama 集成

前置条件

基本设置（隐式发现）

显式配置（手动模型）

自定义基础 URL

模型选择

推荐模型

高级功能

推理模型

流式配置

旧版 OpenAI 兼容模式

上下文窗口

Ollama 故障排除

Ollama 未被检测到

没有可用模型

连接被拒绝

常用命令

Gateway 管理

消息发送

渠道管理

仪表板

故障排除

找不到 openclaw 命令

sharp 构建错误

Gateway 无法启动

更新与卸载

更新 OpenClaw

卸载 OpenClaw

部署选项

相关链接

所有评论(0)

forcedRegCsdn