OpenGauss配置完全指南:~/.gauss/config.yaml与环境变量参数逐项详解

原创2026-10-12 17:43:071,370 阅读

OpenGauss配置完全指南:~/.gauss/config.yaml与环境变量参数逐项详解

OpenGauss 是 Math, Inc. 推出的项目级 Lean 工作流编排器,为 gauss 命令提供多智能体前端,驱动 prove、draft、review、formalize 等 AI 证明与形式化工作流。本文是一份面向新手的 OpenGauss 配置指南,将 ~/.gauss/config.yaml 的每个配置段与 .env 环境变量逐项详解,帮你快速完成模型、终端后端、工具集等核心参数的设置。

OpenGauss配置指南项目标识

OpenGauss 的三大配置文件与加载优先级

OpenGauss 把"设置"和"密钥"分开管理,理解下面三个文件是掌握配置的第一步(定义见 gauss_cli/config.py):

文件 位置 用途
config.yaml ~/.gauss/config.yaml 用户级主配置:模型、终端、工具集等所有行为设置
cli-config.yaml 仓库根目录 项目级配置,用户配置不存在时作为兜底
.env ~/.gauss/.env API 密钥与敏感信息,优先级最高

加载顺序(优先级从高到低):

  1. 环境变量(.env 中定义)——最高优先级,可覆盖一切文件配置
  2. ~/.gauss/config.yaml——用户配置,优先加载
  3. ./cli-config.yaml——项目配置,仅在用户配置不存在时生效
  4. 代码内置默认值

这一逻辑实现在 cli.py 的 load_cli_config 中。仓库根目录提供了两份"注释版模板",是学习配置的最佳入口:

💡 提示:设置 GAUSS_HOME 环境变量可整体更换配置目录(默认 ~/.gauss),多套 OpenGauss 并行安装时尤其有用。

一键编辑配置:gauss config 常用命令

不必手动打开文件,gauss 提供了一组配置命令(详见 website/docs/user-guide/configuration.md):

gauss config                                  # 查看当前配置
gauss config edit                             # 用编辑器打开 config.yaml
gauss config set model anthropic/claude-opus-4.6   # 修改单个值
gauss config set OPENROUTER_API_KEY "sk-..."  # 设置环境变量
gauss setup                                   # 重跑安装向导

gauss config set 很聪明:密钥类变量自动写入 .env,行为类参数自动写入 config.yaml,无需自己判断该改哪个文件。

config.yaml 核心参数逐项详解

以下按 cli-config.yaml.example 的分区逐项讲解,只保留新手最常需要动到的部分。

模型与推理提供商:model 段

model:
  default: "anthropic/claude-opus-4.6"   # 默认模型,可被 --model 覆盖
  provider: "auto"                        # 推理来源
  base_url: "https://openrouter.ai/api/v1"

provider 可选值(见 cli-config.yaml.example):

值 说明 需要的密钥
auto(默认) 已登录 Nous Portal 则用它,否则走 OpenRouter 视情况
openrouter 固定使用 OpenRouter OPENROUTER_API_KEY
nous-api Nous Portal API 方式 NOUS_API_KEY
nous Nous Portal(需 gauss login) —
zai 智谱 GLM 系列 GLM_API_KEY
kimi-coding Kimi / Moonshot KIMI_API_KEY
minimax / minimax-cn MiniMax 国际 / 国内端点 MINIMAX_API_KEY / MINIMAX_CN_API_KEY

若主力模型故障,可在 config.yaml 中加 fallback_model(provider + model)实现自动切换。

OpenRouter 路由策略:provider_routing 段

通过 OpenRouter 时可用 provider_routing 控制流量在多家供应商间的分配(cli-config.yaml.example):

  • sort: price / throughput / latency
  • only / ignore: 允许或跳过指定供应商
  • data_collection: "deny":排除可能存储数据的供应商

终端执行后端:terminal 段

terminal.backend 决定智能体在哪执行命令,共 6 种选项(cli-config.yaml.example):

backend 场景 关键参数
local(默认) 本机直接执行 cwd、timeout
ssh 远程服务器沙箱 ssh_host、ssh_user、ssh_key
docker 可复现容器隔离 docker_image、docker_volumes
singularity HPC 集群 singularity_image
modal 云端 GPU / 弹性算力 modal_image
daytona 云端持久工作区 daytona_image、DAYTONA_API_KEY

通用参数建议新手记住这四个:

terminal:
  backend: "local"
  timeout: 180                    # 单条命令超时(秒)
  lifetime_seconds: 300           # 闲置环境自动回收
  container_persistent: true      # 容器文件系统跨会话保留

容器类后端还有 container_cpu / container_memory / container_disk 资源上限。⚠️ 注意 sudo_password 是明文存储,官方强烈建议改用 SSH 免密 sudo 或交互式提示。

长对话自动压缩:compression 段

