🦞 OpenClaw 终极部署指南：从入门到精通

本文是一篇关于 OpenClaw 的详尽指南，旨在为您提供比官方文档更细致的步骤、更深入的解释和更丰富的实践技巧。无论您是初次接触 AI 代理，还是希望将其深度集成到工作流中，本指南都将是您的得力助手。
QQ交流群：1078800977

我们将涵盖以下内容：

  • 核心概念剖析：不仅告诉您 OpenClaw 是什么，更解释它为何如此设计。
  • 环境准备：提供包含“为什么”的详细解释，助您做出最佳选择。
  • 分步安装：为不同操作系统提供带有预期输出的精细化指令。
  • 傻瓜式配置向导：深入解读每个配置选项的含义及影响。
  • 日常使用与维护：提供可直接使用的命令和脚本，让您的 OpenClaw 稳定运行。
  • 安全加固：这是本指南的重中之重，确保您的 AI 助手不会变成安全漏洞。
  • 高级技巧与故障排除：覆盖从源码编译到解决国内网络问题的各种疑难杂症。

让我们开始吧！

一、OpenClaw 是什么？重新认识你的个人 AI 助理

1.1 核心定义

OpenClaw 是一个开源的个人 AI 助手网关。

您可以把它想象成一个强大的“中间人”或“调度中心”。它本身不是 AI，但它将您最常用的聊天工具（如 WhatsApp, Telegram）与强大的 AI 大模型（如 Claude, ChatGPT）连接起来，让您能够通过简单的聊天消息，远程、安全地控制和操作您的个人电脑。

  • 开发者：Peter Steinberger (PSPDFKit 创始人) 和 Mario Zechner (Pi 创建者)。
  • 名字由来：OpenClaw = CLAW + TARDIS — 一个充满极客情怀的名字，寓意着这个工具如同太空龙虾的时间机器一样强大。

1.2 核心价值：为什么你需要它？

想象一下，您正在外面，突然需要：

  • 运行一个服务器上的脚本来分析日志。
  • 获取电脑上某个重要文件的内容。
  • 让 AI 基于您本地最新的代码库回答一个技术问题。
  • 重启一个卡住的 Docker 容器。

传统方式可能需要打开笔记本、连接 VPN、使用 SSH 或远程桌面等复杂操作。而使用 OpenClaw，您只需在手机的 Telegram 或 WhatsApp 上发送一条指令，就像和朋友聊天一样简单。它将您的电脑变成了一个随时待命、可通过聊天控制的超级助理。

1.3 支持的平台

OpenClaw 通过不同的技术连接各种即时通讯（IM）平台：

平台 集成方式 详细说明
WhatsApp 原生集成 通过 Baileys 库模拟 WhatsApp Web 客户端，功能最完整，但需要扫码登录。
Telegram Bot API 使用官方机器人 API，配置简单，支持私聊和群组。是最稳定和推荐的方式之一。
Discord Bot API 同样使用官方机器人 API，适合重度 Discord 用户和社区管理。
iMessage 本地集成 仅限 macOS，通过 imsg 这个命令行工具实现，侵入性较低。
Mattermost 插件 通过 Bot Token 和 WebSocket 事件连接，主要面向企业用户。

二、核心特性与架构 ✨

2.1 主要功能

  • 🤖 AI 代理桥接：核心功能。可以连接到遵循特定协议（如 Pi RPC 模式）的 AI 代理，并支持工具的流式调用。
  • 💬 流式响应：AI 的回答会像打字一样逐字或逐块显示，显著提升交互体验。
  • 🧠 多代理路由：可以设置多个 AI 代理，并将来自不同聊天工具或用户的消息路由到特定的代理。例如，将工作群的消息路由到“工作代理”，私人聊天的消息路由到“生活代理”。
  • 🔐 订阅认证：支持通过 OAuth 方式复用您已有的 Claude Pro/Max 或 ChatGPT Plus 订阅，无需额外购买 API aky。
  • 📎 媒体与语音支持：不仅支持文本，还可以发送和接收图片、文档。语音笔记可以被自动转录成文字，再交由 AI 处理。
  • 🖥️ 原生 UI 支持：提供了 Web 界面、macOS 菜单栏应用和 iOS/Android 客户端，方便监控和管理。

2.2 架构解析

