OpenClaw-CN 完整安装教程与避坑指南（国内镜像加速版）

安全菜鸟2026-03-19 17:15

最后更新 ：2026 年 3 月 | 适用版本 ：OpenClaw-CN 0.1.8-fix.3+
官方国内社区 ：https://clawd.org.cn/install/
国内镜像加速安装 ：curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry https://registry.npmmirror.com

目录

plain 复制代码 
前言：什么是 OpenClaw？
环境准备（系统要求/依赖检查）
快速安装（国内镜像加速命令）
基础配置向导（网关 / Web / 模型）
常见问题与避坑指南（重点！）
高级配置：自定义模型提供商（以 GitCode AI 为例）
验证与测试：确认一切正常工作
完整卸载教程（干净移除）
附录：常用命令速查表

一、前言：什么是 OpenClaw？

OpenClaw-CN 是一个开源的 AI 助手框架，支持：

  • 多模型接入（OpenAI / Claude / 通义千问 / 本地 Ollama 等）
  • Web 搜索与网页抓取能力
  • 本地 Web 控制界面，可视化配置
  • 灵活的认证机制（Token / Password / 无认证）
  • 插件系统，可扩展工具链

适合开发者、技术爱好者搭建私有化、可定制的 AI 助手。

二、环境准备

系统要求

组件 最低要求 推荐
操作系统 Linux / macOS / WSL2 Ubuntu 22.04+ / macOS 12+
Node.js v18+ v20 LTS
npm v9+ v10+
内存 2GB 4GB+
磁盘 500MB 2GB+（含模型缓存）

检查环境

bash 复制代码 
# 检查 Node.js 和 npm
node -v    # 应 >= v18
npm -v     # 应 >= v9

# 如未安装，使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

安装 jq（配置编辑必备）

bash 复制代码 
# Ubuntu/Debian
sudo apt update && sudo apt install -y jq curl

# CentOS/RHEL
sudo yum install -y jq curl

# macOS
brew install jq curl

三、快速安装（国内镜像加速）

一键安装命令（推荐）

bash 复制代码 
# 使用国内 npm 镜像加速安装
curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry https://registry.npmmirror.com

安装过程预期输出

plain 复制代码 
OpenClaw-CN Installer
→ Checking environment...
→ Installing openclaw-cn package...
→ Creating config directory: ~/.openclaw
→ Installation complete!

下一步：
  1. 运行: openclaw-cn configure --section gateway
  2. 运行: openclaw-cn configure --section web  
  3. 运行: openclaw-cn configure --section model

安装失败？试试这些

错误现象 解决方案
Permission denied 不要用 sudo 运行安装脚本，确保当前用户有 ~/.openclaw 写入权限
npm ERR! registry timeout 确认 --registry 参数生效，或手动设置：npm config set registry https://registry.npmmirror.com
node: command not found 先安装 Node.js，参考上文环境准备
脚本下载失败 检查网络，或手动下载：curl -O https://clawd.org.cn/install.sh

四、基础配置向导

安装完成后，按顺序配置三个核心模块：

4.1 配置网关（gateway）

bash 复制代码 
openclaw-cn configure --section gateway

推荐配置选项：

配置项 推荐值 说明
网关运行位置 本地（此设备） 单机使用选此项
Gateway port 18789（默认） 除非端口冲突，否则不改
Gateway bind mode Loopback (Local only) 仅 127.0.0.1 可访问，最安全
Gateway auth Off (loopback only) 本地测试可选 off，生产环境建议 token
Tailscale exposure Off 无需远程访问则关闭

避坑提示：

  • 如果选 token 认证，启动前必须设置 export OPENCLAW_GATEWAY_TOKEN="your-token"
  • auth.mode 的有效值是 "off" / "token" / "password"，**不是 **"none"！
bash 复制代码 
openclaw-cn configure --section web

推荐配置：

配置项 推荐值 说明
启用 web_search Yes 让助手能在线搜索
Brave API Key 留空（用环境变量） 获取密钥：https://brave.com/search/api/
启用 web_fetch Yes 允许抓取网页内容

设置 Brave API Key（二选一）：

