自定义模型配置

开始之前

• 一个提供商的 API 密钥，或局域网/本机可访问的模型服务
• 自定义网关需要可访问的 Base URL；模型 ID 可以用 获取模型 从服务端拉取，不必事先手抄完整目录
• 如果使用 OpenAI 兼容接口，确认服务接受 Chat Completions 或 Responses 协议

获取可用模型

内置提供商打开后会看到已收录的模型列表，勾选 已启用模型 即可出现在对话输入区。

自定义对话提供商在填好 Base URL 和 API 密钥后，不必先手写整个 models 数组。打开 设置 → 模型，选中该提供商，在 已启用模型 右侧点击 获取模型。Wordless 向该 Base URL 请求远端目录，打开选择窗口。

自定义对话提供商：填好 Base URL 后，已启用模型右侧会出现获取模型。

在目录窗口里可以搜索、按组展开、用 + 加入单个模型，或 添加全部模型 一次加入当前目录。点选后状态为「待添加」或「待移除」；确认无误后点击 应用到配置，选中的模型会写入当前提供商配置。回到列表后再勾选要在对话中使用的条目，并 保存。

远端目录按提供商分组。搜索后用 + 加入或移除，再「应用到配置」写入配置。

获取模型 只出现在自定义对话提供商上，且 Base URL 必须是有效的 http(s) 地址、高级 JSON 没有语法错误。图片提供商不使用这条流程。若提供商的目录接口不是默认的 OpenAI /v1/models，在高级 JSON 里设置 modelFetcher 后再拉取。

配置字段怎么填

JSON 字段	作用	示例与注意
name	提供商显示名称	使用 团队 API、本地模型 等可读名称
baseUrl	API 根地址	通常填到 /v1，不要重复添加 /chat/completions
api	请求协议	常用 openai-completions 或 openai-responses
headers	附加 HTTP 请求头	只填网关要求的请求头，不要把密钥写在这里
modelFetcher	拉取远端模型目录的方式	缺省按 Base URL 自动匹配；目录接口特殊时再显式填写
models[].id	服务端实际模型 ID	必须与提供商返回值一致；优先用获取模型写入
models[].name	对话中的显示名称	可读名称，不影响服务端请求
reasoning	是否展示推理能力	只有模型确实支持时设为 true
input	输入模态	['text'] 或 ['text', 'image']
contextWindow	模型上下文窗口	使用提供商公布值，不要凭空调大
maxTokens	单次最大输出	必须小于模型/接口允许值
thinkingLevelMap	Wordless 深度到服务商参数的映射	允许 off、minimal、low、medium、high、xhigh、max；不支持的级别不写

图片模型配置在顶层使用 imageProviders，协议和能力分开声明。内置协议包括 openrouter-images、openai-images、google-interactions-images、dashscope-images 和 volcengine-images。能力字段决定图片工作台实际显示哪些比例、分辨率和高级参数，不能把供应商不支持的能力写成 true。

创建一个 OpenAI 兼容配置

内置提供商页面：API 密钥、自定义提供商配置与已启用模型分开管理。

1. 打开 设置 → 模型，先选择 对话 类型。
2. 点击 添加自定义 Provider，填写唯一的 Provider ID（只用字母、数字、.、_、-），选择头像并创建。
3. 在右侧填写 API 密钥。它不会回显到高级 JSON 中。
4. 自定义对话提供商填写 Base URL 后点击 获取模型，从远端目录加入需要的模型，再 应用到配置。
5. 仍需改协议、请求头或思考深度时，打开 自定义 Provider 配置 编辑 JSON。
6. 点击 保存。JSON 校验错误会直接显示在 API 密钥区域下方。
7. 在 已启用模型 中启用刚加入的模型；未启用的模型不会出现在对话输入区。
8. 回到对话输入区，点击模型名称直接选中；如果模型配置了 thinkingLevelMap，再从二级菜单选择思考深度。

OpenAI 兼容 Chat Completions 示例

{
  "name": "Company AI",
  "baseUrl": "https://model.example.com/v1",
  "api": "openai-completions",
  "headers": {
    "X-Client": "Wordless"
  },
  "models": [
    {
      "id": "chat-model-prod",
      "name": "Company Chat",
      "reasoning": true,
      "input": ["text", "image"],
      "contextWindow": 128000,
      "maxTokens": 16384,
      "thinkingLevelMap": {
        "off": "none",
        "low": "low",
        "medium": "medium",
        "high": "high"
      }
    }
  ]
}

