OpenClaw 完整上手教程：本地优先的开源 AI 智能体 Gateway

2026-06-17 · AI Agent

GitHub 星标 37.8 万+ 的"AI 小龙虾"，用最酷的方式把任意聊天软件变成 AI 助手的入口

一、工具介绍：它到底是什么？

OpenClaw（社区昵称"小龙虾 AI"）是一个 2025 年底在 GitHub 上发布的开源项目，采用 MIT 协议，当前版本 v2.15.0。截至 2026 年 6 月，GitHub Star 已突破 37.7 万，是 GitHub 历史上增长最快的 AI 项目之一。定位是"the AI that actually does things"——真正能执行任务的 AI。

1.1 核心定位

新手最容易误解的就是把它当成"另一个大模型"或"聊天机器人"。事实上：

它不是大模型，而是一个"AI 智能体网关（Agent Gateway）"——把 Discord、WhatsApp、Telegram、iMessage、Slack、飞书、钉钉、企业微信等聊天应用与本地/云端大模型进行桥接
它不是 ChatGPT 替代品，而是为所有大模型（Claude、GPT-4、Kimi、DeepSeek、Qwen、Llama 3 等 200+ 模型）装上"能动手的身体"
它不是云服务，而是一个本地优先、自托管的 Gateway 网关进程

它的 Slogan 是"脱壳！脱壳！"——出自电影中的一只太空龙虾。

1.2 四大核心特性

① 本地优先的隐私架构

所有对话历史、任务记录、记忆文件默认保存在你本地设备（~/.openclaw/workspace/），仅在调用云端大模型 API 时才按需联网。可完全接入本地 Ollama 模型实现离线运行。

② 模型无关的开放设计

天生不绑定任何厂商，兼容 Claude、GPT-4、Kimi、DeepSeek、Qwen、Gemini、Llama、Qwen-VL 等 200+ 主流模型，支持云端 API 和本地模型一键热切换，零厂商锁定。

③ 安全可控的隔离沙箱

采用细胞级沙箱隔离 + 权限白名单机制，每个任务独立运行，能精准拦截高风险系统命令（如 rm -rf、format、修改系统目录）。

④ 无限扩展的技能生态

核心架构极度精简，所有能力都通过"技能包（Skill）"扩展。全球开发者贡献的 Skills 库涵盖浏览器自动化、文件整理、邮件处理、代码部署、订餐购物等场景。

1.3 适合谁用？

想要一个 7×24 在线、能跨平台调用的私人 AI 助理的职场人
希望数据完全可控、不愿把对话记录交给 SaaS 厂商的隐私党
需要把 AI 接入多个聊天渠道（微信、WhatsApp、Telegram、飞书等）的开发者
想用本地大模型 + 远程调度做混合架构的 AI 工程师

二、安装步骤（全平台）

2.1 系统要求

项目	最低要求	推荐配置
操作系统	Windows 10+ / macOS 12+ / Ubuntu 20.04+	macOS 14+ / Ubuntu 22.04+
Node.js	v22.16+ LTS	v24（最新 LTS）
内存	2GB	4GB+（跑本地模型建议 16GB+）
磁盘	1GB（不含模型）	50GB+（含模型）
权限	macOS/Linux 需 sudo，Windows 需管理员 PowerShell	—

2.2 方式一：一键脚本安装（强烈推荐）

macOS / Linux：

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

Windows（PowerShell 管理员模式）：

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

脚本会自动完成：
1. 检测 Node.js 版本，缺失则通过 nvm 自动安装 v24
2. 全局安装 openclaw CLI
3. 创建 ~/.openclaw/ 配置目录
4. 注册 PATH 环境变量

2.3 方式二：npm 全局安装

如果你已经装了 Node 22+，可以直接：

npm install -g openclaw@latest

验证安装：

openclaw --version
# 应输出类似：openclaw 1.x.x

2.4 方式三：Docker 部署（适合服务器）

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  ghcr.io/openclaw/openclaw:latest

2.5 安装后初始化

启动新手引导：

openclaw onboard --install-daemon

向导会依次询问：
1. 是否了解风险 → 选 Yes（个人本地使用风险极低）
2. 安装模式 → 选 QuickStart（快速开始）
3. 模型提供商 → 国内用户选 Moonshot AI，海外用户选 OpenAI 或 Anthropic
4. API Key → 按提示去对应平台生成并粘贴
5. 聊天界面 → 选 TUI（终端界面）最快上手
6. 技能安装 → 全选 Yes 即可，后续可随时增删
7. 附加服务（Google Places / Notion / OpenAI Vision）→ 暂时全选 No，需要时再开

三、基础使用

3.1 启动 TUI 终端聊天

openclaw tui

界面类似：

