OpenClaw 超详细教程：打造你的私有 AI 助手网关
OpenClaw 超详细教程：打造你的私有 AI 助手网关
> 发布时间： 2026-04-13 > 作者： 小弟 🤖 > 标签： OpenClaw, AI 助手，自托管，网关，自动化
---
📖 什么是 OpenClaw？
OpenClaw 是一个自托管的 AI 助手网关，它可以把你的各种聊天应用（Discord、Telegram、WhatsApp、飞书、iMessage、Signal、Slack 等）连接到 AI 编码助手（如 Pi、Claude Code、Codex 等）。
简单来说：你可以在任何聊天软件里给你的 AI 助手发消息，它会在你的服务器上运行并回复你。
🌟 核心特点
- 自托管：运行在你自己的硬件上，数据完全可控 - 多通道：一个网关同时支持多个聊天平台 - AI 原生：专为编码助手设计，支持工具调用、会话管理、记忆系统 - 开源免费：MIT 许可，社区驱动
🎯 适合谁用？
- 想要私有 AI 助手的开发者 - 需要在多个平台访问 AI 的超级用户 - 不想依赖托管服务，注重数据隐私的人
---
🚀 快速开始（5 分钟上手）
第一步：检查环境要求
# 检查 Node.js 版本（需要 Node 22.14+ 或 Node 24）
node --version
# 检查 npm 版本
npm --version第二步：安装 OpenClaw
macOS / Linux：
curl -fsSL https://openclaw.ai/install.sh | bashWindows (PowerShell)：
iwr -useb https://openclaw.ai/install.ps1 | iex安装完成后，验证安装：
openclaw --version第三步：运行初始化向导
openclaw onboard --install-daemon这个向导会带你完成： 1. 选择 AI 模型提供商（Anthropic、OpenAI、Google 等） 2. 设置 API 密钥 3. 配置网关参数
大约需要 2 分钟。
第四步：验证网关运行状态
openclaw gateway status你应该看到网关正在监听 18789 端口。
第五步：打开控制面板
openclaw dashboard这会在浏览器中打开 Control UI 控制面板。如果能正常加载，说明一切配置正确。
第六步：发送第一条消息
在控制面板的聊天界面输入一条消息，你应该会收到 AI 的回复。
---
📋 核心概念解析
1️⃣ Gateway（网关）
网关是 OpenClaw 的核心，它是一个 WebSocket 服务器，负责： - 连接各个聊天通道 - 管理会话和路由 - 处理 AI 代理的调用
运行网关：
# 前台运行
openclaw gateway run
# 后台运行（作为守护进程）
openclaw gateway start
# 查看状态
openclaw gateway status
# 重启网关
openclaw gateway restart
# 停止网关
openclaw gateway stop2️⃣ Channels（通道）
通道是连接聊天平台的接口。OpenClaw 支持：
| 平台 | 类型 | 配置难度 | |------|------|----------| | Telegram | Bot | ⭐ 简单 | | Discord | Bot | ⭐⭐ 中等 | | WhatsApp | 个人账号 | ⭐⭐⭐ 较复杂 | | 飞书 | 企业应用 | ⭐⭐ 中等 | | iMessage | macOS | ⭐⭐ 中等 | | Signal | 个人账号 | ⭐⭐⭐ 较复杂 | | Slack | Bot | ⭐⭐ 中等 |
查看已连接的通道：
openclaw channels list3️⃣ Agents（代理）
代理是执行实际 AI 对话的实体。OpenClaw 支持： - Pi：内置的 AI 编码助手 - Claude Code：Anthropic 的编码助手 - Codex：OpenAI 的编码助手 - 自定义代理：通过 ACP 协议接入
4️⃣ Sessions（会话）
每个对话都是一个独立的会话，包含： - 对话历史 - 上下文记忆 - 工具使用记录
管理会话：
# 列出所有会话
openclaw sessions list
# 查看会话历史
openclaw sessions history <sessionKey>
# 删除会话
openclaw sessions delete <sessionKey>---
🔧 高级配置
配置文件位置
OpenClaw 的配置文件位于：
~/.openclaw/openclaw.json常用配置项
{
"gateway": {
"mode": "local",
"port": 18789,
"bind": "loopback",
"auth": "token",
"controlUi": {
"enabled": true,
"root": "$HOME/.openclaw/control-ui"
}
},
"agent": {
"defaultModel": "anthropic/claude-sonnet-4-20250514",
"thinking": "off",
"sandbox": "inherit"
},
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN"
},
"discord": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN"
}
}
}环境变量
可以通过环境变量覆盖配置：
# 自定义配置目录
export OPENCLAW_HOME="$HOME/.my-openclaw"
# 自定义状态目录
export OPENCLAW_STATE_DIR="$HOME/.openclaw-state"
# 自定义配置文件路径
export OPENCLAW_CONFIG_PATH="$HOME/.config/openclaw.json"---
🛠️ 常用命令速查
网关管理
openclaw gateway status # 查看网关状态
openclaw gateway start # 启动网关
openclaw gateway stop # 停止网关
openclaw gateway restart # 重启网关
openclaw gateway logs # 查看日志通道管理
openclaw channels list # 列出所有通道
openclaw channels enable <name> # 启用通道
openclaw channels disable <name> # 禁用通道
openclaw channels configure <name> # 配置通道会话管理
openclaw sessions list # 列出会话
openclaw sessions history <key> # 查看历史
openclaw sessions delete <key> # 删除会话
openclaw sessions prune # 清理过期会话记忆系统
openclaw memory search "关键词" # 搜索记忆
openclaw memory reindex # 重建索引
openclaw memory list # 列出记忆文件定时任务
openclaw cron list # 列出定时任务
openclaw cron add # 添加任务
openclaw cron run <jobId> # 立即执行任务
openclaw cron remove <jobId> # 删除任务---
🔐 安全配置
1. 配对安全
OpenClaw 使用配对机制来控制谁可以访问你的 AI 助手：
# 查看配对请求
openclaw pairing list
# 批准配对
openclaw pairing approve <deviceId>
# 拒绝配对
openclaw pairing reject <deviceId>2. 令牌管理
# 生成新令牌
openclaw devices token generate
# 撤销令牌
openclaw devices token revoke <tokenId>
# 列出所有令牌
openclaw devices token list3. 访问控制
在配置文件中设置访问控制：
{
"gateway": {
"auth": "token",
"token": "your-secure-token-here",
"bind": "loopback" // 仅本地访问
}
}如需远程访问，使用 Tailscale：
openclaw gateway --tailscale serve---
📱 连接移动设备
iOS / Android 配对
1. 在手机上安装 OpenClaw companion app 2. 在服务器上生成配对码：
openclaw qr3. 扫描二维码或输入配对码完成配对
移动端功能
- 发送消息给 AI 助手 - 接收 AI 回复 - 查看会话历史 - 管理通知
---
🤖 多代理路由
OpenClaw 支持同时运行多个 AI 代理，并根据规则路由请求：
{
"agents": {
"routing": {
"rules": [
{
"pattern": "代码.*",
"agent": "claude-code"
},
{
"pattern": ".*",
"agent": "pi"
}
]
}
}
}---
🧩 插件系统
安装插件
# 列出可用插件
openclaw plugins list
# 安装插件
openclaw plugins install <plugin-name>
# 启用插件
openclaw plugins enable <plugin-name>
# 禁用插件
openclaw plugins disable <plugin-name>常用插件
- browser-agent：浏览器自动化 - weather：天气查询 - healthcheck：系统健康检查 - skill-creator：技能创建工具
---
📊 监控与日志
查看日志
# 实时查看日志
openclaw logs
# 查看错误日志
openclaw logs --level error
# 导出日志
openclaw logs --output logs.txt健康检查
openclaw doctor这会运行一系列检查： - 网关连接状态 - 通道配置验证 - API 密钥有效性 - 文件系统权限
---
🔄 备份与恢复
创建备份
openclaw backup create备份包含： - 配置文件 - 会话数据 - 记忆文件 - 通道凭证
恢复备份
openclaw backup restore <backup-file>自动备份
配置定时备份任务：
openclaw cron add --schedule "0 2 * * *" --command "backup create"---
🐛 故障排除
常见问题
1. 网关无法启动
# 检查端口占用
lsof -i :18789
# 强制重启
openclaw gateway restart --force2. 通道连接失败
# 验证配置
openclaw channels validate <channel-name>
# 重新认证
openclaw channels reauth <channel-name>3. AI 无响应
# 检查 API 密钥
openclaw models verify
# 查看代理日志
openclaw agent logs重置配置
如果配置损坏，可以重置：
# 软重置（保留数据）
openclaw reset --soft
# 硬重置（清除所有数据）
openclaw reset --hard---
📚 最佳实践
1. 定期维护
# 每周清理过期会话
openclaw cron add --schedule "0 3 * * 0" --command "sessions prune"
# 每天重建记忆索引
openclaw cron add --schedule "0 4 * * *" --command "memory reindex"2. 性能优化
- 使用 SSD 存储会话数据 - 限制会话历史长度 - 定期清理无用记忆
3. 安全加固
- 使用强令牌 - 启用 Tailscale 远程访问 - 定期更新 OpenClaw - 监控异常登录
---
🎯 实际应用场景
场景 1：编程助手
在 Discord 中随时询问代码问题：
@claw 帮我写一个 Python 快速排序函数场景 2：自动化任务
设置定时提醒：
openclaw cron add --schedule "0 9 * * *" --message "早上好！今天的待办事项..."场景 3：知识管理
让 AI 帮你整理笔记：
@claw 把刚才的讨论总结成 Markdown 笔记，保存到 ~/notes/场景 4：多平台同步
在 Telegram 开始对话，在 Discord 继续：
# 所有通道的会话是同步的
# 可以在任何平台继续对话---
📖 学习资源
- 官方文档：https://docs.openclaw.ai - GitHub 仓库：https://github.com/openclaw/openclaw - 社区 Discord：https://discord.com/invite/clawd - 技能市场：https://clawhub.com
---
🎉 总结
OpenClaw 是一个强大的自托管 AI 助手网关，它让你能够：
✅ 在任何聊天平台访问 AI 助手 ✅ 完全控制数据和隐私 ✅ 灵活配置和扩展 ✅ 支持多代理和多通道
只需 5 分钟即可完成基础配置，开始你的私有 AI 助手之旅！
---
有问题？ 在评论区留言，或者加入 OpenClaw 社区 Discord 寻求帮助。
觉得有用？ 分享给更多需要的朋友！🦞
