OpenClaw 技术指南：从入门到精通 2026 年最火开源 AI 助手全攻略 上篇

基于 OpenClaw 2026.3.2 源码深度解析，2026 年 3 月最新版

目录

1. 第一章：认识 OpenClaw
2. 第二章：安装部署
3. 第三章：基础配置
4. 第四章：工作区与记忆系统
5. 第五章：AI 模型配置

第一章：认识 OpenClaw

1.1 什么是 OpenClaw？

OpenClaw 是一个自托管、多通道 AI 网关，由 Peter Steinberger（PSPDFKit 创始人）开发。它能将你熟悉的聊天工具（WhatsApp、Telegram、飞书、Discord 等）连接到 AI 编程代理，让 AI 不再只是"对话框问答"，而是能直接执行任务的智能体（Agent）。

当前最新版本：openclaw 2026.3.2（2026 年 3 月发布）

项目仓库：https://github.com/openclaw/openclaw

核心定位：Multi-channel AI Gateway with extensible messaging integrations（多通道 AI 网关 + 可扩展消息集成）。

与传统聊天机器人的本质区别：

核心能力：

• 将自然语言目标拆解为可执行步骤
• 自动调用终端命令、创建与修改文件
• 操作浏览器（Playwright/Chrome）、收发邮件、管理日历
• 运行代码并根据报错自动修复
• 跨会话保持上下文和记忆（向量索引 + FTS5 全文检索）
• 多 Agent 并行工作，通过 ACP 协议协作

1.2 名称演变史

OpenClaw 经历了三次更名：

注意：代码库中仍保留了对旧名的兼容处理。配置加载时会自动识别历史配置文件（clawdbot.json、moldbot.json、moltbot.json）并迁移到 openclaw.json。

1.3 核心架构

OpenClaw 采用单进程网关架构，所有功能通过一个常驻进程提供：