bash 复制代码 
# 方式1：临时生效（当前终端）
export BRAVE_API_KEY="your-brave-api-key"

# 方式2：永久生效（推荐）
echo 'export BRAVE_API_KEY="your-brave-api-key"' >> ~/.bashrc
source ~/.bashrc

4.3 配置模型提供商（model）

bash 复制代码 
openclaw-cn configure --section model

国内用户推荐选择：

plain 复制代码 
○ 自定义模型 (兼容 OpenAI/Anthropic)  ← 选这个！

后续配置示例（以 GitCode AI 为例）：

配置项 填写内容
Select protocol OpenAI Compatible (Default)
Provider ID gitcode
Base URL https://api-ai.gitcode.com/v1
API Key sk-你的-gitcode-密钥
Model ID（可添加多个） qwen-turbo → qwen-plus → qwen-max
Default primary model gitcode/qwen-turbo

其他国内提供商配置参考：

  • 月之暗面（Moonshot）：https://api.moonshot.cn/v1
  • MiniMax：https://api.minimaxi.com/v1
  • 阿里云百炼：https://dashscope.aliyuncs.com/compatible-mode/v1

五、常见问题与避坑指南（重点！）

问题 1：gateway.auth.mode: Invalid input

现象：

plain 复制代码 
Invalid config at ~/.openclaw/openclaw.json:
- gateway.auth.mode: Invalid input

原因 ：配置向导或手动编辑时，将 auth.mode 设为 "none"，但有效值是 "off" / "token" / "password"。

解决方案：

bash 复制代码 
# 方法1：用 doctor 自动修复
openclaw-cn doctor --fix

# 方法2：手动修正
jq '.gateway.auth.mode = "off"' ~/.openclaw/openclaw.json > t.json && mv t.json ~/.openclaw/openclaw.json

问题 2：网关启动失败，提示 unauthorized: gateway token missing

现象：

plain 复制代码 
disconnected (1008): unauthorized: gateway token missing

原因 ：网关配置为 token 认证，但启动时未提供 token。

解决方案：

bash 复制代码 
# 1. 查看/生成 token
TOKEN=$(jq -r '.gateway.auth.token // empty' ~/.openclaw/openclaw.json)
if [ -z "$TOKEN" ]; then
  TOKEN="oc-$(openssl rand -hex 16)"
  jq --arg t "$TOKEN" '.gateway.auth.token = $t' \
     ~/.openclaw/openclaw.json > t.json && mv t.json ~/.openclaw/openclaw.json
fi

# 2. 设置环境变量并启动
export OPENCLAW_GATEWAY_TOKEN="$TOKEN"
openclaw-cn gateway

# 3. 生成带 token 的登录链接
openclaw-cn dashboard --no-open
# 复制输出的 URL 到浏览器打开

问题 3：模型加载不出来，jq '.models' 返回 null

现象：配置向导跳过了模型配置，或配置未正确写入。

解决方案：

bash 复制代码 
# 1. 重新配置模型
openclaw-cn configure --section model

# 2. 或手动注入配置（以 GitCode 为例）
GITCODE_KEY="sk-你的密钥"
jq --arg key "$GITCODE_KEY" '
  .models.providers.gitcode = {
    baseUrl: "https://api-ai.gitcode.com/v1",
    apiKey: $key,
    api: "openai-completions",
    models: [{id:"qwen-turbo",name:"Qwen-Turbo"}]
  } |
  .agents.defaults.model.primary = "gitcode/qwen-turbo"
' ~/.openclaw/openclaw.json > t.json && mv t.json ~/.openclaw/openclaw.json

# 3. 重启网关
pkill -f "openclaw-cn gateway" 2>/dev/null
export OPENCLAW_GATEWAY_TOKEN=$(jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json)
openclaw-cn gateway

问题 4：BRAVE_API_KEY not found，搜索功能不可用

原因 ：启用了 web_search 但未设置 Brave API 密钥。

解决方案：

bash 复制代码 
# 1. 获取密钥：https://brave.com/search/api/
# 2. 设置环境变量
export BRAVE_API_KEY="your-key-here"