理解其架构有助于您更好地进行配置和排错。

  • Gateway (网关)：是整个系统的心脏。它是一个后台服务，负责监听所有已连接聊天平台的消息，并决定将消息分发给哪个 AI 代理。
  • Pi Agent (代理)：是系统的大脑和双手。它接收来自网关的指令，调用大语言模型（如 Claude）进行思考，并能执行本地命令（如读写文件、运行脚本）。
  • Clients (客户端)：您用来发送指令的聊天工具，是系统的嘴和耳朵。
  • CLI / UI：是您用来管理和监控 OpenClaw 的控制台。

三、系统要求：我的电脑能跑吗？

在开始之前，请确保您的系统满足以下最低要求。

项目 要求 详细说明与原因
Node.js ≥ 22.x [必需] 这是 OpenClaw 的核心运行时。项目使用了 Node.js 22+ 版本的新特性，低于此版本将无法运行。
构建工具 pnpm [推荐] 如果您打算从源码构建，强烈推荐使用 pnpm，它通过符号链接技术管理依赖，速度更快且极大地节省了磁盘空间。
内存 (RAM) 最低 2GB，推荐 4GB+ 2GB 仅够勉强运行。一个 AI 代理实例、Gateway 和 Node.js 环境本身就会占用相当多的内存。若同时使用多个频道或大型 AI 模型，4GB 或更多是流畅运行的保证。
磁盘空间 最低 1GB，推荐 5GB+ 除了程序本身，日志文件 (/tmp/openclaw/)、工作区文件 (~/.openclaw/workspace/) 和 Node.js 模块缓存都会持续占用空间。

操作系统特别说明

  • macOS:

    • 推荐。如果您需要使用 iMessage 频道或构建 .app 应用，则必须安装 Xcode 或其轻量级的命令行工具 (xcode-select --install)。
    • 仅使用 CLI 和 Gateway，则只需 Node.js。

  • Windows:

    • 强烈建议使用 WSL2 (Windows Subsystem for Linux)。原生 Windows 环境未经充分测试，可能会在文件路径、权限管理、后台服务等方面遇到各种难以预料的问题。
    • 请务必先配置好 WSL2，然后在 WSL2 的 Linux 环境（推荐 Ubuntu）中执行所有后续步骤。这会为您省去大量麻烦。

  • Linux:

    • 最佳选择。特别是对于 7x24 小时运行的服务器部署，Linux 提供了无与伦比的性能和稳定性。无额外要求。

🌐 网络要求

  • 必须能访问国际互联网：因为需要调用 Anthropic、OpenAI 等公司的 API。
  • 国内用户特别注意：由于网络限制（GFW），您必须配置一个可靠的全局或命令行代理。否则，Gateway 在启动时会因无法连接到所需服务（如模型 API、NPM 仓库）而失败。

四、安装前准备：磨刀不误砍柴工

4.1 获取 AI 模型的 API Key

OpenClaw 需要一个“大脑”，这个“大脑”就是 AI 模型。您需要从模型提供商那里获取一个 API Key，它是一串密钥，用于证明您有权使用他们的服务。

选择一个即可：

  1. Anthropic Claude (首选推荐)

    • 优点：提供了性能和成本之间极佳平衡的 Claude 3 Sonnet 模型，以及能力超群的 Claude 3 Opus 模型。
    • 获取方式：
      1. 访问 Anthropic Console。
      2. 注册或登录您的账户。
      3. 在 Settings -> API Keys 页面点击 Create Key。
      4. 立即复制并妥善保管好这个以 sk-ant-api... 开头的 Key，因为它只会出现一次。

  2. OpenAI (ChatGPT/Codex)

    • 优点：生态成熟，模型选择多样。
    • 获取方式：
      1. 访问 OpenAI Platform API Keys。
      2. 注册或登录。
      3. 创建一个新的 Secret Key。

  3. 其他选项 (国内推荐)

    • MiniMax / 智谱 GLM：如果您在国内，访问 Claude 或 OpenAI 不稳定，这些是很好的替代品。请参考其官网获取 API Key。
    • 本地 Ollama 模型：如果您希望完全离线运行，或出于隐私考虑，可以配置 OpenClaw 使用本地通过 Ollama 部署的模型。

4.2 安装 Node.js (版本 ≥ 22)

