为什么选择在国内环境自建 OpenClaw

对于开发者和极客玩家而言，拥有一个完全私有化、数据不出域且能深度融入国内办公生态的 AI 助手，早已不再是“锦上添花”，而是提升工作流的刚需。OpenClaw 作为目前开源社区中极具活力的 AI Agent 运行时框架，其核心价值在于它不仅仅是一个调用大模型 API 的脚本，而是一套完整的“操作系统”。它通过 Gateway 网关架构实现了多通道消息的统一接入，支持模块化技能扩展，并原生适配了飞书、钉钉等国内主流 IM 平台。

然而，直接照搬官方文档在国内网络环境下往往会遭遇“水土不服”：GitHub 克隆超时、npm 依赖安装失败、海外模型接口连通性差等问题层出不穷。本文将剥离繁琐的理论铺垫，直接切入实战，手把手带你在一台本地电脑上，从 Node.js 环境搭建开始，解决网络加速痛点，对接国产大模型，最终跑通一个属于你自己的、数据完全本地化的智能代理。

基石构建：Node.js 环境与网络加速策略

OpenClaw 基于 Node.js 构建，环境的稳定性直接决定了后续部署的顺畅度。鉴于 OpenClaw 对最新特性的依赖，强烈建议使用 Node.js 22 LTS 版本。

1. 使用 nvm 管理 Node 版本

为了避免系统自带 Node 版本冲突，推荐使用 nvm (Node Version Manager) 进行版本管理。在终端执行以下命令安装 nvm（以 Linux/macOS 为例，Windows 用户可下载 nvm-windows 安装包）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后重启终端，加载 nvm 并安装指定版本：

source ~/.bashrc  # 或 source ~/.zshrc
nvm install 22
nvm use 22
node -v  # 确认输出 v22.x.x

2. 突破 npm 下载瓶颈

在国内直接访问 npm 官方源往往速度极慢甚至超时。最稳妥的方案是切换至国内镜像源。你可以临时指定或使用 nrm 工具永久切换。

临时切换（推荐用于单次安装）：

npm install --registry=https://registry.npmmirror.com

永久切换：

npm config set registry https://registry.npmmirror.com
npm config get registry # 验证是否切换成功

此外，针对 GitHub 资源访问慢的问题（如克隆源码时），建议在 hosts 文件中添加 GitHub 相关域名的加速 IP，或者使用合法的代码托管镜像站进行源码克隆。这一步是后续顺利安装 OpenClaw 的前提，切勿跳过。

双轨部署：Docker 容器化与源码安装详解

根据你的需求场景，OpenClaw 提供两种主流部署方式。追求极致隔离和简便运维的选择 Docker；需要深度定制代码、调试底层逻辑的选择源码安装。

方案 A：Docker 一键部署（推荐生产环境）

Docker 方式屏蔽了环境差异，适合快速启动。确保已安装 Docker Engine 和 Docker Compose。

  1. 创建项目目录

    mkdir openclaw-deploy && cd openclaw-deploy

  2. 编写 docker-compose.yml
    新建 docker-compose.yml 文件，内容如下：

    version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: always
    ports:
      - "18789:18789"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - NODE_ENV=production
      # 后续在此处配置模型 Key 等环境变量

  3. 启动服务

    docker compose up -d

    启动后，可通过 docker logs -f openclaw-gateway 查看实时日志，确保 Gateway 服务正常监听 18789 端口。

方案 B：源码安装（适合开发者调试）

如果你需要修改核心逻辑或开发自定义 Skill，源码安装是必经之路。

  1. 克隆仓库
    利用之前配置好的加速手段克隆代码：

    git clone https://github.com/OpenClawAI/openclaw.git
cd openclaw

  2. 安装依赖

    npm install --registry=https://registry.npmmirror.com

  3. 初始化配置
    复制示例配置文件并根据实际需求修改：

    cp .env.example .env

    此时不要急于启动，我们需要先解决最核心的“大脑”连接问题——国产大模型的对接。

