本文面向初学者，系统讲解 OpenClaw（原名 Clawdbot/Moltbot）模型配置的核心概念、常见错误及各提供商的配置方法。无论你使用 Anthropic、OpenAI、Google、OpenRouter 还是本地模型，都能在本文找到对应的配置方案。

📚 第一部分：核心概念理解

1.1 什么是 OpenClaw？

OpenClaw 是一款开源的个人 AI 助手，由知名 macOS 开发者 Peter Steinberger 于 2025 年底创建（原名 Clawdbot）。它采用本地优先（Local-first）的 Gateway 架构，让你可以在自己的设备上运行 AI 助手，并通过 Telegram、Discord、WhatsApp、Slack、iMessage、Microsoft Teams、Signal、Google Chat 等多种渠道与之交互。

💡 名称变更历史：

• 2025年11月：Clawdbot（原始名称）
• 2026年1月：Moltbot（因 Anthropic 商标异议更名）
• 2026年1月29日：OpenClaw（最终定名）

OpenClaw 的核心优势：

• 🔐 隐私优先：数据存储在本地，你完全掌控
• 💰 复用现有订阅：可以使用你已有的 Claude Pro/Max 订阅，无需额外付费
• 🔌 多提供商支持：支持 Anthropic、OpenAI、Google、OpenRouter、Ollama 等众多模型提供商
• 🌐 跨平台运行：支持 macOS、Linux、Windows（通过 WSL2）

项目热度：根据 Wikipedia，OpenClaw 在 GitHub 上已获得 超过 145,000 颗星。

1.2 配置体系架构

在开始配置之前，你必须理解 OpenClaw 的配置层级结构：

~/.openclaw/
├── openclaw.json              # 主配置文件
├── credentials/
│   └── oauth.json             # OAuth 令牌存储（旧版导入）
└── agents/
    └── main/
        └── agent/
            ├── auth-profiles.json   # API 密钥配置（OAuth + API keys）
            └── models.json          # 模型提供商配置

⚠️ v2026.1.29 更新说明：配置目录已从 ~/.clawdbot/ 迁移至 ~/.openclaw/，旧路径会自动迁移。

1.3 ⚠️ 最重要的概念区分

这是新手最容易踩的坑！ 请务必区分以下两个配置路径：

记忆口诀：

• 想用哪个模型 → model（单数）
• 想允许哪些模型 → models（复数）

📚 第二部分：常见错误诊断与解决

2.1 错误一：配置键名不被识别

错误现象

$ openclaw config set agents.defaults.models '{"chat": {"model": "google/gemini-3-pro", "provider": "openrouter"}}'
Error: Config validation failed: agents.defaults.models.chat: Unrecognized keys: "model", "provider"

错误原因

你试图在 agents.defaults.models（白名单配置）中使用 model 和 provider 这两个键，但这个配置项不接受这种格式。

agents.defaults.models 的正确格式：

{
  "openrouter/google/gemini-3-pro": {
    "alias": "Gemini3Pro"
  },
  "anthropic/claude-sonnet-4-5": {
    "alias": "Sonnet"
  }
}

正确做法

如果你的目的是设置默认模型，应该使用 agents.defaults.model.primary：

openclaw config set agents.defaults.model.primary 'openrouter/google/gemini-3-pro'

2.2 错误二：Unknown model（未知模型）

错误现象

[gateway] agent model: openrouter/auto
[diagnostic] lane task error: error="Error: Unknown model: openrouter/auto"
Embedded agent failed before reply: Unknown model: openrouter/auto

错误原因

auto 不是一个有效的模型名称。你必须指定具体的模型，模型引用格式为 <提供商>/<模型名>。

💡 例外：OpenRouter 提供了一个特殊的 Auto Model (openrouter/openrouter/auto)，它会根据提示自动选择最具成本效益的模型。这对于 OpenClaw 来说非常理想，因为它会将简单任务（如心跳和状态检查）路由到更便宜的模型。

正确做法

# ✅ 正确：指定具体模型
openclaw config set agents.defaults.model.primary 'openrouter/google/gemini-3-pro'

