命令参考

本页按用途列出全部命令。共同约定（配置从哪里读取、--json、退出码、日志）见命令行概览，环境变量见环境变量。

每条命令都接受下面两个选项，表格中不再重复：

参数写作 <name> 的是必填，[name] 是可选。

服务器复制锚点链接

serve复制锚点链接

启动服务器：兼容 OpenAI 与 Anthropic 的 API，加上 Web UI。

hoshimi serve [OPTIONS]

这些选项都只作用于本次启动，不会写入 config.json。--access-token、--model-api-key、--default-model 给空字符串时不起作用，沿用配置中的值。

启动过程：

1. 读取配置，叠加上面的选项，按配置构建渠道。
2. 地址不是本机回环地址（127.*、localhost、::1）时，打印警告。没有工具访问密钥时拒绝启动（退出码 4）；没有模型 API 密钥时警告外部模型接口不需要密钥即可调用。同时必须配置了 security.allow_cidrs，否则也拒绝启动（退出码 4）。见安全。
3. 绑定端口。端口被占用时依次尝试下一个，直到 65535，再从 1024 绕回；换了端口会警告 Port 10600 is unavailable. Using port 10601.。--strict-port 下只尝试一个端口。找不到可用端口时以退出码 3 结束。
4. 把地址写入数据目录的 server.json，在标准输出打印一行 SERVER_READY url=<地址>，并记录 Hoshimi running on <地址>。监听 0.0.0.0 或 :: 时，打印的地址用 127.0.0.1。
5. 启用了 --open 时，稍后在浏览器中打开这个地址。

按 Ctrl+C 停止；退出时删除 server.json。没有构建好的 Web UI（源码安装而未构建）时，日志警告一句并只提供 API。

hoshimi serve                                      # 默认：127.0.0.1:10600，打开浏览器
hoshimi serve --no-open --port 11000 --strict-port  # 固定端口，不打开浏览器
hoshimi serve --port 0                             # 任意空闲端口，看 SERVER_READY 这一行
hoshimi serve --no-ui                              # 只提供 API
hoshimi serve --default-model kilo-auto/free       # 请求不指定模型时用这个

检查与查看复制锚点链接

check复制锚点链接

检查配置并报告会提供哪些渠道和账户，不启动服务器。

hoshimi check [OPTIONS]

检查的内容与 Web UI 保存设置时相同：网络策略和代理地址、端口范围、各项上限、Playground 设置，以及安全规则（例如监听非本机地址必须同时配置 security.allow_cidrs 和 server.access_token；security.allow_origins 需要 server.access_token）。有问题时以退出码 2 结束并说明原因。

$ hoshimi check
ok: 2 provider(s), 0 account(s) — kilo:0 (keyless), opencode:0 (keyless)
config: /home/you/.local/share/hoshimi/config.json

每个渠道写作 <id>:<账户数>，不需要账户的渠道在没有账户时标为 (keyless)。一个渠道都没有启用时打印一行错误，退出码为 2。

--json 的字段：

使用 --json 时，即使没有启用任何渠道，退出码也是 0。

models复制锚点链接

列出可用模型，即 GET /v1/models 返回的同一份列表。

hoshimi models [OPTIONS]

表格有 Model 和 Provider 两列。多个渠道提供同一个模型 id 时只列出一次，归在排在前面的渠道下。

hoshimi models
hoshimi models --provider opencode
hoshimi models --json | jq -r '.[].id'

providers复制锚点链接

列出已配置的渠道，以及各自的账户数和模型数。

hoshimi providers [OPTIONS]

表格列为 Id、Name、Accounts、Models；被关闭的渠道在表格下方以 disabled: … 列出。账户数不包括匿名渠道内置的匿名身份。

--json 的结构：

{
  "providers": [
    {"id": "opencode", "display_name": "OpenCode Zen", "accounts": [], "keyless": true, "models": 9},
    {"id": "kilo", "display_name": "Kilo AI", "accounts": [], "keyless": true, "models": 17}
  ],
  "disabled": []
}

accounts 是账户 id 的列表，disabled 是被关闭的渠道 id 列表。模型数量取决于上游当时的目录。

stations复制锚点链接

列出 agg 账户可以作为 preset 使用的站点。

hoshimi stations [OPTIONS]

表格列为 Id、Name、Base URL、Key env，表格下面提示用法：

Use one in config.json:  "providers" → "agg" → "accounts" → {"preset": "<id>", "api_key": "..."}
The key env var is the name the upstream reads its key from; Hoshimi reads config.json only.

Key env 只是上游工具惯用的环境变量名，方便你知道去哪里找密钥；Hoshimi 不读取这些变量，密钥要写在 config.json 的账户里。--json 输出 {"stations": [...]}，每项有 id、display_name、base_url、key_env，以及 catalog_keyless（不带密钥也能获取模型列表）。用法和全部预设见 agg 聚合。

version复制锚点链接