# 3. 永久生效（加入 ~/.bashrc）
echo 'export BRAVE_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

# 4. 重启网关使环境变量生效（如用 systemd）
systemctl --user restart openclaw-gateway.service

问题 5：端口 18789 被占用，EADDRINUSE

现象：

plain 复制代码 
Error: listen EADDRINUSE: address already in use 127.0.0.1:18789

解决方案：

bash 复制代码 
# 1. 查找占用进程
lsof -i :18789
# 或
ss -tlnp | grep 18789

# 2. 终止进程（谨慎操作）
kill -9 <PID>

# 3. 或修改网关端口（编辑配置）
jq '.gateway.port = 18790' ~/.openclaw/openclaw.json > t.json && mv t.json ~/.openclaw/openclaw.json

问题 6：systemd 服务启动失败

现象 ：systemctl --user start openclaw-gateway.service 报错

排查步骤：

bash 复制代码 
# 1. 查看服务状态
systemctl --user status openclaw-gateway.service

# 2. 查看详细日志
journalctl --user -u openclaw-gateway.service -n 50 -f

# 3. 常见问题：
#    - 环境变量未传递：编辑 ~/.config/systemd/user/openclaw-gateway.service.d/env.conf
#    - 权限问题：确保用户已启用 linger: loginctl enable-linger $(whoami)
#    - 配置错误：先手动前台运行确认配置有效

问题 7：国内网络访问海外 API 超时

现象：使用 OpenAI / Claude 等海外提供商时连接超时

解决方案：

bash 复制代码 
# 方案1：改用国内提供商（推荐）
# 在模型配置中选择 Moonshot / MiniMax / GitCode / 阿里云百炼等

# 方案2：配置代理（如已有）
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

# 方案3：在配置文件中设置代理（部分提供商支持）
jq '.models.providers.openai.proxy = "http://127.0.0.1:7890"' \
   ~/.openclaw/openclaw.json > t.json && mv t.json ~/.openclaw/openclaw.json

六、高级配置：自定义模型提供商（以 GitCode AI 为例）

为什么需要自定义？

  • GitCode AI、Moonshot、MiniMax 等国内提供商使用 OpenAI 兼容接口
  • 但不在预置列表中，需用「自定义模型」方式配置

完整配置步骤

bash 复制代码 
# 1. 启动配置向导
openclaw-cn configure --section model

# 2. 选择: ○ 自定义模型 (兼容 OpenAI/Anthropic)

# 3. 依次填写：
#    - Protocol: OpenAI Compatible
#    - Provider ID: gitcode
#    - Base URL: https://api-ai.gitcode.com/v1
#    - API Key: sk-你的密钥
#    - Model IDs: qwen-turbo, qwen-plus, qwen-max（逐个添加）
#    - Default model: gitcode/qwen-turbo

# 4. 保存退出，重启网关
pkill -f "openclaw-cn gateway" 2>/dev/null
export OPENCLAW_GATEWAY_TOKEN=$(jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json)
openclaw-cn gateway

验证配置

bash 复制代码 
# 检查配置写入
jq '{
  provider: .models.providers.gitcode.baseUrl,
  models: [.models.providers.gitcode.models[].id],
  default: .agents.defaults.model.primary
}' ~/.openclaw/openclaw.json

# 控制界面查看模型状态
# 浏览器: http://127.0.0.1:18789/?token=xxx
# 发送: /models  应看到 gitcode 下的模型为 Ready

# 命令行测试
openclaw-cn chat "你好，请用一句话介绍你自己"

七、验证与测试：确认一切正常工作

快速验证脚本

bash 复制代码 
#!/bin/bash
# 保存为 ~/test-openclaw.sh

echo "OpenClaw 健康检查"

# 1. 检查配置文件
if [ ! -f ~/.openclaw/openclaw.json ]; then
  echo "配置文件不存在"
  exit 1
fi
echo "配置文件存在"

# 2. 检查模型配置
if jq -e '.models.providers | length > 0' ~/.openclaw/openclaw.json > /dev/null; then
  echo "已配置模型提供商:"
  jq -r '.models.providers | keys[]' ~/.openclaw/openclaw.json | sed 's/^/   - /'
