一、基础规则

1.1 统一引用格式

全局标准写法：提供商前缀:模型名称，所有位置均遵循该格式

示例：

plaintext

deepseek:deepseek-chat
qwen:qwen-max
ollama:llama3
openai:gpt-4o

1.2 两种密钥配置方式

方式 1：环境变量（推荐，更安全）

适合多工具共用密钥、不想明文存配置文件的场景，编辑 ~/.bashrc / ~/.zshrc：

bash

运行

# 示例：多款模型密钥
export DEEPSEEK_API_KEY="sk-xxx"
export QWEN_API_KEY="sk-xxx"
export GLM_API_KEY="xxx"
export MOONSHOT_API_KEY="sk-xxx"
export OPENAI_API_KEY="sk-xxx"

生效命令：

bash

运行

source ~/.bashrc

方式 2：配置文件写入

直接在 ~/.openclaw/openclaw.json 中配置，集中管理，适合单机自用：

json

{
  "providers": {
    "deepseek": {
      "apiKey": "sk-xxx"
    },
    "qwen": {
      "apiKey": "sk-xxx"
    }
  }
}

安全建议：执行 chmod 600 ~/.openclaw/openclaw.json 限制文件权限，防止密钥泄露。

1.3 模型分组

可预设多组模型，适配不同任务：

json

{
  "models": {
    "default": "deepseek:deepseek-chat",
    "large": "qwen:qwen-max",
    "code": "deepseek:deepseek-coder"
  }
}

---

二、国内主流模型（优先推荐，无需翻墙）

2.1 DeepSeek（性价比首选）

主打低价、通用对话与代码能力，国内访问稳定。

1. 官网：https://platform.deepseek.com/ 注册并获取 API Key
2. 完整配置

json

{
  "models": {
    "default": "deepseek:deepseek-chat"
  },
  "providers": {
    "deepseek": {
      "apiKey": "sk-你的密钥"
    }
  }
}

• deepseek-chat：通用对话（主力推荐）
• deepseek-coder：代码编写、排错专用

2.2 通义千问 Qwen（阿里云，中文优化强）

1. 官网：https://dashscope.aliyuncs.com/ 获取 API Key
2. 配置示例

json

{
  "models": {
    "default": "qwen:qwen-plus"
  },
  "providers": {
    "qwen": {
      "apiKey": "sk-你的密钥"
    }
  }
}

模型选型：

• qwen-turbo：轻量快速，简单问答，低成本
• qwen-plus：均衡通用，日常主力
• qwen-max：复杂推理、长文本、创意写作

2.3 智谱 GLM

清华系模型，中文语义理解优秀。

json

{
  "models": {
    "default": "glm:glm-3-turbo"
  },
  "providers": {
    "glm": {
      "apiKey": "你的密钥"
    }
  }
}

2.4 月之暗面 Moonshot（超长上下文）

最高支持 128K 上下文，适合分析小说、合同、日志等长文档。

json

{
  "models": {
    "default": "moonshot:moonshot-v1-32k"
  },
  "providers": {
    "moonshot": {
      "apiKey": "sk-你的密钥"
    }
  }
}

• moonshot-v1-8k：短对话
• moonshot-v1-32k：中等文档
• moonshot-v1-128k：超大文本

---

三、海外主流模型（需网络代理）

3.1 OpenAI

综合能力、多模态最强。

json

{
  "models": {
    "default": "openai:gpt-4o"
  },
  "providers": {
    "openai": {
      "apiKey": "sk-你的密钥"
    }
  }
}

常用模型：

• gpt-4o：旗舰多模态，识图、复杂推理
• gpt-4o-mini：轻量化，速度快、价格低
• o1：深度逻辑推理，数学 / 科研场景

3.2 Anthropic Claude

长文本、安全性表现突出。

json

{
  "models": {
    "default": "anthropic:claude-sonnet-4-20250514"
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-你的密钥"
    }
  }
}

---

四、本地离线模型 Ollama（隐私优先，免费）

数据不上传公网，完全本地运行，适合隐私敏感场景。

4.1 安装 Ollama

bash

运行

# Linux / macOS
curl -fsSL https://ollama.com/install.sh | sh

Windows 前往官网下载客户端：https://ollama.com/download

4.2 拉取模型

bash

运行

ollama pull llama3       # 通用对话
ollama pull codellama    # 代码专用
ollama pull phi3         # 轻量模型，低配电脑可用

4.3 OpenClaw 配置

本地同机部署（默认地址）

json

{
  "models": {
    "default": "ollama:llama3"
  }
}

Ollama 部署在其他设备（局域网）

指定远程地址：

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://192.168.1.100:11434"
    }
  },
  "models": {
    "default": "ollama:llama3"
  }
}

硬件参考：7B 级别模型建议内存 ≥8GB，有 NVIDIA GPU 会自动加速。

---

五、故障转移（Fallback）配置

网络波动、接口限流、服务宕机时，自动切换备用模型，保障服务不中断。

5.1 基础语法

json

{
  "models": {
    "default": "主模型",
    "fallback": [
      "备用模型1",
      "备用模型2"
    ]
  }
}

5.2 国内用户推荐方案

主力 DeepSeek，备用通义千问、智谱 GLM，全国内链路，稳定性拉满：

json

{
  "models": {
    "default": "deepseek:deepseek-chat",
    "fallback": [
      "qwen:qwen-plus",
      "glm:glm-3-turbo"
    ]
  }
}

5.3 海外模型兜底方案

json

{
  "models": {
    "default": "openai:gpt-4o",
    "fallback": [
      "anthropic:claude-sonnet-4-20250514",
      "deepseek:deepseek-chat"
    ]
  }
}

触发场景：接口超时、5xx 错误、429 限流、网络断开。

---

六、场景化配置方案（直接复制即用）

方案 1：日常闲聊 + 低成本（首选）

json

{
  "models": {
    "default": "deepseek:deepseek-chat",
    "fallback": ["qwen:qwen-turbo"]
  },
  "providers": {
    "deepseek": {
      "apiKey": "sk-xxx"
    },
    "qwen": {
      "apiKey": "sk-xxx"
    }
  }
}

方案 2：编程开发专用

json

{
  "models": {
    "default": "deepseek:deepseek-coder",
    "fallback": ["openai:gpt-4o-mini"]
  }
}

方案 3：长文档 / 知识库分析

json

{
  "models": {
    "default": "moonshot:moonshot-v1-128k"
  }
}

方案 4：纯本地离线（无公网、强隐私）

json

{
  "models": {
    "default": "ollama:llama3"
  }
}

---

七、常见问题排查

1. 调用失败、返回密钥错误
   • 检查 apiKey 是否填写正确，有无多余空格
   • 优先切换为环境变量方式配置密钥
2. 国内模型访问超时
   • 确认服务器网络可访问对应厂商域名，关闭代理
3. Ollama 连接失败
   • 执行 ollama ps 确认服务正常运行
   • 跨设备访问检查防火墙、端口 11434 是否放行
4. 故障转移不生效
   • 重启网关 openclaw gateway restart 重载配置

---

八、总结

1. 国内普通用户：优先 DeepSeek + 通义千问 组合，性价比、稳定性最佳；
2. 代码场景：选用 deepseek-coder；长文档选用 moonshot；
3. 隐私需求：直接使用 Ollama 本地模型，数据完全离线；
4. 海外模型：能力强但需网络代理，建议搭配国内模型做故障转移；
5. 密钥优先使用环境变量，提升安全性。