配置图片模型

内置的 OpenRouter、OpenAI、Google、阿里云百炼和火山引擎只需要在 设置 → 模型 → 图片 中填写 API 密钥。百炼还需要选择地域并填写工作空间 ID。自定义网关或未收录模型可以使用下方结构：

自定义图片 Provider 示例

{
  "name": "OpenAI Images",
  "baseUrl": "https://images.example.com/v1",
  "api": "google-interactions-images",
  "models": [
    {
      "id": "studio-image-v1",
      "name": "Studio Image",
      "input": ["text", "image"],
      "output": ["image"],
      "capabilities": {
        "supportsTextToImage": true,
        "supportsReferenceImageEditing": true,
        "supportsMaskEditing": false,
        "supportsTransparentBackground": false,
        "maxReferenceImages": 3,
        "maxOutputImages": 1,
        "aspectRatios": ["1:1", "4:3", "3:4", "16:9", "9:16"],
        "resolutions": ["1K", "2K"],
        "outputFormats": ["png", "jpeg"],
        "qualityLevels": ["auto"],
        "supportsSeed": false,
        "supportsWatermark": false
      }
    }
  ]
}

图片协议	用途	默认 Base URL
openrouter-images	OpenRouter 专用 Images API，支持文生图与参考图	https://openrouter.ai/api/v1
openai-images	OpenAI GPT Image 的 generations/edits 接口	https://api.openai.com/v1
google-interactions-images	Google Nano Banana Interactions API	https://generativelanguage.googleapis.com/v1beta
dashscope-images	阿里云百炼通义万象	由地域和工作空间 ID 自动生成
volcengine-images	火山方舟豆包 Seedream	https://ark.cn-beijing.volces.com/api/v3

百炼使用内置配置时不要把工作空间 ID 写进 Base URL。选择北京或新加坡地域后，Wordless 会根据 connection.region 和 connection.workspaceId 生成对应接口地址；返回的临时图片地址会立即下载并保存，不会把短期网址留在项目中。

capabilities 是运行时契约，不只是界面标签。比例、分辨率、输出数量、参考图数量、格式、质量、Seed 和水印都会在请求发出前校验。自定义配置中没有明确支持的能力，应保持 false 或省略。启用后，在图片生成画布选择该模型。

内置提供商需要调整接口地址或单个模型能力时，不要重建提供商；打开 自定义 Provider 配置，使用 modelOverrides 覆盖已有模型。将某个思考级别设为 null 可以显式禁用继承级别。

自定义提供商页面：Provider ID、头像、API 密钥状态、JSON 编辑器和已启用模型。

只有当前选中的模型展开思考深度选项；未手动指定时默认使用「中」。

如何判断配置正确

✓

预期结果

发送一条短消息后，模型选择器显示已选模型且会话能返回内容；模型配置了有效 thinkingLevelMap 时才会出现对应子菜单。当前页面没有单独的连接测试按钮，实际短消息就是端到端验证。工具审批与模型请求是两条不同链路，模型可用不代表工具权限已开放。

常见配置问题

• 401/403： API 密钥无效、过期或没有该模型权限。
• 404： Base URL 多写或少写 /v1，或模型 ID 不存在。
• 连接超时： 检查代理、VPN、IPv6 路由和局域网服务监听地址。
• 返回 HTML： 你填的是控制台地址，不是 API 地址。
• 保存后模型列表为空： models 数组为空、尚未 应用到配置、JSON 校验失败，或尚未在已启用模型中启用。
• 获取模型按钮不可用： 当前不是自定义对话提供商，Base URL 不是有效的 http(s) 地址，或高级 JSON 有语法错误。
• 模型获取失败 / 目录为空： API 密钥无效、Base URL 不是 API 根地址、网络不可达，或该接口没有返回对话模型。需要非默认目录协议时检查 modelFetcher。
• 思考深度没有显示： 当前模型没有声明支持该能力；切换模型后会重新读取能力。

配置可用后，进入完成首次任务。需要自定义提供商字段的完整说明就留在本页。