else
  echo "未配置模型，运行: openclaw-cn configure --section model"
fi

# 3. 检查网关进程
if pgrep -f "openclaw-cn gateway" > /dev/null; then
  echo "网关进程运行中"
else
  echo "网关未运行，启动: openclaw-cn gateway"
fi

# 4. 测试端口
if curl -s http://127.0.0.1:18789/ > /dev/null 2>&1; then
  echo "网关端口 18789 可访问"
  echo "控制界面: http://127.0.0.1:18789/"
else
  echo "无法访问网关端口"
fi

# 5. 测试对话（如果 openclaw-cn chat 可用）
if command -v openclaw-cn > /dev/null; then
  echo "测试对话 (5 秒超时)..."
  timeout 5 openclaw-cn chat "ping" 2>/dev/null && echo "对话测试成功" || echo"  对话测试超时/失败"
fi

echo ""
echo "提示：配置修改后记得重启网关！"

执行：bash ~/test-openclaw.sh

手动测试清单

bash 复制代码 
# 1. 基础对话
openclaw-cn chat "你好"

# 2. 搜索功能（需配置 Brave API）
openclaw-cn chat "搜索今天的科技新闻"

# 3. 查看模型列表（控制界面）
# 发送: /models

# 4. 查看系统状态
openclaw-cn chat "/status"

# 5. 重置对话上下文
openclaw-cn chat "/reset"

八、完整卸载教程（干净移除）

警告 ：以下操作将永久删除所有配置、数据和缓存，请提前备份重要文件！

步骤 1：停止所有 OpenClaw 进程

bash 复制代码 
# 停止前台运行的网关
pkill -f "openclaw-cn gateway"

# 停止 systemd 服务（如果已安装）
systemctl --user stop openclaw-gateway.service
systemctl --user disable openclaw-gateway.service  # 取消开机自启

步骤 2：卸载 npm 包

bash 复制代码 
# 全局卸载 openclaw-cn
npm uninstall -g openclaw-cn

# 验证是否卸载成功
openclaw-cn --version  # 应提示 command not found

步骤 3：删除配置和数据目录

bash 复制代码 
# 备份配置（可选但推荐）
mkdir -p ~/openclaw-backup-$(date +%Y%m%d)
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)/

# 删除主配置目录
rm -rf ~/.openclaw

# 删除 systemd 服务文件（如果存在）
rm -f ~/.config/systemd/user/openclaw-gateway.service
rm -rf ~/.config/systemd/user/openclaw-gateway.service.d/

# 重载 systemd
systemctl --user daemon-reload

步骤 4：清理环境变量（可选）

bash 复制代码 
# 编辑 ~/.bashrc 或 ~/.zshrc，删除以下行（如果存在）：
# export OPENCLAW_GATEWAY_TOKEN="xxx"
# export BRAVE_API_KEY="xxx"
# export OPENAI_API_KEY="xxx"

# 使修改生效
source ~/.bashrc  # 或 source ~/.zshrc

步骤 5：验证卸载

bash 复制代码 
# 1. 确认命令不可用
openclaw-cn --version  # 应报错

# 2. 确认目录已删除
ls -la ~/.openclaw  # 应提示 No such file

# 3. 确认端口已释放
ss -tlnp | grep 18789  # 应无输出

# 4. 确认进程已终止
ps aux | grep openclaw | grep -v grep  # 应无输出

（可选）步骤 6：清理 npm 缓存

bash 复制代码 
# 清理 openclaw 相关缓存
npm cache clean --force
# 或精准清理
npm cache ls | grep openclaw | xargs -r npm cache clean --force

九、附录：常用命令速查表

配置管理

bash 复制代码 
# 配置各模块
openclaw-cn configure --section gateway   # 网关配置
openclaw-cn configure --section web       # Web 功能配置
openclaw-cn configure --section model     # 模型配置

# 查看当前配置
jq '.' ~/.openclaw/openclaw.json          # 完整配置
jq '.gateway' ~/.openclaw/openclaw.json   # 仅网关部分
jq '.models' ~/.openclaw/openclaw.json    # 仅模型部分