# ✅ 正确：使用 OpenRouter Auto（注意格式）
openclaw config set agents.defaults.model.primary 'openrouter/openrouter/auto'

# ❌ 错误：使用简单的 auto
openclaw config set agents.defaults.model.primary 'openrouter/auto'

2.3 错误三：Gateway 端口被占用

错误现象

Gateway failed to start: gateway already running (pid 688726); lock timeout after 5000ms
Port 18789 is already in use.

解决方法

# 第一步：停止正在运行的 Gateway
openclaw gateway stop

# 第二步：重新启动
openclaw gateway

如果使用 systemd 服务：

systemctl --user stop openclaw-gateway.service

2.4 错误四：No auth configured

错误现象

$ openclaw health
Status: no auth configured

错误原因

根据 v2026.1.29 安全更新，Gateway 现在强制要求认证。auth: none 模式已被移除。

解决方法

重新运行 onboard 向导设置 OAuth 或 API 密钥认证：

openclaw onboard

向导会自动生成 Gateway 令牌并存储在 gateway.auth.token 中。

📚 第三部分：各提供商配置详解

3.1 🟠 Anthropic（Claude）配置

Anthropic 是 OpenClaw 官方推荐的首选提供商，因为 Claude 模型在长上下文处理和抗提示注入方面表现出色。

方式一：API 密钥配置（推荐用于生产环境）

第一步：获取 API 密钥

1. 访问 Anthropic Console
2. 创建并复制你的 API 密钥（仅显示一次，请妥善保存）

第二步：配置 OpenClaw

# 方法 A：通过 onboard 命令（交互式）
openclaw onboard --auth-choice apiKey --token-provider anthropic --token "sk-ant-api03-..."

# 方法 B：通过配置文件
openclaw config set env.ANTHROPIC_API_KEY 'sk-ant-api03-...'
openclaw config set agents.defaults.model.primary 'anthropic/claude-opus-4-5'

或者在 openclaw.json 中直接配置：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5"
      }
    }
  }
}

方式二：使用 Claude Pro/Max 订阅（Setup-Token）

如果你已经订阅了 Claude Pro 或 Claude Max，可以复用订阅而无需额外的 API 费用。

第一步：生成 setup-token

# 在任意已安装 Claude CLI 的机器上运行
claude setup-token

第二步：在 Gateway 主机上配置

# 如果在同一台机器上
openclaw models auth setup-token --provider anthropic

# 如果在不同机器上，粘贴 token
openclaw models auth paste-token --provider anthropic

⚠️ 重要提示：Anthropic 已限制 Claude Code OAuth 令牌仅能在 Claude Code 内部使用。如果你之前使用 OAuth 方式，可能需要删除旧凭据并重新配置：

rm ~/.openclaw/credentials/oauth.json

Anthropic 可用模型

3.2 🟢 OpenAI（GPT）配置

获取 API 密钥

访问 OpenAI Platform 创建密钥。

配置方法

# 方法 A：交互式配置
openclaw onboard --auth-choice openai-api-key

# 方法 B：非交互式配置
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

# 方法 C：手动配置
openclaw config set env.OPENAI_API_KEY 'sk-...'
openclaw config set agents.defaults.model.primary 'openai/gpt-5.2'

配置文件方式：

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.2"
      }
    }
  }
}

OpenAI 可用模型

3.3 🔵 Google Gemini 配置

Google 提供多种认证方式，OpenClaw 通过插件系统支持这些方式。

方式一：Antigravity OAuth（推荐）

# 启用插件
openclaw plugins enable google-antigravity-auth

# 登录并设为默认
openclaw models auth login --provider google-antigravity --set-default

方式二：Gemini CLI OAuth

# 启用插件
openclaw plugins enable google-gemini-cli-auth

# 登录并设为默认
openclaw models auth login --provider google-gemini-cli --set-default

方式三：通过 OpenRouter 使用 Gemini

这是最简单的方式，无需配置 Google Cloud：

openclaw config set agents.defaults.model.primary 'openrouter/google/gemini-3-pro'