对话接近模型上下文上限时,中间轮次会被小模型自动摘要,保住"开头 3 轮 + 最近 4 轮"(cli-config.yaml.example):

compression:
  enabled: true
  threshold: 0.85        # 用掉 85% 上下文时触发,调小更激进
  summary_model: "google/gemini-3-flash-preview"  # 摘要用小模型更省钱

持久记忆与会话重置:memory 与 session_reset 段

  • memory:两段式记忆(MEMORY.md 智能体笔记 + USER.md 用户画像),memory_char_limit: 2200、user_char_limit: 1375 控制体量,nudge_interval: 10 每 10 轮提醒智能体保存记忆
  • session_reset:聊天平台会话自动清空策略,mode 取 both(闲置 + 每日)、idle、daily 或 none,重置前智能体会先把重要信息写入持久记忆

智能体行为与工具集:agent、toolsets 段

agent:
  max_turns: 60            # 单轮对话最大工具调用次数
  reasoning_effort: "medium"  # xhigh/high/medium/low/minimal/none
  personalities: { ... }    # 内置 helpful、concise、noir、pirate 等 12 种人格

toolsets 控制智能体能用什么工具:all 全开,或按需组合 web、terminal、file、browser、vision、image_gen、tts、cronjob 等;safe(无终端)、debugging(terminal+web+file)是常用预设。聊天平台可单独限权,例如给 Discord 只留只读工具:

platform_toolsets:
  discord: [web, vision, skills, todo]

用 gauss chat --list-toolsets 可查看完整清单。

展示、语音与其他可选段

段 作用 常用项
display 界面外观 tool_progress(off/new/all/verbose)、skin(default/ares/mono/slate)、show_reasoning、bell_on_complete
stt 语音转文字 provider: local(免密钥 faster-whisper)/ groq / openai
code_execution 代码执行沙箱 timeout: 300、max_tool_calls: 50
delegation 子智能体委派 可为子智能体指定更便宜的 model
browser 浏览器工具 inactivity_timeout: 120
security tirith 命令安全扫描 tirith_enabled、tirith_fail_open
mcp_servers 接入 MCP 外部工具服务器 见 website/docs/reference/mcp-config-reference.md

.env 环境变量高频参数速查

所有变量写入 ~/.gauss/.env(模板见 .env.example),完整参考在 website/docs/reference/environment-variables.md:

变量 说明
OPENROUTER_API_KEY OpenRouter 密钥,最通用的一条
LLM_MODEL 默认模型名(config.yaml 未设置时生效)
GLM_API_KEY / KIMI_API_KEY / MINIMAX_API_KEY 各家模型提供商密钥
OPENAI_API_KEY + OPENAI_BASE_URL 自定义 OpenAI 兼容端点(vLLM、SGLang 等)
FIRECRAWL_API_KEY 网页抓取工具
BROWSERBASE_API_KEY + BROWSERBASE_PROJECT_ID 云端浏览器自动化
FAL_KEY 图像生成
TERMINAL_TIMEOUT / TERMINAL_ENV 终端超时 / 强制后端类型
TERMINAL_SSH_HOST / TERMINAL_SSH_KEY SSH 后端连接信息
TELEGRAM_BOT_TOKEN、DISCORD_BOT_TOKEN、SLACK_BOT_TOKEN 聊天平台网关密钥
GAUSS_HOME 更换配置目录,支持多实例并存
GAUSS_INFERENCE_PROVIDER 命令行级覆盖 model.provider
GAUSS_MAX_ITERATIONS 覆盖 agent.max_turns
GAUSS_TIMEZONE IANA 时区,如 Asia/Shanghai
CONTEXT_COMPRESSION_THRESHOLD 覆盖压缩触发阈值

配置排错与最佳实践

  1. 改了没生效? 先跑 gauss doctor(gauss_cli/doctor.py)体检,再确认:环境变量 > 用户配置 > 项目配置的优先级,~/.gauss/config.yaml 存在时 cli-config.yaml 会被整体忽略。
  2. 密钥别写进 config.yaml——一律放 .env,权限默认 0600;~/.gauss/ 目录本身就是 0700(见 gauss_cli/config.py)。
  3. 最小化起步:新手先只配 model + terminal.backend: local + 一条模型密钥,其余保持默认,遇到问题再逐项加。
  4. 聊天平台防费用失控:保持 session_reset.mode: both 与 group_sessions_per_user: true,避免上下文无限增长。
  5. 多智能体并发:在 git 仓库中开启 worktree: true,每个 CLI 会话独占一个 worktree,互不冲突。

完整配置项的"注释百科全书"就在仓库里:cli-config.yaml.example(约 38KB,每个参数都有说明)和 .env.example。配合 website/docs/getting-started/start-here.md 的入门指南,你可以把 OpenGauss 调教成完全贴合自己工作流的形态。🚀

登录后查看全文
OpenGauss