最后更新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 为例 验证与测试确认一切正常工作 完整卸载教程干净移除 附录常用命令速查表一、前言什么是 OpenClawOpenClaw-CN是一个开源的 AI 助手框架支持多模型接入OpenAI / Claude / 通义千问 / 本地 Ollama 等Web 搜索与网页抓取能力本地 Web 控制界面可视化配置灵活的认证机制Token / Password / 无认证插件系统可扩展工具链适合开发者、技术爱好者搭建私有化、可定制的 AI 助手。二、环境准备系统要求组件最低要求推荐操作系统Linux / macOS / WSL2Ubuntu 22.04 / macOS 12Node.jsv18v20 LTSnpmv9v10内存2GB4GB磁盘500MB2GB含模型缓存检查环境# 检查 Node.js 和 npmnode-v# 应 v18npm-v# 应 v9# 如未安装使用 nvm 安装推荐curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bashsource~/.bashrc nvminstall20nvm use20安装 jq配置编辑必备# Ubuntu/Debiansudoaptupdatesudoaptinstall-yjqcurl# CentOS/RHELsudoyuminstall-yjqcurl# macOSbrewinstalljqcurl三、快速安装国内镜像加速一键安装命令推荐# 使用国内 npm 镜像加速安装curl-fsSLhttps://clawd.org.cn/install.sh|bash-s----registryhttps://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 web 3. 运行: openclaw-cn configure --section model安装失败试试这些错误现象解决方案Permission denied不要用sudo运行安装脚本确保当前用户有~/.openclaw写入权限npm ERR! registry timeout确认--registry参数生效或手动设置npm config set registry https://registry.npmmirror.comnode: command not found先安装 Node.js参考上文环境准备脚本下载失败检查网络或手动下载curl -O https://clawd.org.cn/install.sh四、基础配置向导安装完成后按顺序配置三个核心模块4.1 配置网关gatewayopenclaw-cn configure--sectiongateway推荐配置选项配置项推荐值说明网关运行位置本地此设备单机使用选此项Gateway port18789默认除非端口冲突否则不改Gateway bind modeLoopback (Local only)仅127.0.0.1可访问最安全Gateway authOff (loopback only)本地测试可选off生产环境建议tokenTailscale exposureOff无需远程访问则关闭避坑提示如果选token认证启动前必须设置export OPENCLAW_GATEWAY_TOKENyour-tokenauth.mode的有效值是off/token/password**不是 **none4.2 配置 Web 功能web_search / web_fetchopenclaw-cn configure--sectionweb推荐配置配置项推荐值说明启用 web_searchYes让助手能在线搜索Brave API Key留空用环境变量获取密钥https://brave.com/search/api/启用 web_fetchYes允许抓取网页内容设置 Brave API Key二选一# 方式1临时生效当前终端exportBRAVE_API_KEYyour-brave-api-key# 方式2永久生效推荐echoexport BRAVE_API_KEYyour-brave-api-key~/.bashrcsource~/.bashrc4.3 配置模型提供商modelopenclaw-cn configure--sectionmodel国内用户推荐选择○ 自定义模型 (兼容 OpenAI/Anthropic) ← 选这个后续配置示例以 GitCode AI 为例配置项填写内容Select protocolOpenAI Compatible (Default)Provider IDgitcodeBase URLhttps://api-ai.gitcode.com/v1API Keysk-你的-gitcode-密钥Model ID可添加多个qwen-turbo→qwen-plus→qwen-maxDefault primary modelgitcode/qwen-turbo其他国内提供商配置参考月之暗面Moonshothttps://api.moonshot.cn/v1MiniMaxhttps://api.minimaxi.com/v1阿里云百炼https://dashscope.aliyuncs.com/compatible-mode/v1五、常见问题与避坑指南重点问题 1gateway.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.jsont.jsonmvt.json ~/.openclaw/openclaw.json问题 2网关启动失败提示unauthorized: gateway token missing现象disconnected (1008): unauthorized: gateway token missing原因网关配置为token认证但启动时未提供 token。解决方案# 1. 查看/生成 tokenTOKEN$(jq-r.gateway.auth.token // empty~/.openclaw/openclaw.json)if[-z$TOKEN];thenTOKENoc-$(openssl rand-hex16)jq--argt$TOKEN.gateway.auth.token $t\~/.openclaw/openclaw.jsont.jsonmvt.json ~/.openclaw/openclaw.jsonfi# 2. 设置环境变量并启动exportOPENCLAW_GATEWAY_TOKEN$TOKENopenclaw-cn gateway# 3. 生成带 token 的登录链接openclaw-cn dashboard --no-open# 复制输出的 URL 到浏览器打开问题 3模型加载不出来jq .models返回null现象配置向导跳过了模型配置或配置未正确写入。解决方案# 1. 重新配置模型openclaw-cn configure--sectionmodel# 2. 或手动注入配置以 GitCode 为例GITCODE_KEYsk-你的密钥jq--argkey$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.jsont.jsonmvt.json ~/.openclaw/openclaw.json# 3. 重启网关pkill-fopenclaw-cn gateway2/dev/nullexportOPENCLAW_GATEWAY_TOKEN$(jq-r.gateway.auth.token~/.openclaw/openclaw.json)openclaw-cn gateway问题 4BRAVE_API_KEY not found搜索功能不可用原因启用了web_search但未设置 Brave API 密钥。解决方案# 1. 获取密钥https://brave.com/search/api/# 2. 设置环境变量exportBRAVE_API_KEYyour-key-here# 3. 永久生效加入 ~/.bashrcechoexport BRAVE_API_KEYyour-key-here~/.bashrcsource~/.bashrc# 4. 重启网关使环境变量生效如用 systemdsystemctl--userrestart openclaw-gateway.service问题 5端口 18789 被占用EADDRINUSE现象Error: listen EADDRINUSE: address already in use 127.0.0.1:18789解决方案# 1. 查找占用进程lsof-i:18789# 或ss-tlnp|grep18789# 2. 终止进程谨慎操作kill-9PID# 3. 或修改网关端口编辑配置jq.gateway.port 18790~/.openclaw/openclaw.jsont.jsonmvt.json ~/.openclaw/openclaw.json问题 6systemd 服务启动失败现象systemctl --user start openclaw-gateway.service报错排查步骤# 1. 查看服务状态systemctl--userstatus openclaw-gateway.service# 2. 查看详细日志journalctl--user-uopenclaw-gateway.service-n50-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配置代理如已有exportHTTPS_PROXYhttp://127.0.0.1:7890exportHTTP_PROXYhttp://127.0.0.1:7890# 方案3在配置文件中设置代理部分提供商支持jq.models.providers.openai.proxy http://127.0.0.1:7890\~/.openclaw/openclaw.jsont.jsonmvt.json ~/.openclaw/openclaw.json六、高级配置自定义模型提供商以 GitCode AI 为例为什么需要自定义GitCode AI、Moonshot、MiniMax 等国内提供商使用 OpenAI 兼容接口但不在预置列表中需用「自定义模型」方式配置完整配置步骤# 1. 启动配置向导openclaw-cn configure--sectionmodel# 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-fopenclaw-cn gateway2/dev/nullexportOPENCLAW_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/?tokenxxx# 发送: /models 应看到 gitcode 下的模型为 Ready# 命令行测试openclaw-cn chat你好请用一句话介绍你自己七、验证与测试确认一切正常工作快速验证脚本#!/bin/bash# 保存为 ~/test-openclaw.shechoOpenClaw 健康检查# 1. 检查配置文件if[!-f~/.openclaw/openclaw.json];thenecho配置文件不存在exit1fiecho配置文件存在# 2. 检查模型配置ifjq-e.models.providers | length 0~/.openclaw/openclaw.json/dev/null;thenecho已配置模型提供商:jq-r.models.providers | keys[]~/.openclaw/openclaw.json|seds/^/ - /elseecho未配置模型运行: openclaw-cn configure --section modelfi# 3. 检查网关进程ifpgrep-fopenclaw-cn gateway/dev/null;thenecho网关进程运行中elseecho网关未运行启动: openclaw-cn gatewayfi# 4. 测试端口ifcurl-shttp://127.0.0.1:18789//dev/null21;thenecho网关端口 18789 可访问echo控制界面: http://127.0.0.1:18789/elseecho无法访问网关端口fi# 5. 测试对话如果 openclaw-cn chat 可用ifcommand-vopenclaw-cn/dev/null;thenecho测试对话 (5 秒超时)...timeout5openclaw-cn chatping2/dev/nullecho对话测试成功||echo 对话测试超时/失败fiechoecho提示配置修改后记得重启网关执行bash ~/test-openclaw.sh手动测试清单# 1. 基础对话openclaw-cn chat你好# 2. 搜索功能需配置 Brave APIopenclaw-cn chat搜索今天的科技新闻# 3. 查看模型列表控制界面# 发送: /models# 4. 查看系统状态openclaw-cn chat/status# 5. 重置对话上下文openclaw-cn chat/reset八、完整卸载教程干净移除警告以下操作将永久删除所有配置、数据和缓存请提前备份重要文件步骤 1停止所有 OpenClaw 进程# 停止前台运行的网关pkill-fopenclaw-cn gateway# 停止 systemd 服务如果已安装systemctl--userstop openclaw-gateway.service systemctl--userdisable openclaw-gateway.service# 取消开机自启步骤 2卸载 npm 包# 全局卸载 openclaw-cnnpmuninstall-gopenclaw-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.servicerm-rf~/.config/systemd/user/openclaw-gateway.service.d/# 重载 systemdsystemctl--userdaemon-reload步骤 4清理环境变量可选# 编辑 ~/.bashrc 或 ~/.zshrc删除以下行如果存在# export OPENCLAW_GATEWAY_TOKENxxx# export BRAVE_API_KEYxxx# export OPENAI_API_KEYxxx# 使修改生效source~/.bashrc# 或 source ~/.zshrc步骤 5验证卸载# 1. 确认命令不可用openclaw-cn--version# 应报错# 2. 确认目录已删除ls-la~/.openclaw# 应提示 No such file# 3. 确认端口已释放ss-tlnp|grep18789# 应无输出# 4. 确认进程已终止psaux|grepopenclaw|grep-vgrep# 应无输出可选步骤 6清理 npm 缓存# 清理 openclaw 相关缓存npmcache clean--force# 或精准清理npmcachels|grepopenclaw|xargs-rnpmcache clean--force九、附录常用命令速查表配置管理# 配置各模块openclaw-cn configure--sectiongateway# 网关配置openclaw-cn configure--sectionweb# Web 功能配置openclaw-cn configure--sectionmodel# 模型配置# 查看当前配置jq.~/.openclaw/openclaw.json# 完整配置jq.gateway~/.openclaw/openclaw.json# 仅网关部分jq.models~/.openclaw/openclaw.json# 仅模型部分网关控制# 启动/停止/重启openclaw-cn gateway# 前台启动openclaw-cn gateway restart# 重启如果支持pkill-fopenclaw-cn gateway# 强制停止# systemd 服务管理systemctl--userstart openclaw-gateway.service systemctl--userstop openclaw-gateway.service systemctl--userstatus openclaw-gateway.service journalctl--user-uopenclaw-gateway.service-f# 查看日志认证与令牌# 查看/生成网关 tokenjq-r.gateway.auth.token~/.openclaw/openclaw.json openclaw-cn doctor --generate-gateway-token# 生成带 token 的登录链接openclaw-cn dashboard --no-open# 设置环境变量exportOPENCLAW_GATEWAY_TOKENyour-tokenexportBRAVE_API_KEYyour-brave-key测试与调试# 测试对话openclaw-cn chat你好# 检查配置有效性openclaw-cn doctor openclaw-cn doctor--fix# 自动修复配置# 查看模型列表控制界面命令# 在 Web UI 发送: /models# 重置对话# 在对话中输入: /reset卸载相关# 卸载包npmuninstall-gopenclaw-cn# 删除配置rm-rf~/.openclaw# 清理 systemdsystemctl--userdisable--nowopenclaw-gateway.servicerm-f~/.config/systemd/user/openclaw-gateway.service systemctl--userdaemon-reload最后的话恭喜你完成 OpenClaw-CN 的完整配置现在你的助手已经可以理解中文进行自然对话 调用 GitCode/Moonshot 等国内模型 在线搜索配置 Brave API 后 读取工作空间配置个性化响应 通过 Web 界面可视化管理进阶建议备份配置定期cp -r ~/.openclaw ~/backup/openclaw-$(date %F)监控日志journalctl --user -u openclaw-gateway.service -f更新版本关注 https://clawd.org.cn 获取最新版参与社区遇到问题先在 国内社区 搜索或提交 Issue其他问题先运行openclaw-cn doctor自动诊断查看日志journalctl --user -u openclaw-gateway.service -n 50搜索 https://clawd.org.cn 的 FAQ在社区提问时附上openclaw-cn --version输出jq .gateway,.models ~/.openclaw/openclaw.json配置片段相关错误日志
OpenClaw-CN 完整安装教程与避坑指南（国内镜像加速版）
发布时间：2026/6/14 11:35:08
最后更新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 为例 验证与测试确认一切正常工作 完整卸载教程干净移除 附录常用命令速查表一、前言什么是 OpenClawOpenClaw-CN是一个开源的 AI 助手框架支持多模型接入OpenAI / Claude / 通义千问 / 本地 Ollama 等Web 搜索与网页抓取能力本地 Web 控制界面可视化配置灵活的认证机制Token / Password / 无认证插件系统可扩展工具链适合开发者、技术爱好者搭建私有化、可定制的 AI 助手。二、环境准备系统要求组件最低要求推荐操作系统Linux / macOS / WSL2Ubuntu 22.04 / macOS 12Node.jsv18v20 LTSnpmv9v10内存2GB4GB磁盘500MB2GB含模型缓存检查环境# 检查 Node.js 和 npmnode-v# 应 v18npm-v# 应 v9# 如未安装使用 nvm 安装推荐curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bashsource~/.bashrc nvminstall20nvm use20安装 jq配置编辑必备# Ubuntu/Debiansudoaptupdatesudoaptinstall-yjqcurl# CentOS/RHELsudoyuminstall-yjqcurl# macOSbrewinstalljqcurl三、快速安装国内镜像加速一键安装命令推荐# 使用国内 npm 镜像加速安装curl-fsSLhttps://clawd.org.cn/install.sh|bash-s----registryhttps://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 web 3. 运行: openclaw-cn configure --section model安装失败试试这些错误现象解决方案Permission denied不要用sudo运行安装脚本确保当前用户有~/.openclaw写入权限npm ERR! registry timeout确认--registry参数生效或手动设置npm config set registry https://registry.npmmirror.comnode: command not found先安装 Node.js参考上文环境准备脚本下载失败检查网络或手动下载curl -O https://clawd.org.cn/install.sh四、基础配置向导安装完成后按顺序配置三个核心模块4.1 配置网关gatewayopenclaw-cn configure--sectiongateway推荐配置选项配置项推荐值说明网关运行位置本地此设备单机使用选此项Gateway port18789默认除非端口冲突否则不改Gateway bind modeLoopback (Local only)仅127.0.0.1可访问最安全Gateway authOff (loopback only)本地测试可选off生产环境建议tokenTailscale exposureOff无需远程访问则关闭避坑提示如果选token认证启动前必须设置export OPENCLAW_GATEWAY_TOKENyour-tokenauth.mode的有效值是off/token/password**不是 **none4.2 配置 Web 功能web_search / web_fetchopenclaw-cn configure--sectionweb推荐配置配置项推荐值说明启用 web_searchYes让助手能在线搜索Brave API Key留空用环境变量获取密钥https://brave.com/search/api/启用 web_fetchYes允许抓取网页内容设置 Brave API Key二选一# 方式1临时生效当前终端exportBRAVE_API_KEYyour-brave-api-key# 方式2永久生效推荐echoexport BRAVE_API_KEYyour-brave-api-key~/.bashrcsource~/.bashrc4.3 配置模型提供商modelopenclaw-cn configure--sectionmodel国内用户推荐选择○ 自定义模型 (兼容 OpenAI/Anthropic) ← 选这个后续配置示例以 GitCode AI 为例配置项填写内容Select protocolOpenAI Compatible (Default)Provider IDgitcodeBase URLhttps://api-ai.gitcode.com/v1API Keysk-你的-gitcode-密钥Model ID可添加多个qwen-turbo→qwen-plus→qwen-maxDefault primary modelgitcode/qwen-turbo其他国内提供商配置参考月之暗面Moonshothttps://api.moonshot.cn/v1MiniMaxhttps://api.minimaxi.com/v1阿里云百炼https://dashscope.aliyuncs.com/compatible-mode/v1五、常见问题与避坑指南重点问题 1gateway.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.jsont.jsonmvt.json ~/.openclaw/openclaw.json问题 2网关启动失败提示unauthorized: gateway token missing现象disconnected (1008): unauthorized: gateway token missing原因网关配置为token认证但启动时未提供 token。解决方案# 1. 查看/生成 tokenTOKEN$(jq-r.gateway.auth.token // empty~/.openclaw/openclaw.json)if[-z$TOKEN];thenTOKENoc-$(openssl rand-hex16)jq--argt$TOKEN.gateway.auth.token $t\~/.openclaw/openclaw.jsont.jsonmvt.json ~/.openclaw/openclaw.jsonfi# 2. 设置环境变量并启动exportOPENCLAW_GATEWAY_TOKEN$TOKENopenclaw-cn gateway# 3. 生成带 token 的登录链接openclaw-cn dashboard --no-open# 复制输出的 URL 到浏览器打开问题 3模型加载不出来jq .models返回null现象配置向导跳过了模型配置或配置未正确写入。解决方案# 1. 重新配置模型openclaw-cn configure--sectionmodel# 2. 或手动注入配置以 GitCode 为例GITCODE_KEYsk-你的密钥jq--argkey$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.jsont.jsonmvt.json ~/.openclaw/openclaw.json# 3. 重启网关pkill-fopenclaw-cn gateway2/dev/nullexportOPENCLAW_GATEWAY_TOKEN$(jq-r.gateway.auth.token~/.openclaw/openclaw.json)openclaw-cn gateway问题 4BRAVE_API_KEY not found搜索功能不可用原因启用了web_search但未设置 Brave API 密钥。解决方案# 1. 获取密钥https://brave.com/search/api/# 2. 设置环境变量exportBRAVE_API_KEYyour-key-here# 3. 永久生效加入 ~/.bashrcechoexport BRAVE_API_KEYyour-key-here~/.bashrcsource~/.bashrc# 4. 重启网关使环境变量生效如用 systemdsystemctl--userrestart openclaw-gateway.service问题 5端口 18789 被占用EADDRINUSE现象Error: listen EADDRINUSE: address already in use 127.0.0.1:18789解决方案# 1. 查找占用进程lsof-i:18789# 或ss-tlnp|grep18789# 2. 终止进程谨慎操作kill-9PID# 3. 或修改网关端口编辑配置jq.gateway.port 18790~/.openclaw/openclaw.jsont.jsonmvt.json ~/.openclaw/openclaw.json问题 6systemd 服务启动失败现象systemctl --user start openclaw-gateway.service报错排查步骤# 1. 查看服务状态systemctl--userstatus openclaw-gateway.service# 2. 查看详细日志journalctl--user-uopenclaw-gateway.service-n50-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配置代理如已有exportHTTPS_PROXYhttp://127.0.0.1:7890exportHTTP_PROXYhttp://127.0.0.1:7890# 方案3在配置文件中设置代理部分提供商支持jq.models.providers.openai.proxy http://127.0.0.1:7890\~/.openclaw/openclaw.jsont.jsonmvt.json ~/.openclaw/openclaw.json六、高级配置自定义模型提供商以 GitCode AI 为例为什么需要自定义GitCode AI、Moonshot、MiniMax 等国内提供商使用 OpenAI 兼容接口但不在预置列表中需用「自定义模型」方式配置完整配置步骤# 1. 启动配置向导openclaw-cn configure--sectionmodel# 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-fopenclaw-cn gateway2/dev/nullexportOPENCLAW_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/?tokenxxx# 发送: /models 应看到 gitcode 下的模型为 Ready# 命令行测试openclaw-cn chat你好请用一句话介绍你自己七、验证与测试确认一切正常工作快速验证脚本#!/bin/bash# 保存为 ~/test-openclaw.shechoOpenClaw 健康检查# 1. 检查配置文件if[!-f~/.openclaw/openclaw.json];thenecho配置文件不存在exit1fiecho配置文件存在# 2. 检查模型配置ifjq-e.models.providers | length 0~/.openclaw/openclaw.json/dev/null;thenecho已配置模型提供商:jq-r.models.providers | keys[]~/.openclaw/openclaw.json|seds/^/ - /elseecho未配置模型运行: openclaw-cn configure --section modelfi# 3. 检查网关进程ifpgrep-fopenclaw-cn gateway/dev/null;thenecho网关进程运行中elseecho网关未运行启动: openclaw-cn gatewayfi# 4. 测试端口ifcurl-shttp://127.0.0.1:18789//dev/null21;thenecho网关端口 18789 可访问echo控制界面: http://127.0.0.1:18789/elseecho无法访问网关端口fi# 5. 测试对话如果 openclaw-cn chat 可用ifcommand-vopenclaw-cn/dev/null;thenecho测试对话 (5 秒超时)...timeout5openclaw-cn chatping2/dev/nullecho对话测试成功||echo 对话测试超时/失败fiechoecho提示配置修改后记得重启网关执行bash ~/test-openclaw.sh手动测试清单# 1. 基础对话openclaw-cn chat你好# 2. 搜索功能需配置 Brave APIopenclaw-cn chat搜索今天的科技新闻# 3. 查看模型列表控制界面# 发送: /models# 4. 查看系统状态openclaw-cn chat/status# 5. 重置对话上下文openclaw-cn chat/reset八、完整卸载教程干净移除警告以下操作将永久删除所有配置、数据和缓存请提前备份重要文件步骤 1停止所有 OpenClaw 进程# 停止前台运行的网关pkill-fopenclaw-cn gateway# 停止 systemd 服务如果已安装systemctl--userstop openclaw-gateway.service systemctl--userdisable openclaw-gateway.service# 取消开机自启步骤 2卸载 npm 包# 全局卸载 openclaw-cnnpmuninstall-gopenclaw-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.servicerm-rf~/.config/systemd/user/openclaw-gateway.service.d/# 重载 systemdsystemctl--userdaemon-reload步骤 4清理环境变量可选# 编辑 ~/.bashrc 或 ~/.zshrc删除以下行如果存在# export OPENCLAW_GATEWAY_TOKENxxx# export BRAVE_API_KEYxxx# export OPENAI_API_KEYxxx# 使修改生效source~/.bashrc# 或 source ~/.zshrc步骤 5验证卸载# 1. 确认命令不可用openclaw-cn--version# 应报错# 2. 确认目录已删除ls-la~/.openclaw# 应提示 No such file# 3. 确认端口已释放ss-tlnp|grep18789# 应无输出# 4. 确认进程已终止psaux|grepopenclaw|grep-vgrep# 应无输出可选步骤 6清理 npm 缓存# 清理 openclaw 相关缓存npmcache clean--force# 或精准清理npmcachels|grepopenclaw|xargs-rnpmcache clean--force九、附录常用命令速查表配置管理# 配置各模块openclaw-cn configure--sectiongateway# 网关配置openclaw-cn configure--sectionweb# Web 功能配置openclaw-cn configure--sectionmodel# 模型配置# 查看当前配置jq.~/.openclaw/openclaw.json# 完整配置jq.gateway~/.openclaw/openclaw.json# 仅网关部分jq.models~/.openclaw/openclaw.json# 仅模型部分网关控制# 启动/停止/重启openclaw-cn gateway# 前台启动openclaw-cn gateway restart# 重启如果支持pkill-fopenclaw-cn gateway# 强制停止# systemd 服务管理systemctl--userstart openclaw-gateway.service systemctl--userstop openclaw-gateway.service systemctl--userstatus openclaw-gateway.service journalctl--user-uopenclaw-gateway.service-f# 查看日志认证与令牌# 查看/生成网关 tokenjq-r.gateway.auth.token~/.openclaw/openclaw.json openclaw-cn doctor --generate-gateway-token# 生成带 token 的登录链接openclaw-cn dashboard --no-open# 设置环境变量exportOPENCLAW_GATEWAY_TOKENyour-tokenexportBRAVE_API_KEYyour-brave-key测试与调试# 测试对话openclaw-cn chat你好# 检查配置有效性openclaw-cn doctor openclaw-cn doctor--fix# 自动修复配置# 查看模型列表控制界面命令# 在 Web UI 发送: /models# 重置对话# 在对话中输入: /reset卸载相关# 卸载包npmuninstall-gopenclaw-cn# 删除配置rm-rf~/.openclaw# 清理 systemdsystemctl--userdisable--nowopenclaw-gateway.servicerm-f~/.config/systemd/user/openclaw-gateway.service systemctl--userdaemon-reload最后的话恭喜你完成 OpenClaw-CN 的完整配置现在你的助手已经可以理解中文进行自然对话 调用 GitCode/Moonshot 等国内模型 在线搜索配置 Brave API 后 读取工作空间配置个性化响应 通过 Web 界面可视化管理进阶建议备份配置定期cp -r ~/.openclaw ~/backup/openclaw-$(date %F)监控日志journalctl --user -u openclaw-gateway.service -f更新版本关注 https://clawd.org.cn 获取最新版参与社区遇到问题先在 国内社区 搜索或提交 Issue其他问题先运行openclaw-cn doctor自动诊断查看日志journalctl --user -u openclaw-gateway.service -n 50搜索 https://clawd.org.cn 的 FAQ在社区提问时附上openclaw-cn --version输出jq .gateway,.models ~/.openclaw/openclaw.json配置片段相关错误日志