┌─ OpenClaw TUI ────────────────┐
│ > 你好，帮我把 Downloads 文件夹│
│   里的 PDF 按月份归档         │
│                                │
│ [Agent 正在思考...]            │
│ > 好的，我先扫描 Downloads    │
│   目录，统计 PDF 文件的修改   │
│   时间...                      │
└────────────────────────────────┘

输入 /exit 退出 TUI，/status 查看运行状态。

3.2 启动 Web 控制台（推荐）

openclaw dashboard

浏览器自动打开 http://127.0.0.1:18789/，可看到完整的聊天、配置、会话、节点管理界面。Web 控制台比 TUI 更直观，支持：
- 多会话标签页
- 文件拖拽上传
- Markdown 实时渲染
- 代码块语法高亮
- 会话历史回溯

3.3 核心 CLI 命令

# 系统状态
openclaw status                # 查看 Gateway、模型、技能整体状态
openclaw gateway status        # 仅查看 Gateway 网关状态
openclaw health                # 健康检查

# 模型管理
openclaw models list           # 列出已配置模型
openclaw models set            # 切换默认模型
openclaw models aliases list   # 模型别名

# 技能管理
openclaw skills list           # 列出已安装技能
openclaw skills info <id>      # 查看技能详情
openclaw skills check          # 检查技能兼容性

# 渠道管理（连接聊天软件）
openclaw channels list         # 已配置渠道
openclaw channels add telegram # 添加 Telegram 渠道
openclaw channels login whatsapp # 扫码登录 WhatsApp

# 记忆管理
openclaw memory status         # 记忆索引状态
openclaw memory search "..."   # 语义搜索历史记忆
openclaw memory index          # 重建索引

# 安全审计
openclaw security audit        # 检查配置风险
openclaw security audit --fix  # 自动修复默认配置

# 定时任务
openclaw cron add "0 9 * * *" "生成今日工作报告"

# 浏览器自动化
openclaw browser open https://github.com
openclaw browser screenshot ~/Desktop/github.png

3.4 全局参数

openclaw --dev                 # 隔离状态到 ~/.openclaw-dev（多环境）
openclaw --profile work        # 隔离到 ~/.openclaw-work
openclaw --json <cmd>          # 输出 JSON 便于脚本处理
openclaw --no-color            # 禁用颜色

四、实战案例

案例 1：自动整理 Downloads 文件夹

场景：Downloads 里堆了 500+ 个杂乱文件，按"按类型/月份"归档。操作（在 TUI 或 Web 中输入）：

把 ~/Downloads 里所有文件按"年-月"目录归档，
PDF 放进 ~/Documents/PDF/，图片放进 ~/Pictures/，代码包放进 ~/Projects/，
重复文件移到 ~/Trash/。操作前先列出将要移动的文件清单等我确认。

OpenClaw 会：
1. 扫描 Downloads，统计文件类型分布
2. 生成一份《拟移动文件清单》供你审核
3. 确认后逐步执行移动，每步反馈结果
4. 全部完成后输出归档报告

案例 2：定时抓取 GitHub Trending 写日报

配置：

# 1. 注册一个 cron 任务
openclaw cron add "0 9 * * *" "抓取 GitHub Trending 今日 Top 10，
整理成中文日报，发送到 Telegram @my_daily_channel"

每天早上 9 点，OpenClaw 会自动执行：
1. 访问 https://github.com/trending
2. 抓取 Top 10 项目
3. 调 LLM 生成中文摘要
4. 通过 Telegram Bot 推送到你的频道

案例 3：把 Telegram 变成随身 AI 助理

配置步骤：

# 1. 在 Telegram @BotFather 创建机器人，拿到 TOKEN
# 2. 启动 OpenClaw 渠道配置
openclaw channels add telegram
# 粘贴 Bot Token
# 3. 启动 Gateway
openclaw gateway start

现在你随时在手机上发消息给这个 Bot，OpenClaw 就会在后台（云服务器/家里 NAS/Mac mini）执行任务并回复。

案例 4：本地跑 Llama 3 + Web 搜索

# 1. 先用 Ollama 拉模型
ollama pull llama3:8b

# 2. 在 OpenClaw 中配置 Ollama 提供商
openclaw configure
# 选择 Providers → Add Provider → Ollama
# Base URL: http://localhost:11434

# 3. 设为默认
openclaw models set ollama/llama3:8b

# 4. 启用本地搜索插件
openclaw plugins install openclaw-plugin-local-search

这样你就能在完全离线的环境下使用 AI 助理。

案例 5：HTTP API 集成到自己的应用

OpenClaw Gateway 暴露了 HTTP API（默认 18789 端口），可直接 POST：

curl -X POST http://127.0.0.1:18789/v1/chat \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "main",
    "message": "用三句话总结《三体》第一部的核心冲突",
    "session": "user-42"
  }'