强烈推荐使用 nvm (Node Version Manager) 来安装 Node.js。

  • 为什么用 nvm？ nvm 允许您在电脑上轻松地安装和切换多个 Node.js 版本。这对于管理不同项目（可能需要不同 Node 版本）非常方便，且避免了使用 sudo 安装带来的权限问题。

安装步骤 (macOS / Linux):

# 1. 下载并运行 nvm 安装脚本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 2. 使 nvm 命令生效 (根据您的 shell 选择)。脚本通常会自动配置，但手动执行一次更保险。
# 对于 bash 用户 (通常是 Linux 默认)
source ~/.bashrc
# 对于 zsh 用户 (通常是 macOS 默认)
source ~/.zshrc

# 3. 验证 nvm 是否安装成功。如果输出了 'nvm'，则表示成功
command -v nvm

# 4. 安装 Node.js 版本 22
nvm install 22

# 5. 将版本 22 设置为当前及默认使用版本
nvm use 22
nvm alias default 22

# 6. 最终验证安装结果
echo "Node version: $(node --version)"
echo "npm version: $(npm --version)"

预期输出:

Node version: v22.x.x
npm version: v10.x.x

4.3 (可选) 安装 pnpm

如果您计划从源码进行修改和编译，推荐安装 pnpm。

# 使用 npm 全局安装 pnpm
npm install -g pnpm

五、安装 OpenClaw

5.1 一键安装脚本 (最推荐)

这个脚本会为您自动检测操作系统、设置路径并完成所有必要操作。

  • macOS / Linux:

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

  • Windows (在 PowerShell 中以管理员身份运行):

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

5.2 NPM 全局安装 (备选方案)

如果您更喜欢通过包管理器进行控制，可以使用 npm 或 pnpm。

# 使用 npm
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

5.3 验证安装

无论使用哪种方法，安装后都应立即验证 openclaw CLI 是否可用。

# 1. 检查版本号
openclaw --version

# 2. 查看帮助文档，确认命令已正确安装并可以执行
openclaw --help

如果命令提示 command not found，通常是 shell 的 PATH 环境变量没有正确配置。请完全关闭并重新打开您的终端窗口。如果问题依旧，请检查您的 shell 配置文件 (~/.zshrc 或 ~/.bashrc) 是否包含了 npm 全局包的路径。

六、首次配置向导：让 OpenClaw 跑起来

安装完成后，我们需要进行首次配置。onboard 命令将通过一个交互式向导引导您完成所有基础设置。

6.1 启动向导并安装后台服务

# --install-daemon 参数会顺便把 Gateway 安装成一个系统服务，方便开机自启
openclaw onboard --install-daemon

6.2 向导步骤详解

下面是向导中每个问题的详细解释：

  • 步骤 1：Gateway 模式

    ? Gateway mode:
    ❯ Local (recommended for most users)
    Remote (connect to a running Gateway)

    • 选择 Local：这表示您将在本机上运行 OpenClaw 的核心服务（Gateway）。99% 的用户都应该选这个。
    • Remote 适用于高级场景，例如在笔记本上使用 openclaw CLI 来控制另一台服务器上已经运行的 Gateway。

  • 步骤 2：认证方式 (选择 AI 提供商)

    ? Auth provider:
    ❯ Anthropic (API key)
    OpenAI (API key)
    ...

    • 选择 Anthropic (API key) 或 OpenAI (API key)：根据您在 4.1 节 准备的 API Key 进行选择。
    • 接下来，向导会提示您粘贴 API Key。在终端中粘贴时，Key 的内容可能不会显示，这是正常的安全措施，直接回车即可。

  • 步骤 3：选择默认 AI 模型

    ? Default model:
    ❯ claude-3-sonnet-20240229
    claude-3-opus-20240229
    claude-3-haiku-20240307

    • Sonnet (推荐)：速度、智能和成本的完美平衡点，适用于绝大多数日常任务。
    • Opus：最强大的模型，但响应较慢且成本最高。适合处理复杂的编程或推理任务。
    • Haiku：最快的模型，成本最低，但能力相对较弱。适合需要快速响应的简单任务（如文本格式化）。

  • 步骤 4：配置聊天频道

    ? Channels: (Press <space> to select)
    ❯⬡ WhatsApp
    ⬡ Telegram
    ⬡ Discord

    • 使用空格键选择您想配置的频道（可以多选），然后按回车。
    • 向导会接着要求您输入所选频道的 Bot Token 等信息（WhatsApp 除外，它将在稍后通过扫码登录）。

  • 步骤 5：工作区设置

    ? Workspace directory:
    ❯ ~/.openclaw/workspace

    • 保持默认即可。这个目录是 AI 代理可以读写文件的“沙盒”或“工作空间”。所有通过聊天上传的文件、AI 生成的代码等都会存放在这里。

  • 步骤 6：安装后台服务

    ? Install daemon: (Y/n)

    • 输入 y 并回车。这会将 OpenClaw Gateway 设置为一个系统服务（在 Linux 上是 systemd，macOS 上是 launchd），能实现开机自启动和后台稳定运行，强烈推荐。

