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

时间线

注意：代码库中仍保留了对旧名的兼容处理。配置加载时会自动识别历史配置文件（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-
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//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 日