Model (模型) 配置指南

Model 是 Wegent 中 AI 模型的配置参数,定义了 Bot 使用哪个 AI 服务、如何认证以及使用什么模型。本指南将帮助您完成 Model 的完整配置和验证。

📋 目录

什么是 Model
模型选择指南
API 密钥获取教程
环境变量详解
配置步骤
配置验证
完整配置示例
常见问题
相关资源

🎯 什么是 Model

Model 是 Bot 的"大脑",决定了 Bot 使用哪个 AI 模型进行思考和推理。

Bot 架构中的位置

Bot = Ghost (灵魂) + Shell (身体) + Model (大脑)

类比:

Ghost: 人的性格和专业知识
Shell: 人的身体和手脚
Model: 人的大脑(思考能力的强弱)

Model 与 Shell 的关系

Shell (执行环境) + Model (AI 模型) = 完整的智能能力

Shell 决定"能做什么"
Model 决定"思考能力有多强"

与数据库的关系

Model 资源存储在数据库的以下表中:

public_models: 存储所有用户共享的公共 Model 配置
kinds: 存储用户自定义的私有 Model 配置 (type='user')

模型类型

Wegent 支持两种类型的模型:

类型	说明	存储位置
公共模型	系统提供的所有用户共享的模型	`public_models` 表
用户模型	用户自定义的私有模型	`kinds` 表

当将模型绑定到 Bot 时，系统按以下顺序解析模型:

用户的私有模型 (type='user')
公共模型 (type='public')

📊 模型选择指南

Anthropic Claude 系列 (推荐)

Claude Haiku 4

特点:

⚡ 响应速度最快
💰 成本最低
⭐⭐ 能力基础但够用

适用场景:

简单代码修改和格式化
文档编写
快速问答
日常简单任务

推荐指数: ⭐⭐⭐⭐ (成本敏感型任务)

Claude Sonnet 4 (最推荐)

特点:

⚡⚡ 响应速度中等
💰💰 成本适中
⭐⭐⭐⭐ 能力强大

适用场景:

常规代码开发
代码审查
功能实现
测试编写
大多数开发任务

推荐指数: ⭐⭐⭐⭐⭐ (最佳平衡选择)

Claude Opus

特点:

⚡ 响应较慢
💰💰💰 成本最高
⭐⭐⭐⭐⭐ 能力最强

适用场景:

复杂架构设计
算法优化
系统级重构
需要深度推理的任务

推荐指数: ⭐⭐⭐ (仅用于复杂任务)

OpenAI GPT 系列

GPT-4

特点:

⚡⚡ 响应速度中等
💰💰💰 成本较高
⭐⭐⭐⭐⭐ 能力强大

适用场景:

复杂推理任务
多步骤问题解决
创意性工作

推荐指数: ⭐⭐⭐⭐

GPT-3.5 Turbo

特点:

⚡⚡⚡ 响应速度快
💰 成本低
⭐⭐⭐ 能力中等

适用场景:

简单对话
基础代码生成
快速原型

推荐指数: ⭐⭐⭐

不同任务场景的模型推荐

任务类型	推荐模型	备选模型
日常开发	Claude Sonnet 4	GPT-4
简单任务	Claude Haiku 4	GPT-3.5 Turbo
代码审查	Claude Sonnet 4	GPT-4
复杂架构	Claude Opus	GPT-4
文档编写	Claude Haiku 4	Claude Sonnet 4
测试编写	Claude Sonnet 4	Claude Haiku 4

🔑 API 密钥获取教程

Anthropic API Key 获取

步骤 1: 访问 Anthropic Console

访问官网: https://console.anthropic.com/settings/keys

步骤 2: 注册或登录账号

如果已有账号,直接登录
如果没有账号,点击 "Sign Up" 注册新账号

步骤 3: 创建 API Key

登录后进入 "API Keys" 页面
点击 "Create Key" 按钮
给 API Key 命名 (如 "Wegent Development")
点击 "Create" 创建

步骤 4: 保存 API Key

⚠️ 重要: API Key 只会显示一次!

立即复制并保存到安全的地方
API Key 格式示例: sk-ant-api03-xxxxxxxxxxxxx