配置完成后，所有设置都将保存在 ~/.openclaw/openclaw.json 这个 JSON 文件中。您之后可以随时通过 openclaw configure 命令或直接用文本编辑器修改该文件。

七、启动与管理 Gateway

如果上一步中您选择安装了后台服务，Gateway 此时应该已经在后台运行了。

7.1 检查服务状态

openclaw gateway status

预期输出 (运行中):

● openclaw-gateway.service - OpenClaw Gateway
     Loaded: loaded (/etc/systemd/system/openclaw-gateway.service; enabled; ...)
     Active: active (running) since ...

7.2 手动管理 Gateway

如果您没有安装后台服务，或需要调试，可以使用以下命令：

  • 前台启动 (用于调试)：所有日志会直接打印在当前终端。

    # --verbose 参数会输出更详细的日志
openclaw gateway --port 18789 --verbose

  • 后台启动/停止/重启 (仅当安装了 daemon 后可用):

    openclaw gateway start
openclaw gateway stop
openclaw gateway restart

7.3 访问控制 UI

Gateway 启动后，会在本地开启一个 Web 服务，您可以通过浏览器访问它来监控状态。

如果您在配置中设置了 Gateway Token，访问 Control UI 时会要求您输入该 Token。

7.4 快速健康检查

运行以下命令，快速确认整个系统是否正常。

# 整体状态概览
openclaw status

# 深入健康检查，会检查 API 连接等
openclaw health

八、连接即时通讯平台

现在，我们将您选择的聊天工具连接到正在运行的 Gateway。

8.1 WhatsApp (通过扫描二维码)

  1. 在终端运行登录命令，它会生成一个二维码： 
    openclaw channels login
  2. 在手机上打开 WhatsApp。
  3. 进入 设置 -> 已关联设备 -> 关联设备。
  4. 扫描终端上显示的二维码。
  5. 扫描成功后，终端会显示 “WhatsApp Ready”。

8.2 Telegram (通过 Bot Token)

  1. 创建 Telegram Bot 并获取 Token：

    • 在 Telegram 中搜索 @BotFather 并开始对话。
    • 发送 /newbot 命令。
    • 按照提示为您的机器人命名（例如 MyClawBot）并设置一个唯一的用户名（必须以 bot 结尾，例如 my_claw_personal_bot）。
    • BotFather 会回复一条包含 HTTP API Token 的消息。这个 Token 就是您需要的，请复制它。

  2. 配置 Token 到 OpenClaw:

    # 这会打开一个交互式编辑器来修改 Telegram 频道的配置
openclaw configure --section channels.telegram

    将您复制的 Token 粘贴到 token 字段。

8.3 Discord (通过 Bot Token)

过程与 Telegram 类似：

  1. 访问 Discord Developer Portal。
  2. 创建一个新的 Application。
  3. 进入 Bot 标签页，点击 Add Bot。
  4. 点击 Reset Token 来生成并查看您的 Bot Token。复制它。
  5. 进入 OAuth2 -> URL Generator，勾选 bot 和 applications.commands 权限，然后在下方 Bot Permissions 中给予必要的权限（如 Send Messages, Read Message History 等）。
  6. 复制生成的 URL，在浏览器中打开，将机器人邀请到您的服务器。
  7. 配置 Token: 
    openclaw configure --section channels.discord

8.4 查看所有频道状态

使用此命令确认您的频道是否都已成功连接到 Gateway。

# --probe 会尝试向每个频道发送一个探测信号，更准确
openclaw channels status --probe

九、DM 安全配对机制

这是一个非常重要的安全特性！ 为了防止任何人都能通过您的机器人来控制您的电脑，OpenClaw 默认启用了私聊（DM）配对机制。

9.1 工作原理