💡 提示：通过 OpenRouter 使用 Google 模型时，你只需要 OpenRouter 的 API 密钥，无需单独配置 Google 凭据。

3.4 🟣 OpenRouter 配置（多模型聚合）

根据 OpenRouter 官方文档，OpenRouter 是一个 API 聚合服务，通过单一 API 密钥即可访问 400+ 模型，包括 Anthropic、OpenAI、Google、Meta 等多家提供商的模型。

OpenClaw 内置支持 OpenRouter，你不需要配置 models.providers——只需设置 API 密钥并使用 openrouter/<author>/<slug> 格式引用模型。

配置方法

第一步：获取 API 密钥

访问 OpenRouter 注册并获取 API 密钥

第二步：配置 OpenClaw

# 方法 A：通过 onboard 命令（推荐）
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "sk-or-..."

# 方法 B：手动配置
openclaw config set env.OPENROUTER_API_KEY 'sk-or-...'
openclaw config set agents.defaults.model.primary 'openrouter/google/gemini-3-pro'

配置文件方式：

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/google/gemini-3-pro"
      }
    }
  }
}

OpenRouter 模型命名格式

openrouter/<提供商>/<模型名>

⚠️ 注意：模型引用通过第一个 / 分割。如果模型 ID 包含 /（OpenRouter 风格），必须包含 provider 前缀（例如：openrouter/moonshotai/kimi-k2）。

常用 OpenRouter 模型

3.5 🏠 Ollama 本地模型配置

根据 Ollama 官方文档 和 集成公告，Ollama 于 2026 年 2 月 1 日正式宣布与 OpenClaw 集成，让你可以在本地运行开源 LLM，完全免费且数据不离开你的设备。

前提条件

确保 Ollama 已安装并运行：

# 安装 Ollama（以 macOS 为例）
brew install ollama

# 拉取推荐模型（需要至少 64,000 token 上下文）
ollama pull glm-4.7

# 启动服务
ollama serve

硬件要求

推荐模型（需要 64k+ 上下文）

根据 官方文档，OpenClaw 要求模型至少有 64,000 token 上下文长度才能可靠完成多步骤任务：

配置方法

方式一：新版集成命令（2026年2月+）

# Ollama 自动配置 OpenClaw 连接
ollama launch openclaw

方式二：自动发现模式（推荐）

当 Ollama 在本地默认端口（11434）运行时，OpenClaw 可以自动发现它。设置 OLLAMA_API_KEY 环境变量即可启用自动发现：

openclaw config set models.providers.ollama.apiKey 'ollama-local'
openclaw config set agents.defaults.model.primary 'ollama/glm-4.7'

或设置环境变量：

export OLLAMA_API_KEY="ollama-local"

方式三：手动配置模式（用于远程 Ollama 或自定义端口）

{
  "models": {
    "providers": {
      "ollama": {
        "apiKey": "ollama-local",
        "baseUrl": "http://192.168.1.100:11434/v1"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/glm-4.7",
        "fallbacks": ["ollama/glm-4.7-flash"]
      }
    }
  }
}

Ollama 服务器优化环境变量

# 上下文窗口大小
export OLLAMA_CONTEXT_LENGTH=16384

# 启用 Flash Attention（更快、更少 VRAM）
export OLLAMA_FLASH_ATTENTION=1

# 使用新推理引擎
export OLLAMA_NEW_ENGINE=1

📝 注意：OpenClaw 自动发现时只会列出支持**工具调用（Tool Calling）**的模型。如果你的模型未被列出，需要在 models.providers.ollama 中显式定义。

3.6 🔧 自定义提供商配置

OpenClaw 支持任何 OpenAI 兼容 或 Anthropic 兼容 的 API 端点。

配置结构

