从零搭建个人 AI 助手,OpenClaw 在国内环境的部署全流程

为什么选择在国内环境自建 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 ~/.zshrcnvm install 22nvm use 22node -v  # 确认输出 v22.x.x

2. 突破 npm 下载瓶颈

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

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

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

永久切换：

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

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

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

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

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

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

创建项目目录

mkdir openclaw-deploy && cd openclaw-deploy

编写 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 等环境变量

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

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

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

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

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

安装依赖

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

初始化配置 复制示例配置文件并根据实际需求修改：
```
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 KeyLLM_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）集成步骤

创建企业应用 登录飞书开放平台，进入“应用管理” -> “自建应用”。创建一个新应用，命名为"OpenClaw Assistant"。
配置权限 在“权限管理”中，务必勾选以下权限：

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

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

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

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

事件订阅与回调 这是最关键的一步。飞书需要将消息推送给 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 为例：

安装 ngrok 并认证。
启动隧道，映射 OpenClaw 的回调端口（假设飞书配置的是 8080）：
```
ngrok http 8080
```

复制生成的 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 市场的深入挖掘，你可以为其赋予更多个性化能力，让它真正成为懂你工作流的得力助手。