当一个未知的用户（即不在白名单中的用户）第一次向您的机器人发送私聊消息时：

  1. OpenClaw 不会处理这条消息。
  2. 它会向该用户回复一个简短的、唯一的配对码（例如 claw-xyz）。
  3. 同时，它会在后台记录下这个待批准的配对请求。
  4. 只有当您（管理员）在终端上手动批准了这个配对码后，该用户才能与您的机器人正常交互。

9.2 如何批准配对

  1. 查看待处理的配对请求：

    # 查看 Telegram 的待处理请求
openclaw pairing list telegram

    预期输出:

    Pending Pairings for telegram:
CODE         USER ID      NAME          DATE
claw-xyz     123456789    John Doe      ...

  2. 批准请求：

    # 使用上一步中看到的 CODE
openclaw pairing approve telegram claw-xyz

    批准后，让您的朋友再发一条消息，这次机器人就应该会响应了。

  3. 拒绝请求：

    openclaw pairing deny telegram <CODE>

9.3 配置配对策略

您可以在配置文件 (~/.openclaw/openclaw.json) 中为每个频道自定义安全策略。

{
  "channels": {
    "telegram": {
      // "pairing": 默认策略，需要手动批准
      // "allowAll": 危险！允许任何人交互
      // "denyAll": 拒绝所有私聊
      "dmPolicy": "pairing",
      // 白名单，这些用户 ID 无需配对即可直接使用
      "allowFrom": [
        123456789, // 您的 Telegram 用户 ID
        987654321  // 您信任的朋友的用户 ID
      ]
    }
  }
}

十、常用命令大全 (Cheatsheet)

掌握这些命令，您就能自如地管理 OpenClaw。

10.1 基础与诊断

openclaw --version          # 查看版本
openclaw --help             # 查看帮助
openclaw status             # 快速状态概览
openclaw status --all       # 完整诊断报告 (提交 issue 时非常有用)
openclaw health             # 深度健康检查 (API连通性等)
openclaw doctor             # 诊断常见配置问题
openclaw doctor --fix       # 尝试自动修复问题
openclaw logs --follow      # 实时查看日志

10.2 Gateway 管理

openclaw gateway start      # 后台启动
openclaw gateway stop       # 停止
openclaw gateway restart    # 重启
openclaw gateway status     # 查看服务状态
openclaw gateway --verbose  # 前台启动并输出详细日志

10.3 配置管理

openclaw configure          # 启动交互式配置向导
openclaw config get         # 查看完整配置 (JSON 格式)
openclaw config get channels.telegram # 查看特定部分
openclaw config set gateway.port 18889 # 设置单个值
openclaw config unset gateway.port    # 删除某个键
# 配置文件物理位置: ~/.openclaw/openclaw.json

10.4 频道与配对

openclaw channels login     # WhatsApp 扫码登录
openclaw channels logout    # 登出所有频道
openclaw channels status    # 查看所有频道状态
openclaw channels status --probe # 探测连接性
openclaw pairing list <channel>   # 列出待批准的配对请求
openclaw pairing approve <channel> <CODE> # 批准
openclaw pairing deny <channel> <CODE>    # 拒绝

10.5 模型管理

openclaw models list        # 查看所有可用的模型
openclaw models scan        # 扫描并更新可用模型列表
openclaw models set <model-id> # 设置默认模型, e.g., 'anthropic/claude-3-sonnet-20240229'
openclaw models probe <model-id> # 测试与特定模型的连接

10.6 消息与会话

# 从命令行发送消息
openclaw message send --target +15555550123 --message "Hello"

# 会话管理
openclaw sessions list      # 查看当前活跃的会话
openclaw sessions history <session-key> # 查看会话历史
openclaw sessions reset <session-key>   # 清除会话上下文

十一、日常维护与备份

让 OpenClaw 长期稳定运行，需要一些简单的日常维护。

11.1 定期检查

建议每周运行一次，确保一切正常。

openclaw status
openclaw health
openclaw doctor

11.2 日志管理

日志文件默认存储在 /tmp/openclaw/ 目录下。

# 实时跟踪日志
openclaw logs -f

# 查找包含 "error" 或 "failed" 的日志行
openclaw logs --limit 1000 | grep -iE "error|failed"

# 手动清理超过7天的旧日志
find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete

11.3 备份与恢复 (重要!)

