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 | bash

Windows (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 的回复。

---

📋 核心概念解析

核心组件说明：

- Gateway（网关） - WebSocket 服务器，负责连接各个聊天通道、管理会话和路由、处理 AI 代理的调用 - Channels（通道） - 连接聊天平台的接口，支持 Telegram、Discord、WhatsApp、飞书等 - Agents（代理） - 执行实际 AI 对话的实体，支持 Pi、Claude Code、Codex 等 - Sessions（会话） - 每个对话都是独立的会话，包含对话历史、上下文记忆、工具使用记录

---

🔧 高级配置

配置文件位置

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 ` - 启用通道 - `openclaw channels disable ` - 禁用通道 - `openclaw channels configure ` - 配置通道

会话管理命令：

- `openclaw sessions list` - 列出会话 - `openclaw sessions history ` - 查看历史 - `openclaw sessions delete ` - 删除会话 - `openclaw sessions prune` - 清理过期会话

记忆系统命令：

- `openclaw memory search "关键词"` - 搜索记忆 - `openclaw memory reindex` - 重建索引 - `openclaw memory list` - 列出记忆文件

定时任务命令：

- `openclaw cron list` - 列出定时任务 - `openclaw cron add` - 添加任务 - `openclaw cron run ` - 立即执行任务 - `openclaw cron remove ` - 删除任务

---

🔐 安全配置

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 list

3. 访问控制

在配置文件中设置访问控制：

{
  "gateway": {
    "auth": "token",
    "token": "your-secure-token-here",
    "bind": "loopback"  // 仅本地访问
  }
}

如需远程访问，使用 Tailscale：

openclaw gateway --tailscale serve

---

📱 连接移动设备

iOS / Android 配对

1. 在手机上安装 OpenClaw companion app 2. 在服务器上生成配对码：

openclaw qr

3. 扫描二维码或输入配对码完成配对

移动端功能

- 发送消息给 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 --force

2. 通道连接失败

# 验证配置
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 寻求帮助。

觉得有用？ 分享给更多需要的朋友！🦞

cnbugsai

打赏 海报 链接