聊天应用 / 插件 | Gateway (ws://127.0.0.1:18789) ── 控制平面 | +-- Pi Agent (RPC 模式) 推理引擎 +-- CLI (openclaw ...) 命令行工具 +-- WebChat UI / Control UI Web 控制面板 +-- macOS/iOS/Android Nodes 原生客户端 +-- Tools 浏览器/Canvas/Cron/Webhooks

关键组件：

1. Gateway（网关）：单端口复用 WebSocket + HTTP，处理所有消息路由、模型调度和工具调用
2. Agent（代理）：推理引擎，理解用户意图并决定如何响应。支持多 Agent 隔离
3. Skills（技能）：模块化能力扩展，通过 SKILL.md 文件定义
4. Memory（记忆）：向量索引 + FTS5 全文检索 + Markdown 文件，持久存储上下文
5. Channels（通道）：消息平台适配器，核心 + 插件两类
6. Nodes（节点）：macOS/iOS/Android 原生客户端，提供 Canvas、Voice 等本地能力

1.4 与 Claude Code 的对比

两者可以互补——OpenClaw 甚至支持通过 ACP 协议桥接 Claude Code、Codex 等 IDE 工具。

第二章：安装部署

2.1 系统要求

最低配置：

• CPU：2 核
• 内存：2GB（推荐 4GB）
• 磁盘：10GB 预留空间
• Node.js >= 22（硬性要求）

支持平台：

• macOS（Intel / Apple Silicon）—— 有独立的菜单栏应用
• Linux（Ubuntu/Debian/CentOS 等）—— systemd 用户服务
• Windows（推荐 WSL2）
• Docker
• 云平台 VM（GCP、Railway、Render、Fly.io、Hetzner 等）
• Raspberry Pi

2.2 一键安装（推荐）

macOS / Linux

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

Windows（PowerShell 管理员模式）

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

安装脚本会自动：

1. 检测系统环境
2. 安装 Node.js（如未安装）
3. 通过 npm 安装 OpenClaw
4. 启动配置向导（onboarding）

2.3 手动安装

如果一键脚本失败，可以手动安装：

# 1. 确保 Node.js >= 22 node -v # 2. 使用 npm 安装 npm i -g openclaw # 或使用 pnpm pnpm add -g openclaw # 3. 运行配置向导 openclaw onboard

2.4 从源码安装（开发者）

# 克隆仓库 git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装依赖（pnpm 或 bun 均可） pnpm install # 构建 Web UI pnpm ui:build # 构建项目 pnpm build # 初始化并安装为系统服务 pnpm openclaw onboard --install-daemon # 开发模式（监听代码变更） pnpm gateway:watch

2.5 Docker 安装

仓库提供了 Dockerfile，可自行构建镜像：

# 从源码构建 git clone https://github.com/openclaw/openclaw.git cd openclaw docker build -t openclaw . # 运行容器 docker run -d \ --name openclaw \ -p 18789:18789 \ -v ~/.openclaw:/root/.openclaw \ openclaw

注意：Docker 镜像以非 root 用户运行，支持 --read-only 和 --cap-drop=ALL 安全选项。

2.6 安装为系统服务

安装后建议配置为守护进程，实现开机自启：

# 通过 onboard 向导自动安装 openclaw onboard --install-daemon # macOS：通过 launchd 管理（或使用 OpenClaw Mac 菜单栏应用） # Linux：通过 systemd 用户服务管理

服务管理命令：

openclaw gateway start # 启动 openclaw gateway stop # 停止 openclaw gateway restart # 重启 openclaw gateway status # 查看状态

2.7 内存不足处理

如果服务器内存小于 4GB，建议配置 swap：

# 创建 2G swap 文件 sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 开机自动启用 echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

2.8 验证安装

# 查看版本 openclaw --version # 健康检查 openclaw health # 深度诊断 openclaw doctor --deep

第三章：基础配置

3.1 配置向导（Onboarding）

安装完成后，运行交互式配置向导：

openclaw onboard

向导分为三种模式：

• quickstart（默认）：最少交互，自动生成网关 Token
• advanced：完整的端口/绑定/认证配置
• manual：纯手动配置

向导会依次引导你完成：

1. 风险确认：OpenClaw 能执行终端命令和操作文件，请确认了解风险
2. 网关模式选择：本地运行（local）或连接远程网关（remote）
3. 模型提供商选择：选择 AI 供应商并配置 API Key 或 OAuth
4. 网关设置：端口（默认 18789）、绑定模式、认证方式
5. 聊天通道配置：选择要接入的消息平台
6. 技能发现与安装：选择预装的 Skills
7. 健康检查与首次测试

也可以用非交互模式（适合 CI/CD 或无头服务器）：

openclaw onboard --non-interactive \ --accept-risk \ --flow quickstart \ --anthropic-api-key "sk-ant-..." \ --gateway-port 18789 \ --gateway-bind loopback \ --install-daemon

3.2 配置文件说明

文件位置与格式

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

• 格式：JSON5（支持注释和尾逗号）
• 严格校验：未知的 key 或错误的类型会导致网关拒绝启动
• 环境变量替换：支持 ${ENV_VAR} 占位符
• 热重载：支持不重启应用更新配置（需开启 gateway.reload）
• 覆盖方式：环境变量 OPENCLAW_CONFIG_PATH 可指定自定义路径

你可以用以下命令管理配置：

# 查看配置文件路径 openclaw config file # 读取配置值（支持点号和括号表示法） openclaw config get gateway.port openclaw config get agents.list[0].id # 设置配置值（值会自动解析为 JSON5） openclaw config set gateway.port 18789 openclaw config set agents.defaults.heartbeat.every "2h" # 删除配置值 openclaw config unset tools.web.search.apiKey # 校验配置合法性 openclaw config validate # 在编辑器中打开配置文件 openclaw config edit # 交互式配置向导（分节） openclaw configure openclaw configure --section channels openclaw configure --section models

配置文件结构概览

{ // 元数据 meta: { lastTouchedVersion: "2026.3.2", lastTouchedAt: "2026-03-02T00:00:00Z" }, // 网关设置 gateway: { port: 18789, // 默认端口 mode: "local", // "local" | "remote" bind: "loopback", // "loopback" | "lan" | "tailnet" | "auto" | "custom" auth: { mode: "token", // "none" | "token" | "password" | "trusted-proxy" token: "${OPENCLAW_GATEWAY_TOKEN}" }, tls: { enabled: false, autoGenerate: true }, controlUi: { enabled: true }, reload: { mode: "hybrid" // "off" | "restart" | "hot" | "hybrid" } }, // Agent 配置 agents: { defaults: { workspace: "~/.openclaw/workspace", heartbeat: { every: "30m" }, memorySearch: { enabled: true, provider: "auto" // "openai" | "local" | "gemini" | "auto" 等 }, compaction: { memoryFlush: { enabled: true, softThresholdTokens: 4000 } } }, list: [ { id: "main" } // 默认有一个 main agent ] }, // 通道配置 channels: { telegram: { enabled: true, botToken: "${TELEGRAM_BOT_TOKEN}", dmPolicy: "pairing" } }, // 模型配置 models: { // 模型别名、默认模型、降级策略等 }, // 技能配置 skills: { // 加载路径、限制等 } }

安全提示：配置文件中的 API Key 建议使用环境变量引用（${ENV_VAR}），避免明文存储。

3.3 关键路径一览

3.4 网关绑定模式

# 设置绑定模式 openclaw config set gateway.bind "loopback" # 设置认证 openclaw config set gateway.auth.mode "token" openclaw config set gateway.auth.token "your-strong-token"

第四章：工作区与记忆系统

4.1 工作区文件说明

工作区是 Agent 的"大脑"，默认位于 ~/.openclaw/workspace/。以下是核心文件：

工作区路径解析优先级：

1. 环境变量 OPENCLAW_PROFILE（非 "default" 时）→ ~/.openclaw/workspace-<profile>
2. 配置项 agents.defaults.workspace
3. 每个 Agent 独立配置 agents.list[].workspace
4. 默认：~/.openclaw/workspace

4.2 记忆架构

OpenClaw 的记忆系统分为三层：

记忆系统 +-- 短期记忆（会话内） | +-- 对话上下文 | +-- 工具调用结果 | +-- 长期记忆（跨会话） | +-- memory/YYYY-MM-DD.md 每日日志（仅追加） | +-- MEMORY.md 精炼的持久记忆 | +-- SQLite 向量索引 语义检索（memory-index.db） | +-- FTS5 全文索引 关键词检索 | +-- 工作记忆（角色定义） +-- USER.md 用户偏好 +-- SOUL.md 人格设定 +-- IDENTITY.md 身份标识

记忆工具（Agent 可调用）：

自动记忆冲刷（Memory Flush）：当会话接近上下文窗口压缩阈值时，OpenClaw 会自动触发一轮静默 Agent 回合，提醒模型将重要信息写入持久记忆文件，防止上下文压缩导致信息丢失。

配置示例：

{ agents: { defaults: { compaction: { memoryFlush: { enabled: true, softThresholdTokens: 4000 } } } } }

4.3 向量搜索配置

OpenClaw 支持多种嵌入模型提供商，用于驱动语义记忆检索：

当 provider 设为 "auto" 时，按以下顺序自动选择：Local → OpenAI → Gemini → Voyage → Mistral → 禁用。

本地模型（无需 API Key）：默认使用 embeddinggemma-300m-qat-Q8_0.gguf，通过 node-llama-cpp 运行。

远程自定义 Endpoint（如 SiliconFlow）：

{ agents: { defaults: { memorySearch: { enabled: true, provider: "openai", // 使用 OpenAI 兼容接口 model: "BAAI/bge-m3", remote: { baseUrl: "https://api.siliconflow.cn/v1", apiKey: "${SILICONFLOW_API_KEY}" }, vector: { enabled: true }, fts: true, // 同时启用全文检索 citations: "auto" // 私聊自动引用来源 } } } }

4.4 会话存储

• 存储路径：~/.openclaw/agents/<agentId>/sessions/
• 格式：JSONL（每行一条 JSON 记录）
• 元数据：sessions.json 存储会话列表（ID、创建时间、Token 消耗等）
• CLI 命令：

# 查看会话列表 openclaw sessions --json # 清理过期会话 openclaw sessions cleanup --dry-run openclaw sessions cleanup --enforce

第五章：AI 模型配置

5.1 支持的模型提供商

OpenClaw 支持众多 AI 模型提供商，通过统一的认证和路由层管理：

国际提供商：

• Anthropic（Claude Sonnet 4.6 / Opus 4.6）—— API Key 或 Setup Token
• OpenAI（GPT-4o / GPT-4o-mini）—— OAuth 或 API Key
• Google Gemini（Gemini 2.0 Flash / 1.5 Pro）—— CLI Auth 或 API Key
• AWS Bedrock（通过 Bedrock 使用 Claude 模型）
• OpenRouter（多模型网关）
• Together（Together.ai）
• Voyage（嵌入模型）
• Mistral
• xAI（Grok）
• Venice
• HuggingFace

国内提供商（推荐新手从这些开始）：

• 通义千问 / Qwen（阿里云）—— Portal Auth
• MiniMax（免费试用）—— Portal Auth
• DeepSeek
• Kimi / Moonshot
• 智谱 GLM
• 火山引擎 / BytePlus
• 小米

本地模型：

• Ollama（本地推理）
• vLLM（本地推理）
• LiteLLM（代理到任意 LLM）
• GitHub Copilot（企业接入）

5.2 模型管理命令

# 列出所有可用模型 openclaw models list --all # 仅列出本地模型 openclaw models list --local # 按提供商筛选 openclaw models list --provider anthropic # 查看当前模型状态 openclaw models status # 设置默认模型 openclaw models set anthropic/claude-sonnet-4-6 # 设置图像生成模型 openclaw models set-image openai/dall-e-3 # 扫描可用模型 openclaw models scan

5.3 认证配置

# 添加认证配置 openclaw models auth add # 交互式登录（OAuth 流程） openclaw models auth login # 使用 Setup Token openclaw models auth setup-token # 粘贴 Token openclaw models auth paste-token

5.4 模型降级（Fallback）

当主模型不可用时，OpenClaw 自动切换到备选模型：

# 查看降级链 openclaw models fallbacks list # 添加降级模型 openclaw models fallbacks add openai/gpt-4o # 图像模型降级 openclaw models image-fallbacks add openai/dall-e-3

5.5 模型别名

方便在聊天中快速切换：

# 查看别名 openclaw models aliases list # 添加别名 openclaw models aliases add sonnet anthropic/claude-sonnet-4-6

聊天中使用 /model sonnet 即可切换。

5.6 模型探测

验证模型配置是否正常：

# 探测所有已配置模型 openclaw models status --probe # 探测特定提供商 openclaw models status --probe-provider anthropic

下篇预告

OpenClaw 完全指南（下篇）将覆盖：

• 第六章：接入 23+ 聊天平台（Telegram/Discord/WhatsApp/飞书/Matrix 等）
• 第七章：Skills 技能生态系统
• 第八章：高级功能（多 Agent、ACP 协议、Canvas、语音、定时任务、浏览器自动化）
• 第九章：安全加固指南
• 第十章：常见问题与命令速查表

本文基于 OpenClaw 2026.3.2 源码验证，最后更新：2026 年 3 月 2 日