您的配置和数据非常宝贵。请定期备份！

  • 创建备份脚本 backup_openclaw.sh:

    #!/bin/bash
BACKUP_DIR=~/openclaw_backups/$(date +%Y-%m-%d)
mkdir -p "$BACKUP_DIR"

echo "Backing up OpenClaw config to $BACKUP_DIR..."
cp ~/.openclaw/openclaw.json "$BACKUP_DIR/"
cp -r ~/.openclaw/agents "$BACKUP_DIR/"

echo "Backing up workspace..."
tar -czf "$BACKUP_DIR/workspace.tar.gz" -C ~/.openclaw workspace

echo "Backup complete!"

  • 运行备份: bash backup_openclaw.sh

  • 恢复:

    1. 停止 Gateway: openclaw gateway stop
    2. 从备份目录中将 openclaw.json, agents/ 目录和 workspace/ 目录恢复到 ~/.openclaw/。
    3. 重启 Gateway: openclaw gateway start

11.4 更新流程

# 1. 检查当前版本
openclaw --version

# 2. 优雅地停止 Gateway
openclaw gateway stop

# 3. 运行安装脚本进行更新
curl -fsSL https://openclaw.ai/install.sh | bash

# 4. 运行健康检查和修复
openclaw doctor --fix

# 5. 重新启动 Gateway
openclaw gateway start

# 6. 验证状态
openclaw status

十二、故障排除 (Troubleshooting)

遇到问题时，请遵循以下步骤。

12.1 快速诊断流程

  1. 运行完整诊断：openclaw status --all
  2. 查看实时日志：openclaw logs --follow，同时在聊天工具里触发一次操作，观察日志输出。
  3. 运行医生检查：openclaw doctor --fix

12.2 常见问题与解决方案

  • 问题 1：Gateway 无法启动

    • 诊断: openclaw gateway --verbose 查看详细错误。最常见的原因是端口被占用或网络问题。
    • 解决方案:
      1. 检查端口占用: sudo lsof -i :18789。如果被占用，要么杀死占用进程，要么用 openclaw config set gateway.port <新端口号> 换个端口。
      2. (国内用户) 检查代理设置是否正确。

  • 问题 2：频道无响应

    • 诊断:
      1. openclaw channels status --probe 检查连接状态。
      2. openclaw pairing list <channel> 检查是否是配对问题。
      3. openclaw logs -f | grep -i "channel" 查看相关日志。
    • 解决方案:
      1. 如果是配对问题，使用 openclaw pairing approve ... 批准。
      2. 如果是 WhatsApp，尝试重新登录: openclaw channels logout 然后 openclaw channels login。
      3. 检查 Bot Token 是否正确或已过期。

  • 问题 3：模型不可用或 API Key 错误

    • 诊断: openclaw models probe <model-id>
    • 解决方案:
      1. 重新配置认证: openclaw configure 并粘贴正确的 API Key。
      2. 检查您的 API 账户余额是否充足。

  • 问题 4：国内网络问题

    • 诊断: Gateway 启动时出现 timeout 或 unreachable 错误。
    • 解决方案: 必须使用代理。
      • 方法一 (命令行临时代理): 
        export HTTPS_PROXY="http://127.0.0.1:7890" # 替换为你的代理地址和端口
export HTTP_PROXY="http://127.0.0.1:7890"
openclaw gateway start
      • 方法二 (写入配置永久生效): 
        openclaw config set gateway.proxy.url "http://127.0.0.1:7890"
openclaw gateway restart

十三、安全加固 (!!! CRITICAL !!!)

⚠️ 重要警告：OpenClaw 赋予了 AI 访问您主机系统的能力。错误的配置会带来极高的安全风险，可能导致：

  • API Key 泄露。
  • 私人聊天记录和文件泄露。
  • 主机系统被完全控制。

请务必遵循以下安全措施！

13.1 运行安全审计

OpenClaw 内置了安全检查工具，请立即运行它。

# 运行标准审计
openclaw security audit

# 运行包含更多检查的深度审计
openclaw security audit --deep

13.2 核心安全措施

  1. 绑定到本地回环地址 (Loopback)
    确保 Gateway 只监听来自本机的连接，而不是局域网或公网。

    # 确认或设置绑定模式为 loopback
openclaw config set gateway.bind loopback
openclaw gateway restart

  2. 设置 Gateway 认证 Token
    为 Gateway 的 Web UI 和 API 设置一个强密码。

    # 生成一个随机的强 Token