API Key 格式说明

正确格式: 以 sk-ant- 开头

sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

官网链接: https://console.anthropic.com/settings/keys

OpenAI API Key 获取

步骤 1: 访问 OpenAI Platform

访问官网: https://platform.openai.com/api-keys

步骤 2: 注册或登录账号

如果已有账号,直接登录
如果没有账号,点击 "Sign up" 注册新账号

步骤 3: 创建 API Key

登录后进入 "API keys" 页面
点击 "Create new secret key" 按钮
给 API Key 命名 (如 "Wegent Bot")
选择权限 (通常选择 "All")
点击 "Create secret key" 创建

步骤 4: 保存 API Key

⚠️ 重要: API Key 只会显示一次!

立即复制并保存到安全的地方
API Key 格式示例: sk-xxxxxxxxxxxxxxxxxxxxx

API Key 格式说明

正确格式: 以 sk- 开头

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

官网链接: https://platform.openai.com/api-keys

API Key 安全存储建议

✅ 推荐做法

使用环境变量管理
- 不要直接写在代码中
- 使用 .env 文件 (但不要提交到 Git)
使用密钥管理服务
- AWS Secrets Manager
- Azure Key Vault
- HashiCorp Vault
限制访问权限
- 仅授权必要的团队成员
- 定期轮换 API Key

❌ 避免做法

❌ 不要提交到 Git 仓库
❌ 不要在公开场合分享
❌ 不要写在前端代码中
❌ 不要使用明文存储

🔧 环境变量详解

ClaudeCode 运行时 - Anthropic 模型环境变量

使用 ClaudeCode Shell 运行 Anthropic Claude 模型时,需要配置以下环境变量:

完整变量表

变量名	说明	示例值	必填
`ANTHROPIC_MODEL`	主要模型配置,格式为 `提供商,模型名` 或直接 `模型名`	`anthropic/claude-sonnet-4` 或 `claude-4.1-opus`	是
`ANTHROPIC_AUTH_TOKEN`	认证令牌,从 Anthropic Console 获取	`sk-ant-api03-xxxx...`	是*
`ANTHROPIC_API_KEY`	认证密钥,部分运行时使用此变量	`sk-ant-api03-xxxx...`	是*
`ANTHROPIC_BASE_URL`	API 基础 URL,默认为官方 API	`https://api.anthropic.com`	否
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	快速模型配置,用于简单任务以降低成本	`anthropic/claude-haiku-4.5`	否

注意:

* 表示 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 至少需要一个
建议两者都配置,以兼容不同版本的运行时

字段详细说明

1. ANTHROPIC_MODEL (必填)

作用: 指定主要使用的 Claude 模型

格式选项:

方式 1: 提供商,模型名 (推荐)

"ANTHROPIC_MODEL": "anthropic,claude-sonnet-4"

方式 2: 提供商/模型名

"ANTHROPIC_MODEL": "anthropic/claude-sonnet-4"

方式 3: 直接使用模型名
```
"ANTHROPIC_MODEL": "claude-sonnet-4"
```

可用模型名称:

claude-sonnet-4 - Claude Sonnet 4 (推荐)
claude-haiku-4.5 - Claude Haiku 4.5
claude-4.1-opus - Claude Opus (如果可用)

2. ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY (必填其一)

作用: 提供 API 认证凭证

获取方式: 从 https://console.anthropic.com/settings/keys 创建

格式: 以 sk-ant- 开头的字符串

示例:

"ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
"ANTHROPIC_API_KEY": "sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

最佳实践: 同时配置两个变量

{
  "ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-xxxx",
  "ANTHROPIC_API_KEY": "sk-ant-api03-xxxx"
}

3. ANTHROPIC_BASE_URL (可选)

作用: 指定 API 的基础 URL

默认值: https://api.anthropic.com

使用场景:

使用代理服务时需要修改
使用自建 API 网关
使用第三方 API 转发服务 (如 OpenRouter)

示例:

// 官方 API (默认)
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"

// 使用 OpenRouter
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api/v1"

// 自定义代理
"ANTHROPIC_BASE_URL": "https://your-proxy.example.com"

