OpenClaw 终极指南：自托管 AI 网关安装、配置与架构原理解析

打造您的私有数字副驾驶 | 支持 Telegram/Discord/飞书 + 国产大模型接入

本文详解如何在 Ubuntu/MacOS 上部署 OpenClaw——一款开源的自托管 AI 代理网关。涵盖从 Clawd 到 OpenClaw 的品牌演变、一行命令安装（含国内镜像源）、交互式 Onboarding 配置（Telegram/Discord 机器人绑定）、以及 Gateway-Node-Canvas 核心架构深度解析。助您构建完全掌控数据、支持多模态交互与本地文件操作的私人 AI 助手

Abstract

在 SaaS 主导的 AI 时代，OpenClaw 提供了一种革命性的’自带设备 (BYOD)’模式。本文将带您从零开始，在 Linux 或 macOS 上部署这款强大的自托管 AI 网关。我们将深入探讨其独特的命名历史，对比官方与国内优化版的安装方案，手把手教您配置 Telegram 等即时通讯通道，并揭秘其 Gateway-Node-Canvas 三层架构如何实现跨平台记忆同步、本地文件操作及浏览器自动化。无论您是想接入阿里通义千问还是本地运行的大模型，本文都是您的最佳入门指南

1. 原理

OpenClaw 是一个自托管网关，可将您最喜欢的聊天应用程序（WhatsApp、Telegram、Discord、iMessage 等）连接到像 Pi 这样的 AI 编码代理。，您只需在自己的机器（或服务器）上运行一个 Gateway 进程，它就会成为您的消息应用程序和始终可用的 AI 助手之间的桥梁。

Note

Pi Ai是由由 Inflection AI 开发的一款对话式人工智能助手

OpenClaw 支持多种接入路径，具体取决于网关的运行位置以及您希望如何配置提供商。

1.1 神经中枢：Gateway网关

Gateway是OpenClaw系统的核心心脏，是一个基于Node.js（要求v22+）构建的长运行守护进程。它充当了所有外部通信与内部逻辑之间的总线

Gateway属于：控制平面(Control Plane)

所有的外部聊天链接都是它统一处理

Gateway默认绑定在本地环回地址（127.0.0.1:18789），这意味着它不直接向公网暴露端口。这种“环回优先”的网络模型强制要求所有外部访问——无论是来自移动端的Node连接，还是远程管理——必须通过安全的隧道技术（如SSH Tunnel或Tailscale）进行。

Loopback-First设计原则

1.2 感知触手：Nodes(节点)

如果说Gateway是OpenClaw的大脑，那么Nodes就是它的手脚和感官。Node是运行在iOS、Android或macOS等终端设备上的轻量级客户端程序，它们通过WebSocket连接回Gateway，将设备的物理能力虚拟化为可供Agent调用的工具

Agent无需运行在手机上，却能通过Gateway远程调用手机的硬件能力：

视觉能力 (camera.*)：Agent可以调用camera.snap指令，触发Android或iOS Node拍摄照片；或调用camera.clip录制短视频
地理感知 (location.get)：Node能够获取设备的GPS坐标，使得Agent能够提供基于位置的服务（LBS），如“我现在的坐标天气如何？”或“帮我记录停车位置”
屏幕交互 (screen.record)：在Android端，Node甚至支持屏幕录制，为未来的UI自动化操作奠定了基础

1.3 交互界面: Canavs

为了突破传统Chatbot纯文本交互的局限，OpenClaw引入了Canvas概念，这是一种由Agent驱动的动态视觉界面

Gateway内置了一个HTTP文件服务器（默认监听端口18793），专门用于服务Canvas内容。Canvas本质上是一个由Agent生成的HTML/JavaScript应用，运行在Node端的WebView容器中。

Note

OpenClaw工作流程大概就是：用户通过App聊天的形式发送指令—-> 网关，接收并路由给连接的Agent —-> Agent调用大模型进行思考，决策调用工具 —-> 工具在本地设备上执行操作 —-> 执行结果返回给Agent —-> Agent将结果返回给网关 —-> 网关将结果返回给用户

1.4 记忆系统

记忆是OpenClaw区别与普通Chatbot的核心能力，四层记忆从不可变的身份内核到实时对话，构建了完整的上下文连续性

SOUL.md 不可变内核
TOOLS：动态工具
User：语义长期记忆
Session：短期对话记忆

SOUL.md