# 在 Linux/macOS 上:
TOKEN=$(openssl rand -base64 32)
echo "Your new token is: $TOKEN"

# 设置 Token
openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "$TOKEN"

  3. 加固文件权限
    限制对敏感配置文件的访问权限。

    # 只有当前用户可以读写配置文件
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/agents/main/agent/auth-profiles.json

# 只有当前用户可以访问工作区
chmod 700 ~/.openclaw/workspace/

13.3 远程访问的安全方式 (绝不直接暴露端口！)

如果您需要在外网访问您的 OpenClaw，绝对不要将 Gateway 端口直接暴露在公网上。请使用以下安全隧道技术：

  1. Tailscale (强烈推荐)
    Tailscale 可以创建一个安全的私有网络，让您的设备（手机、笔记本、服务器）之间可以点对点加密通信，就像在同一个局域网一样，但无需公网 IP。

    • 在运行 OpenClaw 的机器和您的手机/笔记本上都安装并登录 Tailscale。
    • 配置 OpenClaw 监听 Tailscale 网络：openclaw config set gateway.bind tailnet。

  2. SSH 隧道
    如果您有一台具有公网 IP 的服务器，可以通过 SSH 端口转发来安全地访问。

    • 在您的本地机器上运行： 
      # 将远程服务器的 18789 端口转发到本地的 18789 端口
ssh -L 18789:127.0.0.1:18789 user@your-server-ip
    • 现在，访问本地的 http://127.0.0.1:18789 就等于访问了服务器上的 Gateway。

十四、从源码安装 (开发者模式)

如果您想为 OpenClaw 贡献代码或进行深度定制，可以从源码安装。

# 1. 克隆官方仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖 (推荐使用 pnpm)
pnpm install

# 3. 构建项目 (这会编译 TypeScript 等)
pnpm build

# 4. 现在，你可以通过 pnpm 运行 openclaw 命令了
pnpm openclaw onboard --install-daemon

# 5. 直接从源码运行 Gateway (用于开发和调试)
node dist/openclaw.mjs gateway --verbose

十五、FAQ 与资源

Q1: 需要多少内存？
A: 最低 2GB，强烈推荐 4GB 或更多。尤其是在使用大型模型和多个聊天频道时。

Q2: 支持哪些模型？
A: 主要支持 Anthropic (Claude) 和 OpenAI (GPT)。也支持 MiniMax, GLM, 以及通过 Ollama 部署的本地模型。运行 openclaw models list 查看完整支持列表。

Q3: 为什么我的第一条私聊消息没有回复？
A: 这是正常的安全配对机制。您需要让管理员在服务器上运行 openclaw pairing approve <channel> <CODE> 来批准您的聊天。详情请见 第九节。

Q4: 在国内无法使用怎么办？
A: 必须使用网络代理。请参考 12.2 节 中的“国内网络问题”部分进行配置。

Q5: Bun 运行时可以用吗？
A: 不推荐。目前 Bun 在与 WhatsApp 和 Telegram 的集成上存在已知的兼容性问题。请坚持使用 Node.js 22。

📚 资源链接

资源 链接
官方文档 https://docs.openclaw.ai/
GitHub 仓库 https://github.com/openclaw/openclaw
Releases https://github.com/openclaw/openclaw/releases
Moltcn 中文社区 https://www.moltcn.com/
Anthropic API https://console.anthropic.com/
OpenAI API https://platform.openai.com/

最后更新: 2026年2月2日

# 人工智能 # windows
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

【拥抱AI】OpenClaw - 2026年GitHub最火的开源项目

avatar 2048 AI社区
cover

AI普及时代，一人公司的风口已至：普通人的技术赋能创业指南

avatar 2048 AI社区

AI小说生成器

然而，借助现代AI技术和开发工具，我们在短短30分钟内就完成了从概念到成品的全过程。未来的文学世界，将是人类智慧与AI技术完美融合的舞台。那些善于利用AI工具的作家，将拥有更大的创作优势。这是一款基于人工智能技术的小说创作辅助工具，可以帮助作者快速生成小说大纲、章节内容，并提供流畅的阅读体验。系统内置了先进的上下文管理机制，确保在长篇创作过程中不会丢失关键信息，保持情节的连贯性。即使是写作新手，也

avatar 2048 AI社区