想把 Jev 聊天助手接到自己的模型，通常不是改一个“开关”，而是改配置文件里指向模型服务的三项：模型地址、模型名、密钥。不同项目的字段名不一样，先找示例配置和启动日志确认实际字段，改完发一条测试消息，再看模型服务端是否收到请求，而不是只看聊天界面能不能回话。

适用场景是自托管 Jev 后要接本地或自建的 OpenAI 兼容模型服务。操作上先定位示例配置，确认 base_url、model、api_key 一类字段的真实名称，改完启动服务并发测试消息。验证要看 Jev 日志和自己的模型服务访问日志是否同时出现请求。密钥不建议长期留在主配置文件里；字段名和回退方式需结合项目版本确认。

在项目里定位配置文件与示例配置，先备份一份

在项目根目录先找配置文件和示例配置，不要直接改正在运行的主配置。常用查找命令如下，先看文件名再决定打开哪个。

find . -maxdepth 3 -type f | grep -Ei 'config|env|yaml|yml|toml|json' | sort

更可靠的做法是找示例配置对照：.env.example、config.example.yaml、settings.example.toml 这类文件通常会列出模型地址、模型名、密钥的占位字段。如果没有示例，可以在代码里搜关键词辅助定位，但不要只凭搜索结果就改。

grep -RIn -e 'api_key' -e 'base_url' -e 'model' `--exclude-dir`=node_modules `--exclude-dir`=.git . | head -50

改动前先备份。假设主配置是 config.yaml，在项目根目录执行：

cp -a config.yaml config.yaml.bak
cp -a .env .env.bak 2>/dev/null || true

如果配置在 config/ 子目录，备份路径也要对应，例如 cp -a config/app.yaml config/app.yaml.bak。备份文件不要提交到版本库。

按通用骨架写模型地址、模型名、密钥三项占位配置

需要改的通常是三类字段：模型服务地址、模型名、密钥。下面只是通用骨架，字段名必须替换成项目示例配置里的实际名称，不要照抄。

# 通用占位，字段名以项目内示例配置为准
model:
  base_url: 'http://127.0.0.1:8000/v1'
  name: 'your-model-name'
  api_key: 'sk-placeholder'

# 也有些项目用环境变量或扁平写法：
# MODEL_BASE_URL=http://127.0.0.1:8000/v1
# MODEL_NAME=your-model-name
# MODEL_API_KEY=sk-placeholder

模型地址一般指向自己模型服务的 OpenAI 兼容接口，或者项目文档里说明的接入路径；模型名要填模型服务实际提供的标识，不是随便起一个显示名。如果本地模型服务不校验密钥，api_key 可以留空或保留占位，但字段本身建议先留着。部分项目还有 provider 或 type 字段，需要从示例配置里确认是否要改成 openai_compatible、custom 一类值。改完后检查 YAML 缩进、冒号后空格和引号，避免启动时报解析错误。

启动后发一条测试消息，从日志确认请求走了自己的模型服务

改完配置后按项目原有方式启动服务，不要用猜测的启动参数。常见启动命令如下，实际用哪一种看项目 README 或原有脚本。

# 三选一，按项目实际方式
docker compose up -d
python -m app
pnpm start

日志要同时看两边：Jev 应用日志和自己的模型服务访问日志。应用日志常见查看方式：

docker compose logs -f app
tail -f logs/app.log

自己的模型服务如果是本地进程，直接在启动窗口看请求记录；如果用 nginx 或 uvicorn，看对应 access log。然后在 Jev 聊天界面发一条测试消息，例如“你好，请回复 ok”。预期特征是聊天界面有正常回复，同时模型服务端出现对应时间的请求记录，请求路径类似 /v1/chat/completions，请求体里的模型名和配置文件里填的一致。如果应用日志里出现连接被拒绝、401、404 或超时，说明模型地址、密钥或模型名至少有一项没对上。

把密钥移出主配置文件，检查是否会被版本控制带出去

密钥写进主配置文件容易随代码提交，建议改成环境变量或本地未跟踪文件。主配置里只保留引用占位，真实值放本地文件。

# .env，本地文件，不提交
MODEL_API_KEY=sk-your-key
MODEL_BASE_URL=http://127.0.0.1:8000/v1
MODEL_NAME=your-model-name

主配置里引用环境变量，写法看项目支持哪种，常见是 ${MODEL_API_KEY} 或 ${env:MODEL_API_KEY}：

api_key: ${MODEL_API_KEY}
base_url: ${MODEL_BASE_URL}
name: ${MODEL_NAME}

如果项目不支持环境变量插值，可以把密钥放到本地覆盖文件，例如 config/local.secret.yaml，再把该文件加入忽略规则。检查方式：

git check-ignore -v .env config/local.secret.yaml
git status `--short`
git grep -n -e 'sk-' -e 'api_key' -- . ':!*.example'

如果 .env 之前已经被跟踪，需要先 git rm `--cached` .env，再确认 .gitignore 里有 .env、*.local.*、config/*.secret.* 这类规则。历史提交里的密钥是否要清理，要结合仓库权限和协作情况谨慎处理。

配置写错导致启动失败时按日志定位并回退

配置写错后不要反复重启猜原因，先看启动日志的最后一段。按日志里给出的字段名和行号回到配置文件对应位置修改。

docker compose logs `--tail`=50 app
tail -n 50 logs/app.log

常见报错包括 YAML 解析错误会带行号，字段缺失会带字段名，地址写错会显示连接被拒绝。定位顺序是：记录日志里的字段名和行号，打开配置文件找到那一行，检查缩进、冒号后是否有空格、引号是否成对，以及引用的环境变量是否真的存在。一次只改一处，改完重启再看日志。

如果短时间定位不了，直接回退到备份配置，先恢复可用状态：

cp -a config.yaml.bak config.yaml
cp -a .env.bak .env 2>/dev/null || true

回退后重新启动服务，确认能正常发消息，再把改动拆小，每改一项启动一次。这样即使某一项字段名写错，也能从日志里快速看出是哪次改动引起的。