验证配置
4. 查看当前配置的模型
openclaw models list
5. 测试模型连接
openclaw models test deepseek/deepseek-chat
常见问题：配置后无法连接？
Q1：配置后无法连接？
检查项：
• baseUrl 是否正确
• apiKey 是否有效
• 网络是否能访问 API 地址
• 配置文件 JSON 格式是否正确
常见问题：如何切换模型？
Q2：如何切换模型？
临时切换:
openclaw agent --message --model
deepseek/deepseek-chat
永久切换：
修改配置文件中的 primary 字段
常见问题：如何添加多个模型？
Q3：如何添加多个模型？
在 models 数组中添加多个模型对象即可
每个模型需要有唯一的 id
// 示例结构
[]
[]
{
"id": "model-1",
"name": "Model One"
},
{
"id": "model-2",
"name": "Model Two"
}
]
内置API模型配置（推荐新手）
适合人群：新手用户、想要快速上手的用户
以下是几个常用的内置API模型配置教程。选择一个你喜欢的即可。
Kimi 配置（推荐）
特点
• 超长上下文：支持200万字
• 长文档处理：论文、报告分析专家
• 中文理解好：适合中文场景
• 套餐划算：重度使用建议购买套餐
Kimi Logo
Kimi 配置步骤：第一步 & 第二步
第一步：访问Kimi Code平台
访问：
第二步：购买套餐（可选）
提示：OpenClaw消耗token较大，建议购买套餐
更划算。
推荐套餐：
• Allegretto套餐：适合日常使用
• 按需选择其他套餐
Kimi 配置步骤：第三步 & 第四步
第三步：创建API Key
1. 打开控制台
2. 创建API Key
3. 名称随便取
第四步：保存API Key
☑ 重要：这个API Key一定要复制并保存！点击"完成"
后就无法再查看了。
Kimi 配置步骤：第五步 & 成本估算
第五步：配置到OpenClaw
# 运行配置向导
openclaw onboard
# 配置流程：
1. 选择 QuickStart
2. 选择模型供应商：Moonshot AI
3. 粘贴刚才复制的API Key
4. 选择默认模型：kimi-code/kimi-for-codi
5. 完成其他配置
成本估算：
• 轻度使用：10-20元/月
• 中度使用：30-50元/月
• 重度使用：建议购买套餐
DeepSeek 配置（性价比之王）
特点
• 最便宜：输入元/千tokens
• 推理能力强：适合复杂任务
• 编程能力出色：代码生成质量高 DeepSeek Logo
DeepSeek 配置步骤：第一步 & 第二步
第一步：注册并充值
访问：
注意：DeepSeek采用按量付费，账户余额必须大于0才
能调用API。
DeepSeek 配置步骤：第三步 & 第四步
第三步：创建API Key
1. 保证账号有余额
2. 点击"API keys"
3. 点击"创建API key"
第四步：保存API Key
☑ 重要：API Key只显示一次，务必复制保存！
名称随便取，复制API Key后妥善保存。
DeepSeek 配置步骤：第五步 & 成本估算
第五步：配置到OpenClaw
# 运行配置向导
openclaw onboard
# 配置流程：
1. 选择 QuickStart
2. 选择模型供应商：DeepSeek
3. 粘贴API Key
4. 选择默认模型：deepseek-chat
5. 完成其他配置
成本估算：
• 日常使用：5-10元/月
• 中度使用：10-30元/月
• 重度使用：30-50元/月
国产大模型配置（其他选项）
1. DeepSeek配置（性价比之王）
• 最便宜：输入元/千tokens
• 推理能力强：适合复杂任务
• 编程能力出色：代码生成质量高
DeepSeek 的 API 调用是按量付费的，你的账户余额必须大于 0 才能正常调用接口。
如果账户没钱或余额不足，API 请求会直接失败，所以提前充值是保证服务可用的必要操作。
其他大模型也是同理，你要去找到对应网址去充值，然后获取API keys。
Moonshot 配置步骤：第一步 & 第二步
1. 注册账号
访问：
注册并登录
2. 获取API Key
1. 进入"API管理"
2. 点击"创建API Key"
3. 复制API Key
Moonshot 配置步骤：第三步 & 第四步
3. 配置到OpenClaw
{
"models": {
"mode": "merge",
"providers": {
"moonshot": {
"baseUrl": "
"apiKey": "sk-你的API 密钥",
"auth": "api-key",
"api": "openai-chat",
"models": [
{
"id": "moonshot-v1-8k",
"name": "Kimi ",
"contextWindow": 8000,
"maxTokens": 4096
}
]
}
},
"agents": {
"defaults": {
"model": {
"primary": "moonshot/moonshot-v1-8k"
}
}
}
}
4. 重启Gateway
openclaw gateway restart
Moonshot 成本估算 & 其他国产大模型
成本估算
• 日常使用：10-20元/月
• 中度使用：20-50元/月
• 重度使用：50-100元/月
3. 其他国产大模型
模型 特点 价格 官网
GLM-4 多模态能力强 中等
.cn
文心一言 百度生态 中高
m
通义千问 阿里生态 中等
国际模型配置（可选）
如果需要使用Claude、GPT等国际模型：
• 直接使用官方API（需要魔法）
• 使用第三方API服务（国内直连）
推荐第三方API：
• 价格便宜50%-70%
• 国内直连，无需魔法
• 支持支付宝、微信支付
成本对比 & 省钱技巧
成本对比 省钱技巧
• 日常对话：用DeepSeek（最便宜）
• 长文档：用Kimi（长上下文）
• 复杂任务：用Claude（质量最高）
常见问题解决：安装问题
Q1: 版本不对
# 检查版本
node --version
# 如果低于22，升级
nvm install 22
nvm use 22
Q2: 权限错误
Windows:
以管理员身份运行PowerShell
Q3: 网络连接失败
• 检查网络连接
• 尝试使用代理
• 或使用云端部署
常见问题解决：API配置问题
Q1: API Key无效
• 检查是否完整复制（包括sk-前缀）
• 检查是否有多余空格
• 检查账户余额是否充足
Q2: 模型不可用
• 检查模型ID是否正确
• 检查API服务是否正常
• 尝试切换其他模型
Q3: Token消耗太快
• 使用更便宜的模型（DeepSeek）
• 优化提示词
• 定期清理会话历史
常见问题解决：Gateway问题
Q1: Gateway无法启动
# 查看日志
tail -f ~/.openclaw/logs/
# 重启Gateway
openclaw gateway restart
Q2: 端口被占用
# 查看端口占用
lsof -i :18789
# 修改端口
openclaw config set 18790
X 版本升级指南：为什么要升级？
▲ 重要提示：目前推荐使用 版本。 版本存在已知 bug（Issue #15141），会导致
heartbeat 和消息处理功能异常。
为什么要升级？
• 新功能和改进
• 性能优化
• 安全修复
• Bug修复
• 更好的兼容性
推荐版本：当前推荐版本：
已知问题版本：：Session 路径验证 bug，影响 heartbeat 和 Telegram/飞书消息处理
升级方式选择 & 方式一：npm直接升级（推荐）
检查当前版本
# 查看当前版本
openclaw --version
# 查看配置文件版本
cat ~/.openclaw/ | grep version
升级方式选择
安装方式 升级方法 难度 推荐度
云端部署 重新部署镜像 ★★★★ ★★★★★
Docker 拉取新镜像 ★★★★ ★★★★★
本地安装（npm） npm升级 ★★★★ ★★★★★
本地安装（源码） git pull ★★★★★ ★★★★★
升级步骤：备份配置 & 停止Gateway
第一步：备份配置
# 备份整个配置目录
cp -r ~/.openclaw ~/.-$(date
+%Y%m%d)
# 验证备份
ls -la ~/.-*
第二步：停止Gateway服务
# 停止Gateway
openclaw gateway stop
# 验证已停止
openclaw gateway status
升级步骤：卸载旧版本 & 安装新版本
第三步：卸载旧版本
# 卸载旧版本
npm uninstall -g openclaw
# 验证卸载
which openclaw # 应该没有输出
第四步：安装新版本
# 安装推荐版本 （需要--force）
npm install -g openclaw@ --force
△ 版本选择说明：推荐安装 版本（稳定），避免安装 版本（存在 bug）。
△ 为什么需要--force？ npm会检测到已存在的文件，使用 --force 强制覆盖。
升级步骤：修复配置 & 重启Gateway
第五步：修复配置
# 运行doctor工具自动修复配置
openclaw doctor --fix
doctor工具会自动更新入口点、检查兼容性、修复已知问题。
第六步：重启Gateway
# 重启Gateway
openclaw gateway restart
# 等待几秒后检查状态
sleep 5
openclaw gateway status
升级步骤：验证升级 & 升级示例
第七步：验证升级
# 检查版本
openclaw --version
# 检查Gateway状态
openclaw gateway status
# 测试连接
openclaw channels status成功的输出应该显示：
Runtime: running (pid xxxxx, state active)
RPC probe: ok
Listening: *:18789
升级示例：真实升级过程
升级背景：原版本 → 目标版本
图：升级前版本检查 图：使用npm install --force
结果：升级成功，配置自动迁移，Gateway运行正常。
方式二：官方脚本升级 & 方式三：Docker升级
方式二：官方脚本升级
# 运行升级脚本
curl -fsSL | bash
缺点：可能遇到npm错误，不如方式一可靠。
方式三：Docker升级
# 停止并删除旧容器
docker compose down
# 拉取最新镜像
docker compose pull
# 启动新容器
docker compose up -d openclaw-cn-gateway
方式四：云端部署升级 & 升级后的变化
方式四：云端部署升级（腾讯云Lighthouse）
1. 进入轻量应用服务器控制台
2. 选择你的OpenClaw实例
3. 点击"重置应用"
4. 选择最新的OpenClaw镜像
5. 等待重置完成
6. 重新配置API（配置会保留）
升级后的变化
配置文件自动迁移：
• 更新配置文件格式
• 迁移旧版本配置
• 创建备份文件
服务管理改进：
• LaunchAgent/Service自动更新
• 路径更新为新版本
• 日志位置统一
已知警告 & 升级故障排查
已知警告
Config warnings:
: plugin feishu: duplicate plugin id detected
说明：这是一个已知的插件重复警告，不影响正常使用。
升级故障排查
问题1：npm install报错EEXIST
症状
npm error code EEXIST
npm error path /usr/local/bin/openclaw
npm error EEXIST: file already exists
解决方案
# 使用--force参数强制覆盖
npm install -g openclaw@ --force
升级故障排查
问题2：Gateway启动失败
症状
Gateway not running
解决方案
# 运行doctor修复
openclaw doctor --fix
# 重启Gateway
openclaw gateway restart
# 查看详细日志
tail -f ~/.openclaw/logs/
问题3：配置文件版本不匹配
症状
Config was last written by a newer OpenClaw (-3); current version is -
解决方案
# 升级到推荐版本
npm install -g openclaw@ --force
openclaw doctor --fix
升级故障排查
问题4：插件加载失败
症状
plugin not found: xxx
解决方案
# 重新安装插件
openclaw plugins install
# 或禁用有问题的插件
openclaw config set []
问题5：端口被占用
症状
Error: listen EADDRINUSE: address already in use :::18789
解决方案
# 查找占用端口的进程
lsof -i :18789
# 停止旧的Gateway进程
kill -9 [PID]
# 或修改端口
openclaw config set 18790
openclaw gateway restart
回滚到旧版本 & 升级最佳实践
回滚到旧版本
如果升级后遇到问题，可以回滚到旧版本。
方式一：从备份恢复
# 停止Gateway
openclaw gateway stop
恢复配置 & 降级
# 恢复配置
cp -r ~/.-20260213/* ~/.openclaw/
# 降级到旧版本（以中文版为例）
npm uninstall -g openclaw
npm install -g @qingchencloud/openclaw-zh@ --force
# 重启Gateway
openclaw gateway restart
方式二：安装指定版本
# 查看可用版本
npm view openclaw versions
# 安装指定版本
npm install -g openclaw@ --force
# 修复配置 & 重启Gateway
# 修复配置
openclaw doctor --fix
# 重启Gateway
openclaw gateway restart
升级最佳实践
升级前必做
• 1. 备份配置
• 2. 记录当前版本
• 3. 导出重要配置
• 4. 检查磁盘空间
升级时注意 & 升级后验证
升级时注意
• 使用--force参数
• 运行doctor修复
• 检查Gateway状态
• 查看日志
升级后验证
• 检查版本号
• 测试Gateway连接
• 验证插件功能
• 测试频道连接
• 检查API消耗
已知问题版本警告 & 升级时间建议
版本问题：Session 文件路径验证逻辑错误，导致 heartbeat 功能失败。
升级时间建议
☑ 晚上或周末（使用量低）
每月检查一次更新
发现Bug时及时升级
安全更新立即升级
不推荐升级时机
工作日高峰期
重要任务进行中
网络不稳定时
没有备份时
自动更新（可选） & 版本发布说明
自动更新（可选）
# 编辑crontab
crontab -e
# 添加每周检查更新（周日凌晨2点）
0 2 * * 0 /usr/local/bin/openclaw doctor --check-updates
版本发布说明
查看每个版本的更新内容：
# 访问GitHub发布页面
# 或使用命令行
curl -s
升级成本估算 & 升级检查清单
升级成本估算 升级检查清单
• 升级前：备份、记录版本、检查空间
• 升级中：停止服务、卸载、安装、修复、重启
• 升级后：验证版本、连接、插件、频道、日志
升级支持 & 升级案例
升级支持
• 查看日志
• 运行诊断
• 查看官方文档
• 加入社区
升级案例： →
耗时：约5分钟
结果：配置自动迁移，Gateway运行正常。
本章小结 & 实战练习
本章小结
• 了解了云端部署和本地部署的区别
• 完成了OpenClaw的安装（云端或本地）
• 配置了API（推荐国产大模型）
• 验证了安装是否成功
• 学会了如何升级OpenClaw
实战练习
1. 完成OpenClaw安装
2. 配置至少一个API
3. 发送第一条测试消息
4. 验证AI是否正常回复
5. 检查当前版本，尝试升级