4. ANTHROPIC_DEFAULT_HAIKU_MODEL (可选但推荐)

作用: 指定用于简单任务的快速模型,以降低成本

推荐值: anthropic/claude-haiku-4.5

使用场景:

系统会自动在简单任务中使用此模型
降低整体 API 调用成本
提升响应速度

示例:

"ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"

OpenAI 模型环境变量

使用 OpenAI GPT 模型时,需要配置以下环境变量:

完整变量表

变量名	说明	示例值	必填
`OPENAI_API_KEY`	OpenAI API 密钥	`sk-xxxxxxxxxxxxxxxx`	是
`OPENAI_MODEL`	模型名称	`gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo`	是
`OPENAI_BASE_URL`	API 基础 URL,默认为官方 API	`https://api.openai.com/v1`	否

字段详细说明

1. OPENAI_API_KEY (必填)

作用: 提供 OpenAI API 认证凭证

获取方式: 从 https://platform.openai.com/api-keys 创建

格式: 以 sk- 开头的字符串

示例:

"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. OPENAI_MODEL (必填)

作用: 指定使用的 GPT 模型

可用模型:

gpt-4 - GPT-4 (能力强,成本高)
gpt-4-turbo - GPT-4 Turbo (更快,成本较低)
gpt-3.5-turbo - GPT-3.5 Turbo (快速,成本低)

示例:

"OPENAI_MODEL": "gpt-4"

3. OPENAI_BASE_URL (可选)

作用: 指定 API 的基础 URL

默认值: https://api.openai.com/v1

使用场景:

使用 Azure OpenAI Service
使用代理服务
使用第三方 API 转发服务

示例:

// 官方 API (默认)
"OPENAI_BASE_URL": "https://api.openai.com/v1"

// Azure OpenAI
"OPENAI_BASE_URL": "https://your-resource.openai.azure.com"

// 自定义代理
"OPENAI_BASE_URL": "https://your-proxy.example.com/v1"

🚀 配置步骤

方式 1: 通过 Web 界面配置 (推荐新手)

步骤 1: 进入 Model 管理页面

