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

最后更新：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

目录

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

一、前言：什么是 OpenClaw？

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

·多模型接入（OpenAI / Claude / 通义千问 / 本地 Ollama 等）

·Web 搜索与网页抓取能力

·本地 Web 控制界面，可视化配置

·灵活的认证机制（Token / Password / 无认证）

·插件系统，可扩展工具链

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

二、环境准备

系统要求

检查环境

# 检查 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（配置编辑必备）

# Ubuntu/Debian            sudo apt update && sudo apt install -y jq curl            # CentOS/RHEL            sudo yum install -y jq curl            # macOS            brew install jq curl            

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

一键安装命令（推荐）

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

安装过程预期输出

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 web3. 运行: openclaw-cn configure --section model            

安装失败？试试这些

四、基础配置向导

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

4.1 配置网关（gateway）

openclaw-cn configure --section gateway            

推荐配置选项：

避坑提示： 

·如果选 token 认证，启动前必须设置 export OPENCLAW_GATEWAY_TOKEN="your-token"

·auth.mode 的有效值是 "off" / "token" / "password"，**不是 **"none"！

4.2 配置 Web 功能（web_search / web_fetch）

openclaw-cn configure --section web            

推荐配置：

设置 Brave API Key（二选一）：

# 方式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）

openclaw-cn configure --section model            

国内用户推荐选择：

○ 自定义模型 (兼容 OpenAI/Anthropic)← 选这个！            

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

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

·月之暗面（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

现象：

Invalid config at ~/.openclaw/openclaw.json:            - gateway.auth.mode: Invalid input            

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

解决方案：

# 方法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

现象：

disconnected (1008): unauthorized: gateway token missing            

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

解决方案：

# 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

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

解决方案：

# 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 密钥。

解决方案：

# 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

现象：

Error: listen EADDRINUSE: address already in use 127.0.0.1:18789            

解决方案：

# 1. 查找占用进程            lsof -i :18789            # 或            ss -tlnp | grep 18789            # 2. 终止进程（谨慎操作）            kill -9# 3. 或修改网关端口（编辑配置）       jq '.gateway.port = 18790' ~/.openclaw/openclaw.json > t.json && mv t.json ~/.openclaw/openclaw.json       

问题 6：systemd 服务启动失败

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

排查步骤：

# 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 等海外提供商时连接超时

解决方案：

# 方案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 兼容接口

·但不在预置列表中，需用「自定义模型」方式配置

完整配置步骤

# 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            

验证配置

# 检查配置写入            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 "你好，请用一句话介绍你自己"            

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

快速验证脚本

#!/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

手动测试清单

# 1. 基础对话            openclaw-cn chat "你好"            # 2. 搜索功能（需配置 Brave API）            openclaw-cn chat "搜索今天的科技新闻"            # 3. 查看模型列表（控制界面）            # 发送: /models            # 4. 查看系统状态            openclaw-cn chat "/status"            # 5. 重置对话上下文            openclaw-cn chat "/reset"            

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

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

步骤 1：停止所有 OpenClaw 进程

# 停止前台运行的网关            pkill -f "openclaw-cn gateway"            # 停止 systemd 服务（如果已安装）            systemctl --user stop openclaw-gateway.service            systemctl --user disable openclaw-gateway.service# 取消开机自启            

步骤 2：卸载 npm 包

# 全局卸载 openclaw-cn            npm uninstall -g openclaw-cn            # 验证是否卸载成功            openclaw-cn --version# 应提示 command not found            

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

# 备份配置（可选但推荐）            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：清理环境变量（可选）

# 编辑 ~/.bashrc 或 ~/.zshrc，删除以下行（如果存在）：            # export OPENCLAW_GATEWAY_TOKEN="xxx"            # export BRAVE_API_KEY="xxx"            # export OPENAI_API_KEY="xxx"            # 使修改生效            source ~/.bashrc# 或 source ~/.zshrc            

步骤 5：验证卸载

# 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 缓存

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

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

配置管理

# 配置各模块            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# 仅模型部分            

网关控制

# 启动/停止/重启            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# 查看日志            

认证与令牌

# 查看/生成网关 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"            

测试与调试

# 测试对话            openclaw-cn chat "你好"            # 检查配置有效性            openclaw-cn doctor            openclaw-cn doctor --fix# 自动修复配置            # 查看模型列表（控制界面命令）            # 在 Web UI 发送: /models            # 重置对话            # 在对话中输入: /reset            

卸载相关

# 卸载包            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 的完整配置！

现在你的助手已经可以：

理解中文，进行自然对话            调用 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 配置片段

• 相关错误日志