注入灵魂：对接 DeepSeek 与通义千问

OpenClaw 本身不具备推理能力，它需要接入 LLM 作为“大脑”。考虑到国内网络环境的特殊性，直接配置 OpenAI 接口往往不稳定且延迟高。接入国产大模型不仅速度快，而且合规可控。OpenClaw 支持标准的 OpenAI SDK 协议，这意味着我们可以轻松接入 DeepSeek、通义千问等模型。

1. 获取 API Key

  • DeepSeek: 访问 DeepSeek 开放平台，注册账号并创建 API Key。DeepSeek-V3 或 V2.5 在代码逻辑和长文本处理上表现优异，性价比极高。
  • 通义千问: 登录阿里云百炼控制台，开通 Qwen-Max 或 Qwen-Plus 服务，获取 API Key。

2. 配置模型路由

编辑项目根目录下的 .env 文件（Docker 用户则在 docker-compose.yml 的 environment 中配置）。OpenClaw 允许通过环境变量动态切换模型提供商。

以配置 DeepSeek 为例：

# 模型基础 URL，注意指向国内节点
LLM_BASE_URL=https://api.deepseek.com
# 你的 API Key
LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# 模型名称，需与服务商一致
LLM_MODEL=deepseek-chat
# 上下文窗口限制，根据模型实际能力设置
LLM_CONTEXT_WINDOW=32000

若使用通义千问，只需调整 LLM_BASE_URL 为阿里云 DashScope 的兼容地址（或直接使用阿里云提供的 OpenAI 兼容接口地址），并将 LLM_MODEL 改为 qwen-max。

关键点：OpenClaw 的 Prompt 编译机制非常灵活，它会根据你配置的模型能力动态调整系统提示词。国产模型通常对中文指令遵循度更高，在配置完成后，建议先在终端进行一次简单的对话测试，确保链路畅通。

打通任督二脉：飞书与钉钉渠道集成

有了“大脑”，还需要“耳朵”和“嘴巴”。OpenClaw 的强大之处在于其原生的 IM 集成能力。不同于国外框架需要复杂的 Webhook 中转，OpenClaw 内置了针对飞书和钉钉的深度适配器。

飞书（Feishu）集成步骤

  1. 创建企业应用
    登录飞书开放平台，进入“应用管理” -> “自建应用”。创建一个新应用，命名为"OpenClaw Assistant"。

  2. 配置权限
    在“权限管理”中，务必勾选以下权限：

    • im:message (发送与接收消息)
    • im:chat (群组管理)
    • contact:employee (可选，用于识别用户身份)

  3. 获取凭证
    在“凭证与基础信息”页面，记录 App ID 和 App Secret。

  4. 配置 OpenClaw
    在 OpenClaw 的配置目录（通常是 config/channels/feishu.json 或通过环境变量）填入凭证：

    {
  "appId": "cli_xxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxx",
  "port": 8080,
  "path": "/openclaw/feishu"
}

  5. 事件订阅与回调
    这是最关键的一步。飞书需要将消息推送给 OpenClaw。由于你的 OpenClaw 可能运行在本地，此时需要用到内网穿透（见下一节）。将内网穿透生成的公网地址 + 路径（如 https://xxx.ngrok.io/openclaw/feishu）填入飞书后台的“事件订阅” -> “请求地址”中。订阅 receive_message 事件。

钉钉（DingTalk）集成简述

钉钉流程类似，需在钉钉开放平台创建应用，获取 Client Key 和 Client Secret。钉钉的特色在于支持卡片消息交互，OpenClaw 的 Skill 系统可以解析这些卡片回调，实现更丰富的操作界面（如审批按钮、表单填写）。配置完成后，重启 Gateway 服务，即可在对应的 IM 客户端中看到你的 AI 助手上线。

破局内网：内网穿透与 Gateway 调优

国内家庭宽带或公司内网通常没有固定公网 IP，这导致 IM 厂商无法将消息推送到你的本地服务。解决这一问题的标准方案是使用内网穿透工具。

