Loading... # OpenClaw 安装配置指南 # 一、概述 ## 1. 简介 ### A. 是什么 OpenClaw 是一个开源的个人 AI 助手平台，支持多平台集成（WhatsApp、Telegram、Discord 等）和任务自动化。 ### B. 为什么使用 - 支持多聊天平台统一管理 - 提供 WebSocket Gateway 实现实时通信 - 支持代理管理和会话持久化 - 开源免费，可自主部署 ### C. 学完能做什么 - 在 Linux 环境中安装 OpenClaw - 配置和管理聊天频道 - 运行和监控 Gateway 服务 - 使用控制面板管理 AI 代理 ## 2. 前置知识 ### A. 必备技能 - 基本 Linux 命令操作 - 了解 Node.js 和 npm 基本概念 ### B. 推荐知识 - 了解 WebSocket 基本原理 - 熟悉 JSON 配置文件 # 二、环境准备 ## 1. 系统要求 - 操作系统：Linux（Kali、Ubuntu、Debian 等） - Node.js：v22.12.0 或更高版本 - 构建工具：gcc、make、g++、python3 - 内存：至少 2GB 可用 - 磁盘：至少 500MB 可用空间 ## 2. 安装步骤 ### 检查 Node.js 版本 ```bash node --version ``` ### 检查构建工具 ```bash make --version gcc --version ``` ### 检查 npm（通过 corepack） ```bash node /usr/share/nodejs/corepack/dist/npm.js --version ``` ## 3. 验证安装 确保所有前置条件满足后再继续。 # 三、核心概念 ## 1. 基本术语 - Gateway（网关）：WebSocket 服务器，处理通道和代理之间的通信 - Agent（代理）：AI 智能体，处理用户消息和任务 - Channel（通道）：连接的聊天平台（Telegram、Discord 等） - Session（会话）：用户与代理之间的对话历史 - Credentials（凭证）：第三方服务的认证信息 ## 2. 工作原理 ```mermaid graph TB Client[用户客户端<br/>Telegram/Discord] --> Channel[通道模块] Channel --> Gateway[WebSocket 网关] Gateway --> Agent[AI 代理] Agent --> Gateway Gateway --> Channel Channel --> Client Gateway --> Control[控制面板<br/>http://127.0.0.1:18789] Agent --> Session[(会话存储)] Channel --> Cred[(凭证存储)] ```  # 四、快速上手 ## 1. 安装 OpenClaw ### 官方安装脚本（推荐） ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` ### 替代方案：用户级安装 当 npm 通过 corepack 提供且没有系统级权限时使用： ```bash # 创建用户级 npm 目录 mkdir -p ~/.npm-global # 设置环境变量 export npm_config_prefix="$HOME/.npm-global" export PATH="$npm_config_prefix/bin:$PATH" # 使用 corepack npm 安装 npm_config_prefix="$HOME/.npm-global" PATH="$npm_config_prefix/bin:$PATH" \ node /usr/share/nodejs/corepack/dist/npm.js install -g openclaw@latest ``` ## 2. 验证安装 ```bash # 检查可执行文件 ls -la ~/.npm-global/bin/openclaw # 查看版本 ~/.npm-global/bin/openclaw --version # 检查已安装包 ~/.npm-global/bin/node /usr/share/nodejs/corepack/dist/npm.js list -g openclaw ``` 预期输出： - 可执行文件：~/.npm-global/bin/openclaw - 版本：2026.2.26（或更新版本） ## 3. 初始化配置 首次使用前需要运行配置向导： ```bash ~/.npm-global/bin/openclaw onboard ``` 或使用交互式设置向导： ```bash ~/.npm-global/bin/openclaw configure ``` 配置完成后，配置文件位于： - 主配置：~/.openclaw/openclaw.json - 工作空间：~/.openclaw/workspace - 凭证：~/.openclaw/credentials - 日志：~/.openclaw/logs/ # 五、启动服务 ## 1. 启动 Gateway ```bash ~/.npm-global/bin/openclaw gateway ``` 默认配置： - WebSocket 地址：ws://127.0.0.1:18789 - 控制面板：http://127.0.0.1:18789/ ## 2. 检查服务状态 ```bash # 健康检查 ~/.npm-global/bin/openclaw health # 查看详细状态 ~/.npm-global/bin/openclaw status ``` 正常输出示例： ``` Gateway: local · ws://127.0.0.1:18789 · reachable 62ms Telegram: ok (@your_bot_name) ``` ## 3. 访问控制面板 浏览器访问：http://127.0.0.1:18789/ # 六、常用命令 ## 1. 核心命令 | 命令 | 说明 | |------|------| | openclaw gateway | 启动 WebSocket 网关 | | openclaw status | 查看系统状态 | | openclaw health | 健康检查 | | openclaw configure | 交互式配置向导 | | openclaw onboard | 初始化配置向导 | | openclaw channels | 管理聊天通道 | | openclaw agents | 管理代理 | | openclaw message | 发送消息 | ## 2. 通道管理 ```bash # 登录 Telegram 通道 ~/.npm-global/bin/openclaw channels login --channel telegram # 查看通道状态 ~/.npm-global/bin/openclaw channels list # 登录 Discord ~/.npm-global/bin/openclaw channels login --channel discord ``` ## 3. 日志查看 ```bash # 实时查看网关日志 ~/.npm-global/bin/openclaw logs --follow # 查看指定行数的日志 ~/.npm-global/bin/openclaw logs --lines 100 ``` # 七、常见问题 ## 1. 安装问题 ### npm command not found 问题：官方脚本无法找到 npm 命令 解决方案：使用用户级安装方案 ```bash mkdir -p ~/.npm-global export npm_config_prefix="$HOME/.npm-global" export PATH="$npm_config_prefix/bin:$PATH" ``` ### 原生模块编译失败 问题：sharp、canvas 等原生模块编译失败 解决方案：安装构建依赖 ```bash sudo apt-get update sudo apt-get install -y build-essential python3 python3-dev ``` ## 2. 运行问题 ### Gateway 无法连接 问题：ECONNREFUSED 127.0.0.1:18789 解决方案：检查 Gateway 是否运行 ```bash ~/.npm-global/bin/openclaw gateway ``` ### 凭证目录权限警告 问题：credentials 目录权限过于宽松 解决方案：收紧权限 ```bash chmod 700 ~/.openclaw/credentials ``` ## 3. 配置问题 ### 如何设置自定义端口 编辑 ~/.openclaw/openclaw.json，修改 gateway.port 字段 ### 如何启用 dev 模式 ```bash ~/.npm-global/bin/openclaw --dev gateway ``` dev 模式使用独立的配置和状态目录（~/.openclaw-dev/） # 八、安全建议 ## 1. 基本安全措施 - 使用强密码保护控制面板 - 不要在公共网络暴露 Gateway 端口 - 定期备份配置和会话数据 - 设置凭证目录权限为 700 ## 2. 网络安全 - 使用反向代理时配置 trustedProxies - 启用 HTTPS 访问控制面板 - 限制聊天机器人的访问权限 ## 3. 运行安全检查 ```bash # 运行安全审计 ~/.npm-global/bin/openclaw security audit # 运行系统健康检查 ~/.npm-global/bin/openclaw doctor ``` *** ## 参考资料 1. [OpenClaw 官方文档](https://docs.openclaw.ai/) 2. [OpenClaw GitHub 仓库](https://github.com/openclaw/openclaw) 3. [OpenClaw 安装指南](https://openclaw.ai/install.sh) 最后修改：2026 年 02 月 28 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