{
  "reply": "三体文明的智子锁死了地球基础科学...",
  "session": "user-42",
  "model": "moonshot/kimi-k2.5",
  "tokens_used": 234
}

五、常见问题与解决方案

Q1：安装成功后终端找不到 `openclaw` 命令

原因：npm 全局目录未加入 PATH。解决：

# 1. 确认 Node 是否安装
node -v

# 2. 查看全局包路径
npm prefix -g
# 输出类似：/Users/you/.npm-global

# 3. 把全局 bin 目录加入 PATH（macOS/Linux）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 4. Windows：编辑系统环境变量，添加 %AppData%\npm 到 Path

Q2：Windows 上 `iwr` 提示"无法解析脚本"

原因：PowerShell 执行策略限制。解决：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 然后重新执行安装命令

Q3：`openclaw status` 报 "Gateway not running"

解决：

openclaw gateway start          # 直接启动
# 或
openclaw gateway restart        # 重启
# 查日志定位
openclaw logs --tail 100

Q4：Telegram Bot 收不到消息

排查步骤：

# 1. 检查渠道状态
openclaw channels status telegram

# 2. 测试连通性
openclaw channels logs telegram --tail 50

# 3. 常见原因：
#    - Bot Token 配错（注意不是 Bot 用户名）
#    - 没向 Bot 发送过 /start 消息激活
#    - Gateway 绑定了 loopback 而非 LAN

Q5：本地 Ollama 模型响应慢

优化：

# 1. 确认 Ollama 在跑
ollama list
curl http://localhost:11434

# 2. 使用量化版模型（显存吃紧时）
ollama pull llama3:8b-instruct-q4_0

# 3. 调整 OpenClaw 超时
openclaw config set providers.ollama.timeoutMs 120000

Q6：磁盘占用增长快

原因：记忆文件、会话历史、模型缓存堆积。清理：

# 清理过期会话（保留 30 天）
openclaw sessions prune --older-than 30d

# 重建记忆索引
openclaw memory index

# 手动清理日志
openclaw logs prune --older-than 7d

Q7：技能（Skill）安装失败

# 查看详情
openclaw skills info <skill-id>

# 检查依赖
openclaw doctor

# 重装
openclaw skills install <skill-id> --force

Q8：安全审计告警如何处理

openclaw security audit
# 输出会列出风险项，逐条对照处理
# 一键修复安全默认值
openclaw security audit --fix

六、总结与资源链接

6.1 总结

OpenClaw 不是另一个聊天 AI，而是一个把 AI 接入你现有工具链的执行网关。它的杀手锏是：

跨渠道：一个 Gateway 同时服务 10+ 聊天平台
本地优先：数据不出本机，隐私零妥协
模型无关：今天用 Kimi，明天切 Llama 3，后天本地跑 Qwen
沙箱安全：敢让 AI 动手执行命令，因为有隔离保护

对于中国用户，强烈推荐 Kimi K2.5 + OpenClaw 的组合——Kimi 性价比极高，OpenClaw 负责执行，完美互补。

6.2 推荐部署方案

用户类型	推荐方案
纯小白	直接用 Kimi/OpenAI 官方集成的 OpenClaw 在线版
普通用户	云服务器（阿里云/腾讯云 2核4G ≈ 100 元/月）+ Moonshot API
隐私党	Mac mini / NAS 本地部署 + Ollama 本地模型
极客玩家	树莓派 5 + 小模型（Phi-3 / Gemma 2B）+ Tailscale 远程访问

6.3 资源链接

GitHub 仓库：https://github.com/openclaw/openclaw
官方文档（中文）：https://docs.openclaw.ai/zh-CN
社区文档镜像：https://openclawcn.com
新手入门：https://docs.openclaw.ai/zh-CN/start/getting-started
CLI 参考：https://openclawcn.com/en/docs/cli/
故障排查：https://docs.openclaw.ai/zh-CN/help
技能市场：https://docs.openclaw.ai/zh-CN/tools/plugin
社区讨论：https://github.com/openclaw/openclaw/discussions
一键安装脚本：https://openclaw.ai/install.sh
npm 包：https://www.npmjs.com/package/openclaw
Docker 镜像：ghcr.io/openclaw/openclaw:latest
腾讯云部署教程：
阿里云部署教程：

6.4 下一步学习路径

第一周：跑通 tui 和 dashboard，熟悉基础对话
第二周：接入 1 个聊天渠道（推荐 Telegram，最简单）
第三周：装 3-5 个实用 Skills（文件整理、浏览器自动化、邮件处理）
第四周：配置定时任务和记忆系统，开始让它"记住"你的工作习惯
第二个月：尝试多智能体路由 + 自定义 Skill，开始深度定制

养好你的小龙虾，AI 打工人就能 7×24 帮你干活了。

← 返回教程列表