配置第一个模型

当前数据目录里没有 state/models.yaml 时，Foxwarm 会打开首次设置，直到你保存一份有效的模型配置为止。

用安装脚本输出的登录链接打开 WebUI。如果找不到链接，见打开 WebUI。

添加服务商

首次设置会直接打开 Setup → Models，里面是一个简短的表单：

Service：选择 OpenAI、Anthropic、OpenRouter、DeepSeek、Ollama，或者选 Other service 填写任意兼容端点。选择服务会自动填入 API 类型和基础地址，两者都可以修改。
API type：OpenAI-compatible (Chat Completions)、OpenAI Responses 或 Anthropic Messages。
API key：托管服务必须填写；Ollama 这类本地服务可以留空。
Models：点 Load models 获取服务提供的模型列表再选择，或者直接输入准确的模型 ID 后按回车。如果服务报告了模型的上下文和输出上限，或者说明模型不能读取图片，Setup 会把这些信息和该模型一起保存。
Default model：新对话默认使用的模型。

点 Test connection 会向默认模型发送一条简短消息，确认无误后点 Save models。如果 API Key 仍是占位符，或者需要密钥的托管服务没有填写密钥，首次设置不会完成。

表单会替你生成 models.yaml。随时可以切换到 YAML 直接查看或编辑文件；别名、故障切换、多个服务商和其他模型选项也都在 YAML 里配置。已保存的文件用到这些设置时，Setup 会以 YAML 打开它，保证不丢失任何内容。

同样的配置写成 YAML 是这样：

default: my-provider/my-model
providers:
  my-provider:
    providerType: openai-completions
    baseUrl: https://api.example.com/v1
    apiKey: replace-with-your-key
    models:
      - my-model

实现 Responses API 的端点用 openai-responses，Anthropic 兼容端点用 anthropic。本地的 OpenAI 兼容网关如果不需要密钥，apiKey 可以留空。Save models 会校验 YAML 并解析模型条目；只有 Test connection 或你发出的第一条消息才会真正请求服务商。

Setup 用到的文件

模型配置：foxwarm-data/state/models.yaml
应用和渠道配置：foxwarm-data/state/config.yaml
WebUI 访问令牌：foxwarm-data/state/token

如果你选择了自定义数据目录，这些路径也随之变化。

在新安装中，首次 Setup 保存模型时还会创建 state/config.yaml，其中包含 sessionAutoTitle: true，即在每个新会话第一次回复后自动为它命名。已有的 config.yaml 不会被修改，包括你事先创建的文件（例如为了设置 httpPort）。如果你自己创建 models.yaml 跳过了首次 Setup，就不会创建这个文件；在 config.yaml 中加入 sessionAutoTitle: true 即可开启自动标题。没有这一项时，会话会一直显示 ID，直到你重命名。

第一次对话

首次设置保存模型配置时，Foxwarm 会为 main Agent 创建默认会话 main，关闭 Setup 后就会打开它。会话里预先准备了一段欢迎消息，语言跟随浏览器（中文或英文，其他语言显示英文），所以即使服务商还没有回复也能看到。回复一个不需要工具的小问题，或告诉它你希望怎么被称呼；这次回复同时也是对服务商连接的简单实测。之后可以在你放心让 Agent 访问的目录里，试一个文件或命令相关的小任务。

已经有会话的安装，以及之后再次保存模型配置，都不会创建或修改任何会话。要开始新的对话，点会话列表上方的 +。

模型配置完成后，内置的 about-foxwarm Skill 可以讲解各项概念，并指引你了解更深入的功能。

排查问题

如果 API Key 被拒绝或模型 ID 不存在，回复会立即失败，并说明原因、提供打开模型设置的入口。到 Setup → Models 修正密钥或模型即可。
第一条消息因其他原因失败时，检查服务商类型、API 基础地址、模型 ID 和凭据。Test connection 会显示服务商返回的信息。
在 Docker 里，localhost 指的是容器本身。请使用主机可达的地址，例如在支持的环境中使用 host.docker.internal。
如果手动编辑的配置导致无法完成设置，修正或删除数据目录里的 state/models.yaml，即可回到首次设置。
如果 WebUI 没有任何回复，查看 foxwarm-data/state/logs/。

基本对话正常后，可以参考模型选项与路由（英文），了解推理强度、别名、故障切换、托管搜索和图像生成。