登录 Wegent Web 界面 (http://localhost:3000)
进入设置 → Models 标签页
您将看到统一的模型列表，显示公共模型和用户自定义模型
点击 创建新模型 按钮添加新模型

步骤 2: 配置模型详情

在模型创建/编辑对话框中，配置以下内容:

基本信息:

名称: 给 Model 起一个描述性的名称 (如 my-claude-sonnet)
显示名称: 可选的在界面上显示的人类可读名称

提供商配置:

提供商类型: 选择 OpenAI 或 Anthropic
模型 ID: 从预设模型中选择或输入自定义模型 ID
- OpenAI 预设: gpt-4, gpt-4-turbo, gpt-3.5-turbo, gpt-4o, gpt-4o-mini
- Anthropic 预设: claude-sonnet-4-20250514, claude-3-7-sonnet-20250219, claude-3-5-haiku-20241022

认证信息:

API Key: 输入您从提供商获取的 API 密钥
- 使用可见性切换按钮 (👁️) 显示/隐藏密钥
Base URL: 可选的自定义 API 端点 (用于代理或自托管服务)

步骤 3: 测试连接

在保存之前，使用 测试连接 功能验证您的配置:

点击 测试连接 按钮
系统会发送一个最小化的测试请求来验证:
- API Key 有效性
- 模型可用性
- 网络连通性
结果:
- ✅ "成功连接到 {模型}" - 配置有效
- ❌ 错误信息 - 检查您的 API 密钥或网络设置

步骤 4: 保存配置

点击保存创建或更新模型。

模型将出现在您的模型列表中，可以在 Bot 配置中使用。

方式 2: 通过 YAML 文件配置

步骤 1: 创建 YAML 文件

创建一个 YAML 配置文件,例如 my-model.yaml

步骤 2: 编写配置

参考下方 "完整配置示例" 章节编写配置内容。

步骤 3: 导入配置

通过 Web 界面或 API 导入 YAML 配置。

🔄 任务中的模型选择

单任务模型覆盖

创建或发送任务时，您可以覆盖 Bot 的默认模型:

在聊天界面中，找到 模型选择器 下拉框
从可用模型中选择不同的模型
可选择启用 强制覆盖 以确保使用此模型，即使 Bot 已配置了模型

使用场景:

在不修改 Bot 配置的情况下测试不同模型
对复杂任务使用更强大的模型
对简单任务使用更快/更便宜的模型

模型解析优先级

当任务运行时，模型按以下顺序解析:

任务级覆盖 (如果 force_override_bot_model 为 true)
Bot 的 bind_model (来自 agent_config)
Bot 的 modelRef (旧版)
默认模型

✅ 配置验证

配置 Model 后,务必进行验证以确保配置正确,避免后续使用时出错。

验证方法 1: 通过 Web 界面查看状态

步骤 1: 进入 Model 列表

登录 Wegent Web 界面
进入 资源管理 → Model 配置
查看 Model 列表

步骤 2: 检查状态

✅ 状态显示为 Available: 配置正确,可以使用
❌ 状态显示为 Unavailable: 配置有问题,需要排查

步骤 3: 查看配置详情

点击 Model 名称查看详细配置,确认:

API Key 是否正确
模型名称是否正确
BASE_URL 是否正确 (如果使用了代理)

验证方法 2: 通过创建测试 Bot

步骤 1: 创建测试 Bot

创建一个简单的 Bot 使用新配置的 Model:

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: test-bot
  namespace: default
spec:
  ghostRef:
    name: developer-ghost  # 使用现有的 Ghost
    namespace: default
  shellRef:
    name: ClaudeCode
    namespace: default
  modelRef:
    name: my-new-model  # 引用新配置的 Model
    namespace: default

步骤 2: 分配简单任务

给 Bot 分配一个简单的测试任务,例如:

请编写一个 Python 函数,计算两个数的和。

步骤 3: 查看执行结果

✅ 如果任务成功执行,说明 Model 配置正确
❌ 如果任务失败,查看错误信息进行排查

步骤 4: 查看任务日志

在任务详情页查看执行日志,确认:

API 调用是否成功
是否有认证错误
是否有模型不可用错误

验证方法 3: 通过 API 测试

步骤 1: 访问 API 文档

访问: http://localhost:8000/api/docs

步骤 2: 测试 Model 接口

找到 Model 相关的 API 接口 (如 GET /api/v1/models)
点击 "Try it out"
输入您的 Model 名称
点击 "Execute" 执行请求

步骤 3: 检查响应

状态码 200: 配置正确
状态码 401: 认证失败,检查 API Key
状态码 404: Model 不存在,检查名称和命名空间
状态码 500: 服务器错误,检查配置格式

示例: 成功响应

{
  "apiVersion": "agent.wecode.io/v1",
  "kind": "Model",
  "metadata": {
    "name": "claude-sonnet-4",
    "namespace": "default"
  },
  "spec": {
    "env": {
      "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4",
      "ANTHROPIC_AUTH_TOKEN": "sk-ant-***",
      "ANTHROPIC_API_KEY": "sk-ant-***",
      "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
    }
  },
  "status": {
    "state": "Available"
  }
}

验证方法 4: 查看日志排查问题

如果验证失败,查看日志进行排查:

查看后端日志

docker-compose logs backend

查看 Executor 日志

docker-compose logs executor_manager

常见错误码及解决方案

错误码	错误信息	原因	解决方案
401	`Unauthorized` / `Invalid API Key`	API Key 无效或过期	1. 检查 API Key 格式是否正确 2. 重新生成 API Key 3. 确认 API Key 已激活
429	`Too Many Requests` / `Rate Limit Exceeded`	超过速率限制	1. 等待一段时间后重试 2. 检查是否有其他程序在使用同一 API Key 3. 升级 API 套餐
500	`Internal Server Error`	配置格式错误或服务器内部错误	1. 检查 JSON 格式是否正确 2. 检查环境变量名称拼写 3. 查看后端日志获取详细错误信息
404	`Model not found`	模型名称不存在	1. 检查模型名称拼写 2. 确认模型在 API 提供商处可用 3. 参考官方文档确认模型名称

调试步骤

检查 API Key 格式

# Anthropic API Key 应该以 sk-ant- 开头
echo $ANTHROPIC_AUTH_TOKEN | grep "^sk-ant-"

# OpenAI API Key 应该以 sk- 开头
echo $OPENAI_API_KEY | grep "^sk-"

测试 API 连接

# 测试 Anthropic API
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

检查配置文件格式
- 使用 JSON/YAML 验证器检查格式
- 确保没有多余的逗号或引号
- 确保所有字段名拼写正确

💡 完整配置示例

示例 1: Claude Sonnet 4 完整配置 (推荐)

YAML 格式

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: claude-sonnet-4
  namespace: default
spec:
  env:
    # 主要模型配置 - Claude Sonnet 4
    ANTHROPIC_MODEL: "anthropic/claude-sonnet-4"

    # API 认证令牌 (必填,从 Anthropic Console 获取)
    ANTHROPIC_AUTH_TOKEN: "sk-ant-api03-your-api-key-here"

    # API 密钥 (建议配置,兼容不同运行时)
    ANTHROPIC_API_KEY: "sk-ant-api03-your-api-key-here"

    # API 基础 URL (可选,默认为官方 API)
    ANTHROPIC_BASE_URL: "https://api.anthropic.com"

    # 快速模型配置 (可选但推荐,用于简单任务降低成本)
    ANTHROPIC_DEFAULT_HAIKU_MODEL: "anthropic/claude-haiku-4.5"
status:
  state: "Available"

JSON 格式 (Web 界面使用)

{
  "env": {
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4",
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-your-api-key-here",
    "ANTHROPIC_API_KEY": "sk-ant-api03-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
  }
}

使用场景:

日常开发任务
代码审查
功能实现
最佳的性能和成本平衡

示例 2: Claude Haiku 4 完整配置 (经济型)

YAML 格式

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: claude-haiku-4
  namespace: default
spec:
  env:
    # 主要模型配置 - Claude Haiku 4.5
    ANTHROPIC_MODEL: "anthropic/claude-haiku-4.5"

    # API 认证
    ANTHROPIC_AUTH_TOKEN: "sk-ant-api03-your-api-key-here"
    ANTHROPIC_API_KEY: "sk-ant-api03-your-api-key-here"

    # API 基础 URL
    ANTHROPIC_BASE_URL: "https://api.anthropic.com"
status:
  state: "Available"

JSON 格式

{
  "env": {
    "ANTHROPIC_MODEL": "anthropic/claude-haiku-4.5",
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-api03-your-api-key-here",
    "ANTHROPIC_API_KEY": "sk-ant-api03-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

使用场景:

简单代码修改
文档编写
格式化任务
成本敏感的场景

示例 3: OpenAI GPT-4 完整配置

YAML 格式

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: gpt-4
  namespace: default
spec:
  env:
    # OpenAI API 密钥 (必填)
    OPENAI_API_KEY: "sk-your-openai-api-key-here"

    # 模型名称 (必填)
    OPENAI_MODEL: "gpt-4"

    # API 基础 URL (可选,默认为官方 API)
    OPENAI_BASE_URL: "https://api.openai.com/v1"
status:
  state: "Available"

JSON 格式

{
  "env": {
    "OPENAI_API_KEY": "sk-your-openai-api-key-here",
    "OPENAI_MODEL": "gpt-4",
    "OPENAI_BASE_URL": "https://api.openai.com/v1"
  }
}

使用场景:

复杂推理任务
需要 GPT-4 特定能力的场景
已有 OpenAI 账户的用户

示例 4: 多模型并存配置

在同一个 Wegent 系统中可以配置多个 Model 资源,供不同的 Bot 使用:

# Model 1: 快速经济型
---
apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: fast-model
  namespace: default
spec:
  env:
    ANTHROPIC_MODEL: "anthropic/claude-haiku-4.5"
    ANTHROPIC_AUTH_TOKEN: "sk-ant-api03-your-key"
    ANTHROPIC_API_KEY: "sk-ant-api03-your-key"
    ANTHROPIC_BASE_URL: "https://api.anthropic.com"
status:
  state: "Available"

---
# Model 2: 标准开发型
apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: standard-model
  namespace: default
spec:
  env:
    ANTHROPIC_MODEL: "anthropic/claude-sonnet-4"
    ANTHROPIC_AUTH_TOKEN: "sk-ant-api03-your-key"
    ANTHROPIC_API_KEY: "sk-ant-api03-your-key"
    ANTHROPIC_BASE_URL: "https://api.anthropic.com"
    ANTHROPIC_DEFAULT_HAIKU_MODEL: "anthropic/claude-haiku-4.5"
status:
  state: "Available"

---
# Model 3: GPT-4 备选
apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: gpt4-model
  namespace: default
spec:
  env:
    OPENAI_API_KEY: "sk-your-openai-key"
    OPENAI_MODEL: "gpt-4"
    OPENAI_BASE_URL: "https://api.openai.com/v1"
status:
  state: "Available"

使用方式:

# Bot 1: 使用快速模型
kind: Bot
metadata:
  name: quick-bot
spec:
  modelRef:
    name: fast-model  # 引用 Haiku
    namespace: default

---
# Bot 2: 使用标准模型
kind: Bot
metadata:
  name: developer-bot
spec:
  modelRef:
    name: standard-model  # 引用 Sonnet
    namespace: default

---
# Bot 3: 使用 GPT-4
kind: Bot
metadata:
  name: gpt-bot
spec:
  modelRef:
    name: gpt4-model  # 引用 GPT-4
    namespace: default

示例 5: 使用代理的配置

如果您使用 API 代理服务 (如 OpenRouter),需要修改 BASE_URL:

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: claude-via-proxy
  namespace: default
spec:
  env:
    ANTHROPIC_MODEL: "anthropic/claude-sonnet-4"
    ANTHROPIC_AUTH_TOKEN: "your-proxy-api-key"
    ANTHROPIC_API_KEY: "your-proxy-api-key"
    # 修改为代理 URL
    ANTHROPIC_BASE_URL: "https://openrouter.ai/api/v1"
status:
  state: "Available"

⚠️ 常见问题

Q1: API Key 无效怎么办?

症状:

Bot 任务执行失败
错误信息包含 "401 Unauthorized" 或 "Invalid API Key"

解决步骤:

检查 API Key 格式
- Anthropic: 应以 sk-ant- 开头
- OpenAI: 应以 sk- 开头
重新生成 API Key
- 访问 Anthropic Console 或 OpenAI Platform
- 删除旧的 API Key
- 创建新的 API Key
- 更新 Model 配置
检查 API Key 是否激活
- 确认账户状态正常
- 确认 API Key 未被删除或禁用
检查变量名拼写
- ANTHROPIC_AUTH_TOKEN (不是 ANTHROPIC_API_TOKEN)
- ANTHROPIC_API_KEY (不是 ANTHROPIC_KEY)

Q2: 模型调用失败如何排查?

排查步骤:

查看后端日志

docker-compose logs backend | grep -i error

查看 Executor 日志

docker-compose logs executor_manager | grep -i error

检查网络连接

# 测试能否访问 Anthropic API
curl -I https://api.anthropic.com

# 测试能否访问 OpenAI API
curl -I https://api.openai.com

验证配置格式
- 使用 JSON/YAML 验证器检查格式
- 确认没有语法错误
检查模型名称
- 确认模型名称拼写正确
- 参考官方文档确认模型可用

Q3: 成本控制建议

策略 1: 任务分层使用不同模型

# 简单任务用 Haiku (便宜)
fast-bot → claude-haiku-4

# 常规任务用 Sonnet (平衡)
developer-bot → claude-sonnet-4

# 复杂任务用 Opus (贵但强大)
expert-bot → claude-opus

策略 2: 配置 DEFAULT_HAIKU_MODEL

系统会自动在简单任务中使用 Haiku,降低成本:

{
  "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
}

策略 3: 设置 API 使用限制

在 API 提供商的控制台中设置:

每月使用限额
每日使用限额
单次调用 token 限制

策略 4: 监控使用情况

定期检查:

API 使用统计
成本报告
调用频率

Q4: 如何切换模型?

方式 1: 更新 Bot 的 modelRef

# 修改 Bot 配置,引用不同的 Model
apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: my-bot
spec:
  modelRef:
    name: claude-haiku-4  # 从 Sonnet 改为 Haiku
    namespace: default

方式 2: 更新 Model 配置

# 修改 Model 资源,更改模型版本
apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: my-model
spec:
  env:
    ANTHROPIC_MODEL: "anthropic/claude-sonnet-4"  # 从 Haiku 改为 Sonnet

注意: 方式 2 会影响所有使用此 Model 的 Bot。

Q5: 初始化数据中的示例 Model 如何使用?

Wegent 在初始化时可能已经创建了一些示例 Model 配置。

查看方式:

通过 Web 界面
- 进入 资源管理 → Model 配置
- 查看现有 Model 列表
检查初始化脚本
- 查看 backend/init.sql 或相关初始化文件
- 查看预设的 Model 配置

使用方式:

如果发现示例 Model (如 claude-model):

查看其配置详情
复制配置作为模板
修改 API Key 为您的实际密钥
创建新的 Model 资源

不要直接修改示例 Model: 建议创建新的 Model 资源,避免影响系统默认配置。

Q6: 支持哪些模型提供商?

当前 Wegent 主要支持:

✅ Anthropic Claude

Claude Haiku 4.5
Claude Sonnet 4
Claude Opus (如果可用)

✅ OpenAI GPT

GPT-4
GPT-4 Turbo
GPT-3.5 Turbo

⚠️ 其他提供商 (可能需要自定义配置):

Azure OpenAI
本地模型 (通过兼容 API)
第三方 API 服务 (如 OpenRouter)

Q7: BASE_URL 何时需要修改?

需要修改的场景:

使用 API 代理

"ANTHROPIC_BASE_URL": "https://your-proxy.example.com"

使用 OpenRouter

"ANTHROPIC_BASE_URL": "https://openrouter.ai/api/v1"

使用 Azure OpenAI

"OPENAI_BASE_URL": "https://your-resource.openai.azure.com"

企业内部 API 网关

"ANTHROPIC_BASE_URL": "https://internal-gateway.company.com"

不需要修改的场景:

直接使用官方 Anthropic API
直接使用官方 OpenAI API

🔗 相关资源

下一步

智能体设置 - 配置智能体和机器人

参考文档

核心概念 - 理解 Model 在架构中的角色
YAML 规范 - 完整的配置格式

官方资源

💬 获取帮助

遇到问题?

📖 查看 FAQ
🐛 提交 GitHub Issue
💬 加入社区讨论

配置好 Model,为您的 Bot 赋予强大的 AI 能力! 🚀

📋 目录​

🎯 什么是 Model​

Bot 架构中的位置​

Model 与 Shell 的关系​

与数据库的关系​

模型类型​

📊 模型选择指南​

Anthropic Claude 系列 (推荐)​

Claude Haiku 4​

Claude Sonnet 4 (最推荐)​

Claude Opus​

OpenAI GPT 系列​

GPT-4​

GPT-3.5 Turbo​

不同任务场景的模型推荐​

🔑 API 密钥获取教程​

Anthropic API Key 获取​

步骤 1: 访问 Anthropic Console​

步骤 2: 注册或登录账号​

步骤 3: 创建 API Key​

步骤 4: 保存 API Key​

API Key 格式说明​

OpenAI API Key 获取​

步骤 1: 访问 OpenAI Platform​

步骤 2: 注册或登录账号​

步骤 3: 创建 API Key​

步骤 4: 保存 API Key​

API Key 格式说明​

API Key 安全存储建议​

✅ 推荐做法​

❌ 避免做法​

🔧 环境变量详解​

ClaudeCode 运行时 - Anthropic 模型环境变量​

完整变量表​

字段详细说明​

1. ANTHROPIC_MODEL (必填)​

2. ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY (必填其一)​

3. ANTHROPIC_BASE_URL (可选)​

4. ANTHROPIC_DEFAULT_HAIKU_MODEL (可选但推荐)​

OpenAI 模型环境变量​

完整变量表​

字段详细说明​

1. OPENAI_API_KEY (必填)​

2. OPENAI_MODEL (必填)​

3. OPENAI_BASE_URL (可选)​

🚀 配置步骤​

方式 1: 通过 Web 界面配置 (推荐新手)​

步骤 1: 进入 Model 管理页面​

步骤 2: 配置模型详情​

步骤 3: 测试连接​

步骤 4: 保存配置​

方式 2: 通过 YAML 文件配置​

步骤 1: 创建 YAML 文件​

步骤 2: 编写配置​

步骤 3: 导入配置​

🔄 任务中的模型选择​

单任务模型覆盖​

模型解析优先级​

✅ 配置验证​

验证方法 1: 通过 Web 界面查看状态​

步骤 1: 进入 Model 列表​

步骤 2: 检查状态​

步骤 3: 查看配置详情​

验证方法 2: 通过创建测试 Bot​

步骤 1: 创建测试 Bot​

步骤 2: 分配简单任务​

步骤 3: 查看执行结果​

步骤 4: 查看任务日志​

验证方法 3: 通过 API 测试​

步骤 1: 访问 API 文档​

步骤 2: 测试 Model 接口​

步骤 3: 检查响应​

示例: 成功响应​

验证方法 4: 查看日志排查问题​

查看后端日志​

查看 Executor 日志​

常见错误码及解决方案​

调试步骤​

💡 完整配置示例​

示例 1: Claude Sonnet 4 完整配置 (推荐)​

📋 目录

🎯 什么是 Model

Bot 架构中的位置

Model 与 Shell 的关系

与数据库的关系

模型类型

📊 模型选择指南

Anthropic Claude 系列 (推荐)

Claude Haiku 4

Claude Sonnet 4 (最推荐)

Claude Opus

OpenAI GPT 系列

GPT-4

GPT-3.5 Turbo

不同任务场景的模型推荐

🔑 API 密钥获取教程

Anthropic API Key 获取

步骤 1: 访问 Anthropic Console

步骤 2: 注册或登录账号

步骤 3: 创建 API Key

步骤 4: 保存 API Key

API Key 格式说明

OpenAI API Key 获取

步骤 1: 访问 OpenAI Platform

步骤 2: 注册或登录账号

步骤 3: 创建 API Key

步骤 4: 保存 API Key

API Key 格式说明

API Key 安全存储建议

✅ 推荐做法

❌ 避免做法

🔧 环境变量详解

ClaudeCode 运行时 - Anthropic 模型环境变量

完整变量表

字段详细说明

1. ANTHROPIC_MODEL (必填)

2. ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY (必填其一)

3. ANTHROPIC_BASE_URL (可选)

4. ANTHROPIC_DEFAULT_HAIKU_MODEL (可选但推荐)

OpenAI 模型环境变量

完整变量表

字段详细说明

1. OPENAI_API_KEY (必填)

2. OPENAI_MODEL (必填)

3. OPENAI_BASE_URL (可选)

🚀 配置步骤

方式 1: 通过 Web 界面配置 (推荐新手)

步骤 1: 进入 Model 管理页面

步骤 2: 配置模型详情

步骤 3: 测试连接

步骤 4: 保存配置

方式 2: 通过 YAML 文件配置

步骤 1: 创建 YAML 文件

步骤 2: 编写配置

步骤 3: 导入配置

🔄 任务中的模型选择

单任务模型覆盖

模型解析优先级

✅ 配置验证

验证方法 1: 通过 Web 界面查看状态

步骤 1: 进入 Model 列表

步骤 2: 检查状态

步骤 3: 查看配置详情

验证方法 2: 通过创建测试 Bot

步骤 1: 创建测试 Bot

步骤 2: 分配简单任务

步骤 3: 查看执行结果

步骤 4: 查看任务日志

验证方法 3: 通过 API 测试

步骤 1: 访问 API 文档

步骤 2: 测试 Model 接口

步骤 3: 检查响应

示例: 成功响应

验证方法 4: 查看日志排查问题

查看后端日志

查看 Executor 日志

常见错误码及解决方案

调试步骤

💡 完整配置示例

示例 1: Claude Sonnet 4 完整配置 (推荐)