网关控制

bash 复制代码 
# 启动/停止/重启
openclaw-cn gateway                       # 前台启动
openclaw-cn gateway restart              # 重启（如果支持）
pkill -f "openclaw-cn gateway"           # 强制停止

# systemd 服务管理
systemctl --user start openclaw-gateway.service
systemctl --user stop openclaw-gateway.service
systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -f  # 查看日志

认证与令牌

bash 复制代码 
# 查看/生成网关 token
jq -r '.gateway.auth.token' ~/.openclaw/openclaw.json
openclaw-cn doctor --generate-gateway-token

# 生成带 token 的登录链接
openclaw-cn dashboard --no-open

# 设置环境变量
export OPENCLAW_GATEWAY_TOKEN="your-token"
export BRAVE_API_KEY="your-brave-key"

测试与调试

bash 复制代码 
# 测试对话
openclaw-cn chat "你好"

# 检查配置有效性
openclaw-cn doctor
openclaw-cn doctor --fix          # 自动修复配置

# 查看模型列表（控制界面命令）
# 在 Web UI 发送: /models

# 重置对话
# 在对话中输入: /reset

卸载相关

bash 复制代码 
# 卸载包
npm uninstall -g openclaw-cn

# 删除配置
rm -rf ~/.openclaw

# 清理 systemd
systemctl --user disable --now openclaw-gateway.service
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

最后的话

恭喜你完成 OpenClaw-CN 的完整配置！

现在你的助手已经可以：

plain 复制代码 
理解中文，进行自然对话
调用 GitCode/Moonshot 等国内模型
在线搜索（配置 Brave API 后）
读取工作空间配置，个性化响应
通过 Web 界面可视化管理

进阶建议

  1. 备份配置 ：定期 cp -r ~/.openclaw ~/backup/openclaw-$(date +%F)
  2. 监控日志 ：journalctl --user -u openclaw-gateway.service -f
  3. 更新版本 ：关注 https://clawd.org.cn 获取最新版
  4. 参与社区 ：遇到问题先在 国内社区 搜索，或提交 Issue

其他问题

  1. 先运行 openclaw-cn doctor 自动诊断
  2. 查看日志：journalctl --user -u openclaw-gateway.service -n 50
  3. 搜索 https://clawd.org.cn 的 FAQ
  4. 在社区提问时附上：
    • openclaw-cn --version 输出
    • jq '.gateway,.models' ~/.openclaw/openclaw.json 配置片段
    • 相关错误日志
相关推荐
小慧教你用AI1 小时前
OpenClaw的多Agent架构设计，揭示其实现原理
人工智能
FluxMelodySun2 小时前
机器学习(二十三) 密度聚类与层次聚类
人工智能·机器学习·聚类
奋斗中的小猩猩2 小时前
Test Case Generator / AI 测试用例生成器（多Agent组合，效果可观）
人工智能·测试用例
总有刁民想爱朕ha2 小时前
OpenCV 图像操作入门：从零开始玩转计算机视觉
人工智能·opencv·计算机视觉
前进的李工2 小时前
LangChain使用之Model IO（提示词模版之PromptTemplate）
开发语言·人工智能·python·langchain
Techblog of HaoWANG2 小时前
目标检测与跟踪（9）-- Jetson Xavier NX GPIO控制3D结构光C与Python双版本实现（中）
c语言·人工智能·目标检测
掘金一周2 小时前
吃龙虾🦞咯！万字拆解OpenClaw的架构与设计 | 掘金一周 3.19
前端·人工智能·后端
段小二2 小时前
Chat Memory 实战：让 LLM 记住多轮对话（Java 架构师的 AI 工程笔记 05）
人工智能
东离与糖宝2 小时前
Java 21 虚拟线程与 AI 推理结合的最新实践
java·人工智能
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04UV安装并设置国内源05AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南06Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services07OpenClaw Control UI安全上下文访问配置08小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）09本地部署 OpenClaw + DeepSeek-R1 完全指南10OpenClaw macOS 完整安装与本地模型配置教程（实战版）