内网穿透实战

推荐使用 Cloudflare Tunnel 或 Ngrok。以 Ngrok 为例：

  1. 安装 ngrok 并认证。
  2. 启动隧道，映射 OpenClaw 的回调端口（假设飞书配置的是 8080）： 
    ngrok http 8080
  3. 复制生成的 https 域名，回填到飞书/钉钉的事件订阅配置中。

注意：为了安全，建议在 Gateway 层配置签名验证。OpenClaw 支持校验 IM 平台发送的请求签名，防止恶意伪造请求。在配置文件中开启 verify_signature: true 并填入对应的验证 Token。

Gateway 服务调优

OpenClaw 的 Gateway 是整个系统的流量入口。在高并发场景下（如多人同时在群聊中使用），可能需要调整 WebSocket 的心跳检测和最大连接数。

编辑 gateway.config.js（或对应配置文件）：

module.exports = {
  ws: {
    pingInterval: 30000, // 心跳间隔，防止连接假死
    maxPayload: 1048576, // 最大负载 1MB
  },
  rateLimit: {
    windowMs: 60000,
    max: 100 // 每分钟每 IP 最大请求数，防刷
  }
};

对于本地个人使用，默认配置通常足够；若部署在团队服务器，适当调低 max 值可增强稳定性。

避坑指南：常见报错与排查思路

在从零搭建的过程中，以下几个问题是高频出现的“拦路虎”，掌握排查思路能让你事半功倍。

1. 环境变量未生效

现象：启动后日志提示 LLM_API_KEY is missing 或模型调用返回 401。
排查：

  • 检查 .env 文件是否与启动脚本在同一目录。
  • 若是 Docker 部署，确认 docker-compose.yml 中的 environment 字段是否正确覆盖，或使用 docker exec -it openclaw-gateway env 进入容器内部查看环境变量。
  • 注意 key 前后是否有多余空格。

2. 端口占用冲突

现象：启动失败，报错 EADDRINUSE: address already in use :::18789。
排查：

  • 使用 lsof -i :18789 (Mac/Linux) 或 netstat -ano | findstr 18789 (Windows) 查找占用进程。
  • 通常是上一次非正常退出的 Node 进程未清理，杀掉对应 PID 即可。
  • 或者在配置文件中修改 Gateway 监听端口，避免冲突。

3. 回调地址不可达

现象：IM 软件显示“回调验证失败”或收不到消息。
排查：

  • 确认内网穿透工具是否在线，生成的 URL 是否变更（免费版的 Ngrok 每次重启 URL 会变，建议使用固定域名方案）。
  • 检查防火墙设置，确保本地端口对 localhost 开放。
  • 查看 OpenClaw 日志，确认是否有收到 HTTP POST 请求的记录。若收到但处理失败，可能是签名验证未通过。

4. 模型响应超时

现象：发送消息后长时间无反应，最终报错 Timeout。
排查：

  • 检查国内大模型的服务状态。
  • 调整 .env 中的 REQUEST_TIMEOUT 参数，国产模型偶尔会有波动，适当延长超时时间（如设为 60s）。
  • 确认网络出口是否正常，虽然是国内模型，但若服务器位于特殊网络环境，仍需检查 DNS 解析。

当你在 IM 窗口中发出第一条指令，并看到 OpenClaw 准确调用技能、返回结构化结果时，这套完全由你掌控的本地 AI 基础设施便正式运转起来了。它不仅是一个工具，更是理解 AI Agent 架构、探索自动化边界的最佳实验田。随着后续对 Skill 市场的深入挖掘，你可以为其赋予更多个性化能力，让它真正成为懂你工作流的得力助手。

Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

Kiro比Claude省21倍！实测对比惊人

avatar AI Agent技术社区
cover

用 ChatGPT 5.5 辅助 Java 后端排查慢接口：从日志到修复方案的实践

avatar AI Agent技术社区
cover

土区ChatGPT订阅价格暴涨，薅羊毛时代结束！

avatar AI Agent技术社区