GOD环境变量与配置完全参考:.env、.god目录与OpenAI兼容模型接入一文搞懂
GOD环境变量与配置完全参考:.env、.god目录与OpenAI兼容模型接入一文搞懂
GOD 是一个 Govern, Observe, Direct 的 Agent Society 实时控制台。本文带你一次性看懂 GOD 环境变量与配置体系:如何用 .env 文件接入 OpenAI 兼容模型、.god 目录如何决定运行哪个实验,以及端口、浏览器、跳过依赖检查等常用参数如何调优,新手也能快速上手。
GOD 配置体系全景:.env 与 .god 各管什么
GOD 把「机器配置」和「实验选择」分开管理,这是理解整个配置系统的关键:
| 层级 | 文件 | 职责 |
|---|---|---|
| 模型与端口 | .env |
保存 API key、base URL、模型名和端口,由 .env.example 创建,被 Git 忽略 |
| 当前实验 | .god/current_experiment.json |
记录当前激活的实验,start、open、new-run 都读它 |
| 一次性覆盖 | 命令行环境变量 | 如 GOD_EXPERIMENT,仅对当次命令生效 |
也就是说:.env 只决定「用哪个模型、监听哪些端口」,而「跑哪个地图/剧本」由 .god 目录说了算,两者互不干扰。
一分钟接入 OpenAI 兼容模型:.env 必备三项
任何支持 /v1/chat/completions 的 OpenAI 兼容接口(如 OpenAI、通义千问、Claude 网关等)都可以。首次运行 ./scripts/god.sh start 时会自动从 .env.example 创建 .env,也可以在配置向导里直接填写。
必需的三个变量:
| 变量 | 默认值 | 说明 |
|---|---|---|
GOD_LLM_API_KEY |
空 | OpenAI 兼容 API key,模型运行前必填 |
GOD_LLM_API_BASE |
https://api.openai.com/v1 |
任意 OpenAI 兼容 endpoint |
GOD_LLM_MODEL |
空 | 主聊天模型,示例:qwen-plus、gpt-4o-mini |
配置向导界面如下,填写后点击保存即可:
💡 API key 只保存在本地
.env中,浏览器端只会拿到脱敏后的状态,不用担心泄露。
Embedding 模型与可选变量:按需覆盖更省成本
除了主聊天模型,GOD 还内置了 embedding 与轻量模型槽位。留空即自动复用主模型配置,需要分开时才覆盖:
| 变量 | 默认值 | 说明 |
|---|---|---|
GOD_EMBEDDING_API_KEY |
复用 GOD_LLM_API_KEY |
embedding 服务 key(可选覆盖) |
GOD_EMBEDDING_API_BASE |
复用 GOD_LLM_API_BASE |
embedding 服务地址(可选覆盖) |
GOD_EMBEDDING_MODEL |
text-embedding-3-large |
embedding 模型 |
GOD_LLM_NANO_MODEL |
复用 GOD_LLM_MODEL |
可选高频小模型槽位 |
完整变量清单可查阅官方文档:docs/developer/zh/env-vars.rst。
端口与启动参数:解决端口冲突的完整清单
本地栈包含后端、控制台和 JiuwenClaw runtime 多组服务,默认端口如下,冲突时可在 .env 中覆盖:
| 变量 | 默认端口 | 对应服务 |
|---|---|---|
GOD_BACKEND_HOST / GOD_BACKEND_PORT |
127.0.0.1 / 8001 |
FastAPI 后端 |
GOD_FRONTEND_PORT |
5174 |
GOD 控制台(PixelReplay 等页面) |
RUNTIME_AGENT_PORT |
19092 |
JiuwenClaw agent WebSocket |
RUNTIME_WEB_PORT |
20000 |
JiuwenClaw web 服务 |
RUNTIME_GATEWAY_PORT |
20001 |
JiuwenClaw gateway |
RUNTIME_UI_PORT |
6173 |
Runtime UI |
另外三个实用开关:
GOD_OPEN_BROWSER=0—— 禁止自动打开浏览器,适合 SSH 远程场景GOD_SKIP_SETUP=1—— 依赖已就绪时跳过依赖检查,加快启动GOD_PRIME_FIRST_STEP—— 设为0可跳过自动预跑第一步
配置完成后,./scripts/god.sh status 可确认 backend、control room、runtime 各端口全部 up。控制台最终效果:
.god 目录详解:当前实验指针与本地状态边界
.god/ 是 GOD 的本地状态目录(由 scripts/god.sh 定义),包含:
current_experiment.json—— 当前实验指针,记录hypothesis_id、experiment_id和 workspace 路径logs/—— 服务日志,可用./scripts/god.sh tail跟随pids/、run/—— 进程与运行状态
配置向导点击 Save and Launch 后会写入 .god/current_experiment.json,脚本随后启动该实验——而不是靠 .env 决定实验选择。
⚠️ 注意:.env、.god/、.live/ 均为本地运行状态,属于 Git 边界内文件,切勿提交到仓库(详见 docs/developer/zh/installation.rst)。
命令行一次性覆盖:不改动 .god 也能临时换实验
想临时跑另一个内置实验而不修改当前指针,直接在命令前加环境变量即可:
GOD_EXPERIMENT=pku_trump_visit GOD_EXPERIMENT_RUN=1 ./scripts/god.sh new-run
启动后访问 http://127.0.0.1:5174/pixel-replay/pku_trump_visit/1 即可看到北大校园实验。此机制在 docs/developer/zh/experiment-contract.rst 中有完整说明。
兼容旧变量与常见疑问
旧变量名还能用吗? 能。scripts/god.sh 会自动接受旧的 AGENTSOCIETY_* 和 JIUWENCLAW_* 命名并映射为 GOD_* 值,老配置无需手动迁移。
.env 和 .god 冲突时听谁的? 模型和端口听 .env,实验选择听 .god/current_experiment.json,除非命令行显式设置 GOD_EXPERIMENT。
如何重新切换内置实验? 运行 ./scripts/god.sh configure 重新打开配置向导即可。
掌握以上三层结构——.env 管模型与端口、.god 管实验指针、命令行管一次性覆盖——你已具备完整调优 GOD 环境的全部知识。更多细节可延伸阅读:docs/developer/zh/configuration.rst、docs/developer/zh/quickstart.rst 和 docs/developer/zh/commands.rst。



