配置文件

Hoshimi 的全部设置和渠道账号都保存在数据目录中的一个 JSON 文件 config.json 里。网页界面的 设置 和 渠道 页、hoshimi config 命令和管理 API 改的都是这同一个文件。大多数情况下不需要手动编辑它；本页是给需要直接查看或修改它的人准备的完整参考。

文件在哪里复制锚点链接

hoshimi config path

即使文件还不存在，这条命令也会打印它将要写入的绝对路径。所有命令和网页界面都使用这个文件，与当前工作目录无关。

设置环境变量 HOSHIMI_DATA_DIR 可以把整个数据目录搬到别处，配置文件始终是 <数据目录>/config.json。文件不存在时全部使用默认值。数据目录里的其他文件见数据目录与迁移。

三种修改方式复制锚点链接

最小示例复制锚点链接

{
  "server": {
    "access_token": "your-tool-access-key",
    "model_api_key": "your-model-api-key"
  },
  "providers": {
    "nvidia": {"accounts": [{"id": "nvidia-1", "api_key": "your-provider-api-key"}]}
  }
}

只需要写和默认值不同的键。上面的密钥都是占位符。仓库里的 config.example.json 列出了各渠道账号的字段形状，其中的凭据是演示值，不能直接使用。

结构复制锚点链接

Hoshimi 不认识的顶层键和字段在读取时被忽略，并且在下一次保存时被丢弃，不要在文件里存放自己的备注字段。

server复制锚点链接

security复制锚点链接

这三个键也接受单数写法 allow_cidr、allow_host、allow_origin，值也可以是一个用逗号分隔的字符串。保存时统一写成复数形式的列表。各项检查的细节见访问控制。

network复制锚点链接

network 里不能出现其他键。每个渠道可以在 providers.<id>.options.network 中单独覆盖这条策略，见网络与代理。

playground复制锚点链接

providers复制锚点链接

providers 以渠道 id 为键，每个渠道有三个字段：

规则：

• 不认识的渠道 id 被忽略。
• 一个启用但没有账号的渠道不会运行，免账号渠道除外。
• 网页上的 登录、添加账号 和 hoshimi login 会把账号写进这里，并自动把渠道设为启用；对同一身份重新登录会替换原账号而不是再加一个。

账号中 Hoshimi 通用读取的字段：

渠道选项中通用的：

各渠道专有的账号字段和选项（如 agg 的 base_url、preset、model_specs）见渠道下的各页。

校验复制锚点链接

保存（网页、API、hoshimi config set）和启动（hoshimi serve、hoshimi check）前都会整体校验，不通过时文件保持原样。可能的错误：

config.json 本身不是合法的 JSON（或不是一个 JSON 对象）时，服务器拒绝启动，并先把原文件复制为 config.json.corrupt-<UTC 时间>，错误信息中会给出副本的路径。修好或删除 config.json 后再启动。

何时生效复制锚点链接

通过网页或管理 API 保存时：

通过 hoshimi config set 或编辑文件修改的，都要重启服务器才生效。

用命令行查看和修改复制锚点链接

hoshimi config path                                   # 配置文件路径
hoshimi config show                                   # 完整配置，凭据显示为 ***
hoshimi config show --json
hoshimi config get server.port
hoshimi config set server.port 10601
hoshimi config set server.default_model "<provider>/<model>"
hoshimi config set security.allow_cidrs '["192.168.1.0/24"]'
hoshimi config set network '{"mode": "proxy", "proxy": "http://127.0.0.1:7890"}'
hoshimi config set providers.kilo.enabled false
hoshimi config set server.access_token null           # 清除
hoshimi check                                         # 校验配置并列出将要启用的渠道

• 键用点分隔，值能按 JSON 解析的就按 JSON 解析（数字、true/false、列表、对象），否则作为字符串。null（或 none）清除一个值。
• 写入前整体校验，所以互相依赖的键要一次写完。例如切换到代理模式时，把整个 network 对象一起设置，单独设置 network.mode proxy 会因缺少代理地址而被拒绝。
• show 和 get 把访问密钥、账号凭据和代理地址显示为 ***。get 读的是文件中实际写着的值，文件里没有的键会报 Unknown setting。
• 改完要重启服务器。完整的命令参考见命令一览。

文件的写入方式复制锚点链接

每次保存都先写入同目录下的临时文件再原子替换，避免写到一半的文件。文件中有明文刷新令牌，保存后会尽量把权限设为仅所有者可读写（0600），在不支持权限位的文件系统（Windows、部分网络挂载）上跳过。把它当作凭据文件对待，不要分享填好的配置。