Decentralization? We're still early!
简体
Toggle Side Panel
Brave基地
Brave基地
Close search

主权个人必看的 Clawdbot/OpenClaw 模型配置完全指南（2026版）

  • 人工智能研究

    主权个人必看的 Clawdbot/OpenClaw 模型配置完全指南（2026版）

    發布人 Brave 2026-01-26 03:13

    目录

    本文面向初学者，系统讲解 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 ⚠️ 最重要的概念区分

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

    配置路径用途示例值
    agents.defaults.model设置默认使用的模型（单数）{ "primary": "anthropic/claude-opus-4-5" }
    agents.defaults.models模型白名单 + 别名配置（复数）{ "anthropic/claude-opus-4-5": { "alias": "Opus" } }

    记忆口诀：

    • 想用哪个模型 → 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 可用模型

    模型 ID说明推荐场景
    anthropic/claude-opus-4-5最强质量复杂任务、长上下文（推荐默认）
    anthropic/claude-sonnet-4-5平衡之选日常使用

    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 可用模型

    模型 ID说明
    openai/gpt-5.2最新旗舰模型（推荐）
    openai/gpt-4o多模态模型
    openai/gpt-4o-mini轻量快速版本
    openai/o4-mini推理模型

    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 模型

    模型 ID说明
    openrouter/openrouter/auto自动选择最具成本效益的模型（推荐）
    openrouter/google/gemini-3-proGoogle Gemini 3 Pro
    openrouter/anthropic/claude-sonnet-4-5Claude Sonnet 4.5
    openrouter/anthropic/claude-opus-4-5Claude Opus 4.5
    openrouter/openai/gpt-5.2GPT-5.2
    openrouter/meta-llama/llama-3.3-70b-instructLlama 3.3 70B
    openrouter/moonshotai/kimi-k2Moonshot Kimi K2

    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

    硬件要求

    配置说明
    推荐 VRAM48GB（可靠运行）
    GPUNVIDIA 最佳支持；AMD 可用但性能降低
    无 GPU可在 CPU 上运行，但速度慢 5-10 倍

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

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

    模型说明
    ollama/qwen3-coder代码任务优化
    ollama/glm-4.7通用任务（推荐）
    ollama/glm-4.7-flash快速处理
    ollama/gpt-oss:20b平衡性能
    ollama/gpt-oss:120b复杂推理

    配置方法

    方式一：新版集成命令（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 生命周期管理

    命令作用
    openclaw gateway启动 Gateway
    openclaw gateway stop停止 Gateway
    openclaw gateway status查看 Gateway 状态
    openclaw dashboard打开 Control UI（浏览器聊天）

    4.2 模型管理命令

    根据 CLI 文档：

    命令作用
    openclaw models list列出所有可用模型
    openclaw models status查看当前模型状态（含 auth 概览）
    openclaw models status --probe运行实时 auth 探测（⚠️ 会消耗 token）
    openclaw models set <provider/model>快速切换模型
    openclaw models scan扫描可用模型
    openclaw models auth login --provider <name>OAuth 登录
    openclaw models auth add添加 API 密钥
    openclaw models auth setup-token设置 Claude setup-token
    openclaw models auth paste-token粘贴 setup-token

    4.3 配置查看与修改

    命令作用
    openclaw config get agents.defaults.model查看当前默认模型
    openclaw config set <path> '<value>'设置配置项
    openclaw doctor诊断配置问题
    openclaw health查看健康状态
    openclaw status --all最佳调试报告（可粘贴）
    openclaw plugins list查看已安装的 provider 插件

    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 快速参考

    提供商模型 ID 格式示例
    Anthropicanthropic/<model>anthropic/claude-opus-4-5
    OpenAIopenai/<model>openai/gpt-5.2
    OpenRouteropenrouter/<provider>/<model>openrouter/google/gemini-3-pro
    Ollamaollama/<model>ollama/glm-4.7
    自定义<provider-name>/<model>moonshot/kimi-k2

    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 故障排查清单

    问题检查项
    Unknown model模型 ID 格式是否正确？提供商是否已配置？
    认证失败API 密钥是否正确？环境变量是否设置？
    No auth configured是否运行了 openclaw onboard？Gateway 是否配置了 token？
    Gateway 无法启动端口是否被占用？先运行 gateway stop
    模型不在列表中是否需要在白名单中添加？Ollama 模型是否支持工具调用？
    OAuth 令牌无效删除 ~/.openclaw/credentials/oauth.json 并重新配置

    Brave 回复 1 month, 3 weeks ago 1 成員 · 0 回复
  • 0 回复

歡迎留言回复交流。

Log in to reply.

讨论開始
0 的 0 回复 2018 年 6 月
現在

報告

屏蔽成員？

請確認您要屏蔽該成員。

你將不再能：

  • 查看被屏蔽成員的帖子
  • 在帖子中@此成員
  • 邀請加入該組
  • 留言
  • 添加好友

請注意： 這個操作同時將從你的好友中刪除這個成員，並向網站管理員發送一份報告。 請等待幾分鐘。

報告

您已經報告過這個 .