GOD环境变量与配置完全参考:.env、.god目录与OpenAI兼容模型接入一文搞懂

原创2026-10-15 06:44:411,851 阅读

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 目录说了算,两者互不干扰。

GOD Agent Society 实时控制台主界面

一分钟接入 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

配置向导界面如下,填写后点击保存即可:

GOD 配置向导中填写 OpenAI 兼容模型 API 配置

💡 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 控制台面板展示地图与实时 Agent 社会运行状态

.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 中有完整说明。

GOD 内置 PKU 实验地图预览

兼容旧变量与常见疑问

旧变量名还能用吗? 能。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。

登录后查看全文
GOD