{
  "models": {
    "mode": "merge",
    "providers": {
      "<提供商名称>": {
        "baseUrl": "<API 端点>",
        "apiKey": "${ENV_VAR_NAME}",
        "api": "openai-completions | anthropic-messages",
        "models": [
          {
            "id": "<模型ID>",
            "name": "<显示名称>",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

示例：Moonshot（月之暗面）

{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.ai/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2-0905-preview",
            "name": "Kimi K2"
          }
        ]
      }
    }
  }
}

示例：LM Studio（本地）

根据 Medium 教程：

{
  "models": {
    "mode": "merge",
    "providers": {
      "lmstudio": {
        "baseUrl": "http://127.0.0.1:1234/v1",
        "apiKey": "lm-studio",
        "api": "openai-completions",
        "models": [
          {
            "id": "local-model",
            "name": "My Local Model"
          }
        ]
      }
    }
  }
}

示例：Cerebras（高速推理）

{
  "models": {
    "mode": "merge",
    "providers": {
      "cerebras": {
        "baseUrl": "https://api.cerebras.ai/v1",
        "apiKey": "${CEREBRAS_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "zai-glm-4.7",
            "name": "GLM 4.7"
          }
        ]
      }
    }
  }
}

📝 可选参数说明：reasoning、input、cost、contextWindow、maxTokens 都是可选的。如果省略，OpenClaw 会使用默认值：reasoning: false、input: ["text"]、cost: { input: 0, output: 0 }、contextWindow: 200000。

📚 第四部分：Gateway 管理与验证

4.1 Gateway 生命周期管理

4.2 模型管理命令

根据 CLI 文档：

4.3 配置查看与修改

4.4 验证配置是否生效

第一步：重启 Gateway

openclaw gateway stop
openclaw gateway

第二步：检查启动日志

成功的配置应该显示：

[gateway] agent model: openrouter/google/gemini-3-pro  ← 你设置的模型
[gateway] listening on ws://0.0.0.0:18789 (PID xxxxx)

如果看到 Unknown model 错误，请检查模型名称是否正确。

📚 第五部分：高级配置技巧

5.1 设置备用模型（Fallback）

当主模型不可用或达到速率限制时，自动切换到备用模型：

openclaw config set agents.defaults.model.fallbacks '["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"]'

或在配置文件中：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": [
          "anthropic/claude-sonnet-4-5",
          "openai/gpt-5.2"
        ]
      }
    }
  }
}

5.2 为特定 Agent 设置独立模型

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5"
      }
    },
    "list": [
      {
        "id": "code-assistant",
        "model": {
          "primary": "anthropic/claude-opus-4-5"
        }
      }
    ]
  }
}

5.3 配置模型白名单

限制用户只能使用特定模型（适用于团队环境）：

{
  "agents": {
    "defaults": {
      "models": {
        "anthropic/claude-sonnet-4-5": { "alias": "Sonnet" },
        "anthropic/claude-opus-4-5": { "alias": "Opus" },
        "openai/gpt-5.2": { "alias": "GPT5" }
      }
    }
  }
}

设置白名单后，用户只能通过 /model 命令切换到白名单中的模型。

5.4 Gateway 认证配置

根据 v2026.1.29 安全更新，Gateway 现在强制要求认证：

{
  "gateway": {
    "bind": "lan",
    "port": 18789,
    "auth": {
      "token": "your-secure-token"
    }
  }
}

⚠️ 安全提示：

• 非 loopback 绑定必须设置 gateway.auth.token 或 gateway.auth.password
• auth: none 模式已在 v2026.1.29 中移除
• onboard 向导会自动生成 token

📚 第六部分：速查表

6.1 模型 ID 快速参考

6.2 常用配置命令

# 查看当前模型
openclaw config get agents.defaults.model

# 设置默认模型
openclaw config set agents.defaults.model.primary '<provider>/<model>'

# 设置 API 密钥
openclaw config set env.ANTHROPIC_API_KEY 'sk-ant-...'
openclaw config set env.OPENAI_API_KEY 'sk-...'
openclaw config set env.OPENROUTER_API_KEY 'sk-or-...'

# 查看模型状态
openclaw models status

# 切换模型
openclaw models set anthropic/claude-sonnet-4-5

# 重启 Gateway 使配置生效
openclaw gateway stop && openclaw gateway

# 诊断问题
openclaw doctor
openclaw health
openclaw status --all

6.3 故障排查清单