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

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

  • 人工智能研究

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

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

    目录

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

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

    1.1 什么是 Clawdbot？

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

    Clawdbot 的核心优势：

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

    1.2 配置体系架构

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

    ~/.clawdbot/
├── clawdbot.json          # 主配置文件 ├── credentials/
│   └── oauth.json         # OAuth 令牌存储 └── agents/
    └── main/
        └── agent/
            ├── auth-profiles.json   # API 密钥配置             └── models.json          # 模型提供商配置

    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 错误一：配置键名不被识别

    错误现象

    $ clawdbot config set agents.defaults.models '{"chat": {"model": "google/gemini-3-pro-preview", "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-preview": {
    "alias": "Gemini3Pro"   },
  "anthropic/claude-sonnet-4-5": {
    "alias": "Sonnet"   }
}

    正确做法

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

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

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

    正确做法

    # ✅ 正确：指定具体模型 clawdbot config set agents.defaults.model.primary 'openrouter/google/gemini-3-pro-preview' 
# ❌ 错误：使用 auto clawdbot 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 clawdbot gateway stop

# 第二步：重新启动 clawdbot gateway

    如果使用 systemd 服务：

    systemctl --user stop clawdbot-gateway.service

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

    3.1 🟠 Anthropic（Claude）配置

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

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

    第一步：获取 API 密钥

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

    第二步：配置 Clawdbot

    # 方法 A：通过 onboard 命令（交互式） clawdbot onboard --auth-choice apiKey --token-provider anthropic --token "sk-ant-api03-..." 
# 方法 B：通过配置文件 clawdbot config set env.ANTHROPIC_API_KEY 'sk-ant-api03-...' clawdbot config set agents.defaults.model.primary 'anthropic/claude-opus-4-5'

    或者在 clawdbot.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 主机上配置

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

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

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

    rm ~/.clawdbot/credentials/oauth.json

    Anthropic 可用模型

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

    3.2 🟢 OpenAI（GPT）配置

    获取 API 密钥

    访问 OpenAI Platform 创建密钥。

    配置方法

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

# 方法 B：非交互式配置 clawdbot onboard --openai-api-key "$OPENAI_API_KEY" 
# 方法 C：手动配置 clawdbot config set env.OPENAI_API_KEY 'sk-...' clawdbot config set agents.defaults.model.primary 'openai/gpt-4o'

    配置文件方式：

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

    OpenAI 可用模型

    模型 ID说明
    openai/gpt-5.2最新旗舰模型
    openai/gpt-4o多模态模型
    openai/gpt-4o-mini轻量快速版本
    openai/gpt-4-turbo高性能版本

    3.3 🔵 Google Gemini 配置

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

    方式一：Antigravity OAuth（推荐）

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

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

    方式二：Gemini CLI OAuth

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

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

    方式三：通过 OpenRouter 使用 Gemini

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

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

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

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

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

    配置方法

    第一步：获取 API 密钥

    第二步：配置 Clawdbot

    # 方法 A：通过 onboard 命令 clawdbot onboard --auth-choice apiKey --token-provider openrouter --token "sk-or-..." 
# 方法 B：手动配置 clawdbot config set env.OPENROUTER_API_KEY 'sk-or-...' clawdbot config set agents.defaults.model.primary 'openrouter/google/gemini-3-pro-preview'

    配置文件方式：

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

    OpenRouter 模型命名格式

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

    常用 OpenRouter 模型

    模型 ID说明
    openrouter/google/gemini-3-pro-previewGoogle Gemini 3 Pro
    openrouter/anthropic/claude-sonnet-4-5Claude Sonnet 4.5
    openrouter/anthropic/claude-opus-4-5Claude Opus 4.5
    openrouter/openai/gpt-4oGPT-4o
    openrouter/meta-llama/llama-3.3-70b-instructLlama 3.3 70B

    3.5 🏠 Ollama 本地模型配置

    Ollama 让你可以在本地运行开源 LLM，完全免费且数据不离开你的设备。

    前提条件

    确保 Ollama 已安装并运行：

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

# 拉取模型 ollama pull llama3.3

# 启动服务 ollama serve

    配置方法

    自动发现模式（推荐）：

    当 Ollama 在本地默认端口（11434）运行时，Clawdbot 可以自动发现它：

    clawdbot config set models.providers.ollama.apiKey 'ollama-local' clawdbot config set agents.defaults.model.primary 'ollama/llama3.3'

    或设置环境变量：

    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/llama3.3",
        "fallback": ["ollama/qwen2.5-coder:32b"]
      }
    }
  }
}

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

    常用 Ollama 模型

    模型说明内存需求
    ollama/llama3.3Meta 最新开源模型~8GB
    ollama/qwen2.5-coder:32b阿里云代码模型~20GB
    ollama/deepseek-r1:32bDeepSeek 推理模型~20GB
    ollama/mistralMistral AI 模型~4GB

    3.6 🔧 自定义提供商配置

    Clawdbot 支持任何 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（本地）

    {
  "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 都是可选的。如果省略，Clawdbot 会使用默认值：reasoning: false、input: ["text"]、cost: { input: 0, output: 0 }、contextWindow: 200000。

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

    4.1 Gateway 生命周期管理

    命令作用
    clawdbot gateway启动 Gateway
    clawdbot gateway stop停止 Gateway
    clawdbot gateway status查看 Gateway 状态

    4.2 模型管理命令

    命令作用
    clawdbot models list列出所有可用模型
    clawdbot models status查看当前模型状态
    clawdbot models set <provider/model>快速切换模型
    clawdbot models auth login --provider <name>OAuth 登录
    clawdbot models auth order get查看认证优先级

    4.3 配置查看与修改

    命令作用
    clawdbot config get agents.defaults.model查看当前默认模型
    clawdbot config set <path> '<value>'设置配置项
    clawdbot doctor诊断配置问题

    4.4 验证配置是否生效

    第一步：重启 Gateway

    clawdbot gateway stop
clawdbot gateway

    第二步：检查启动日志

    成功的配置应该显示：

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

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

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

    5.1 设置备用模型（Fallback）

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

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

    或在配置文件中：

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

    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-4o": { "alias": "GPT4" }
      }
    }
  }
}

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

    📚 第六部分：速查表

    6.1 模型 ID 快速参考

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

    6.2 常用配置命令

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

# 设置默认模型 clawdbot config set agents.defaults.model.primary '<provider>/<model>' 
# 设置 API 密钥 clawdbot config set env.ANTHROPIC_API_KEY 'sk-ant-...' clawdbot config set env.OPENAI_API_KEY 'sk-...' clawdbot config set env.OPENROUTER_API_KEY 'sk-or-...' 
# 重启 Gateway 使配置生效 clawdbot gateway stop && clawdbot gateway

    6.3 故障排查清单

    问题检查项
    Unknown model模型 ID 格式是否正确？提供商是否已配置？
    认证失败API 密钥是否正确？环境变量是否设置？
    Gateway 无法启动端口是否被占用？先运行 gateway stop
    模型不在列表中是否需要在白名单中添加？Ollama 模型是否支持工具调用？

    Brave 回复 5 days, 11 hours ago 1 成員 · 0 回复
  • 0 回复

歡迎留言回复交流。

Log in to reply.

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

報告

屏蔽成員？

請確認您要屏蔽該成員。

你將不再能：

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

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

報告

您已經報告過這個 .