显示 Hoshimi、Python 以及主要组件（fastapi、uvicorn、pydantic、typer、httpx、rich）的版本。

hoshimi version [OPTIONS]

没有安装的组件在表格中显示 not installed，在 JSON 中为 null。

env复制锚点链接

列出 Hoshimi 读取的环境变量，以及当前设置了哪些。

hoshimi env [OPTIONS]

第一张表 Environment variables 列出已知变量和说明；当前环境中设置了任何以 HOSHIMI_ 开头的变量时，第二张表 Set now 列出它们的值，名字含 TOKEN 或 KEY 的显示为 ***。各变量的含义见环境变量。

登录复制锚点链接

login复制锚点链接

登录一个站点（通过浏览器授权），站点返回凭据后，账户写入 config.json。

hoshimi login [OPTIONS] [PROVIDER]

支持交互登录的站点：anthropic、buddy、cline、codearts、codex、eac、gemini、github-copilot、kilo、kimi-coding、lobsterai、loomy、meta、minimax、openai、openrouter、qoder、qodercn、raccoon、radius、trae、workbuddy、xai、zcode。

流程：

1. 命令向站点请求登录链接，打印 Authorize at <链接>；设备码类站点还会打印 Authorization code: <代码> — <链接>，在授权页输入这个代码。
2. 启用 --open 时自动在浏览器中打开链接；打不开时提示手动访问。
3. 每 2 秒询问一次结果。成功时打印 Signed into <站点> as <账户 id>.，账户已写入配置；失败时以退出码 1 结束。
4. 10 分钟内站点没有答复则超时（退出码 1）。

用同一个站点身份再次登录，会替换原有账户，而不是再加一个。站点名不在列表中时退出码为 2。

hoshimi login                    # 列出支持登录的站点
hoshimi login cline              # 打开浏览器完成登录
hoshimi login codex --no-open    # 只打印链接，在别处打开
hoshimi login gemini --manual    # 浏览器在另一台机器上：完成后把回调 URL 粘贴回来

--manual 用于浏览器和 Hoshimi 不在同一台机器的情况：许多站点把授权结果回调到本机的回环端口，另一台机器上的浏览器到不了这个端口；这时把浏览器最终跳转到的回调 URL（或页面上的授权码）粘贴到提示中即可。各站点的登录方式和回调端口见免费站点。

运行中的服务器不会读取命令行登录写入的账户，重启后生效；在 Web UI 的 渠道 页登录则立即生效。

配置复制锚点链接

config 下的命令读写数据目录里的 config.json。键用点号分隔，例如 server.port、security.allow_cidrs、providers.kilo.enabled。全部键见配置。

config path复制锚点链接

打印配置文件的路径。文件还不存在时也会打印它将被创建的位置。

hoshimi config path

$ hoshimi config path
/home/you/.local/share/hoshimi/config.json

config show复制锚点链接

显示配置：配置文件存在时显示文件内容，不存在时显示默认值。凭据显示为 ***。

hoshimi config show [OPTIONS]

不带 --json 时，以带颜色的 JSON 显示，最后一行是配置文件路径。

config get复制锚点链接

打印一项设置，格式为 JSON。凭据显示为 ***。

hoshimi config get <KEY>

键不存在时报错 Unknown setting: <KEY>，退出码为 4。也可以取一整段：

$ hoshimi config get server.port
10600
$ hoshimi config get security
{
  "allow_cidrs": [],
  "allow_hosts": [],
  "allow_origins": []
}

配置文件不存在时，可以读取的是默认值中有的键（network、server、security 下的各项）。

config set复制锚点链接

修改一项设置并保存。

hoshimi config set <KEY> <VALUE>

hoshimi config set server.port 10600
hoshimi config set server.strict_port true
hoshimi config set server.default_model kilo-auto/free
hoshimi config set security.allow_cidrs '["192.168.1.0/24"]'
hoshimi config set security.allow_cidrs 10.0.0.0/8,192.168.0.0/16   # 安全列表也接受逗号分隔
hoshimi config set providers.kilo.enabled false
hoshimi config set server.model_api_key null                         # 清除

保存前，整份配置会按与 check 相同的规则检查，不通过时不写入并以退出码 2 报告原因，例如监听非本机地址但没有配置允许的网段和工具访问密钥。成功时打印 <KEY> = <新值>（凭据显示为 ***，清除时显示 (cleared)）。

需要注意：

• 文件会以 Hoshimi 自己的格式重写。Hoshimi 不认识的键不会被保存；渠道的 accounts 和 options 中的内容原样保留。
• 类型不对的值，有的会报错（例如 playground.max_steps 不是整数、server.access_token 不是字符串，退出码 2），有的会被忽略、保持原值（例如给 server.port 一个字符串），而命令仍然打印新值；改完后可以用 config get 确认。
• 修改在服务器重启后生效。在 Web UI 的 设置 页修改则立即生效（监听地址和端口除外）。
• 写在命令行里的密钥会留在 shell 历史中；介意的话改用 Web UI 设置。