OpenGauss配置完全指南:~/.gauss/config.yaml与环境变量参数逐项详解
OpenGauss配置完全指南:~/.gauss/config.yaml与环境变量参数逐项详解
OpenGauss 是 Math, Inc. 推出的项目级 Lean 工作流编排器,为 gauss 命令提供多智能体前端,驱动 prove、draft、review、formalize 等 AI 证明与形式化工作流。本文是一份面向新手的 OpenGauss 配置指南,将 ~/.gauss/config.yaml 的每个配置段与 .env 环境变量逐项详解,帮你快速完成模型、终端后端、工具集等核心参数的设置。
OpenGauss 的三大配置文件与加载优先级
OpenGauss 把"设置"和"密钥"分开管理,理解下面三个文件是掌握配置的第一步(定义见 gauss_cli/config.py):
| 文件 | 位置 | 用途 |
|---|---|---|
config.yaml |
~/.gauss/config.yaml |
用户级主配置:模型、终端、工具集等所有行为设置 |
cli-config.yaml |
仓库根目录 | 项目级配置,用户配置不存在时作为兜底 |
.env |
~/.gauss/.env |
API 密钥与敏感信息,优先级最高 |
加载顺序(优先级从高到低):
- 环境变量(
.env中定义)——最高优先级,可覆盖一切文件配置 ~/.gauss/config.yaml——用户配置,优先加载./cli-config.yaml——项目配置,仅在用户配置不存在时生效- 代码内置默认值
这一逻辑实现在 cli.py 的 load_cli_config 中。仓库根目录提供了两份"注释版模板",是学习配置的最佳入口:
- cli-config.yaml.example:完整的 config.yaml 注释模板
- .env.example:完整的环境变量注释模板
💡 提示:设置 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/latencyonly/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 |
覆盖压缩触发阈值 |
配置排错与最佳实践
- 改了没生效? 先跑
gauss doctor(gauss_cli/doctor.py)体检,再确认:环境变量 > 用户配置 > 项目配置的优先级,~/.gauss/config.yaml存在时cli-config.yaml会被整体忽略。 - 密钥别写进 config.yaml——一律放
.env,权限默认 0600;~/.gauss/目录本身就是 0700(见 gauss_cli/config.py)。 - 最小化起步:新手先只配
model+terminal.backend: local+ 一条模型密钥,其余保持默认,遇到问题再逐项加。 - 聊天平台防费用失控:保持
session_reset.mode: both与group_sessions_per_user: true,避免上下文无限增长。 - 多智能体并发:在 git 仓库中开启
worktree: true,每个 CLI 会话独占一个 worktree,互不冲突。
完整配置项的"注释百科全书"就在仓库里:cli-config.yaml.example(约 38KB,每个参数都有说明)和 .env.example。配合 website/docs/getting-started/start-here.md 的入门指南,你可以把 OpenGauss 调教成完全贴合自己工作流的形态。🚀
