设置与配置

本章介绍 AggRoot 的所有配置选项，包括环境变量、权限模式、安全设置和配置文件。

环境变量

AI 提供商（至少配置一个）

变量名	说明	示例
`DEEPSEEK_API_KEY`	DeepSeek API 密钥（默认提供商）	`sk-xxxxxxxx`
`ZHIPU_API_KEY`	智谱 AI API 密钥	`xxxxxxxx.xxxxxxxx`
`QWEN_API_KEY`	通义千问 API 密钥（也可用 `DASHSCOPE_API_KEY`）	`sk-xxxxxxxx`
`KIMI_API_KEY`	Kimi（Moonshot）API 密钥	`sk-xxxxxxxx`
`CLAUDE_API_KEY`	Anthropic Claude API 密钥	`sk-ant-xxxxxxxx`
`OPENAI_API_KEY`	OpenAI GPT API 密钥	`sk-xxxxxxxx`
`MINIMAX_API_KEY`	MiniMax API 密钥	`xxxxxxxx`
`MIMO_API_KEY`	小米 MiMo API 密钥	`xxxxxxxx`
`NVIDIA_API_KEY`	NVIDIA NIM API 密钥	`nvapi-xxxxxxxx`
`SILICONFLOW_API_KEY`	SiliconFlow API 密钥（免费模型可不填）	`sk-xxxxxxxx`

本地模型服务器

变量名	说明	默认值
`OLLAMA_BASE_URL`	Ollama 服务地址	`http://localhost:11434`
`OLLAMA_MODEL_NAME`	Ollama 模型名称	`llama3.2`
`VLLM_BASE_URL`	vLLM 服务地址	—

Shell 配置

变量名	说明	可选值	默认值
`DEFAULT_SHELL`	默认 Shell	`auto`, `powershell`, `cmd`, `bash`, `nushell`, `wsl`	`auto`
`SHELL_TIMEOUT`	Shell 命令超时（毫秒）	正整数	`30000`
`CODE_EXECUTION_TIMEOUT`	代码执行超时（秒）	正整数	`30`

会话管理

变量名	说明	默认值
`MAX_SESSION_HISTORY`	每个会话最大消息数	`50`
`SESSION_TIMEOUT`	会话超时（分钟）	`60`

日志

变量名	说明	可选值	默认值
`LOG_LEVEL`	日志级别	`debug`, `info`, `warn`, `error`, `fatal`	`info`

安全

变量名	说明	默认值
`SAFE_MODE`	是否启用安全模式	`true`
`DANGEROUS_COMMANDS`	危险命令黑名单（逗号分隔）	`rm -rf,format,del /f /q,shutdown,reboot`

视觉

变量名	说明	默认值
`BROWSER_TYPE`	浏览器类型	`chromium`
`BROWSER_HEADLESS`	是否使用无头浏览器	`true`

文件操作

变量名	说明	默认值
`MAX_FILE_SIZE`	最大文件大小（字节）	`10485760`（10MB）

.env 文件配置

将环境变量写入 .env 文件，AggRoot 启动时自动加载：

# === AI 提供商（至少配置一个） ===
DEEPSEEK_API_KEY=sk-your-deepseek-key
ZHIPU_API_KEY=your-zhipu-key
QWEN_API_KEY=sk-your-qwen-key
KIMI_API_KEY=sk-your-kimi-key
CLAUDE_API_KEY=sk-ant-your-claude-key
OPENAI_API_KEY=sk-your-openai-key
MINIMAX_API_KEY=your-minimax-key
MIMO_API_KEY=your-mimo-key
NVIDIA_API_KEY=nvapi-your-nvidia-key
# SILICONFLOW_API_KEY=（免费模型可不填）

# === 本地模型 ===
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL_NAME=llama3.2

# === Shell 配置 ===
DEFAULT_SHELL=auto
SHELL_TIMEOUT=30000
CODE_EXECUTION_TIMEOUT=30

# === 会话管理 ===
MAX_SESSION_HISTORY=50
SESSION_TIMEOUT=60

# === 日志 ===
LOG_LEVEL=info

# === 安全 ===
SAFE_MODE=true
DANGEROUS_COMMANDS=rm -rf,format,del /f /q,shutdown,reboot

Tips: 使用 cp .env.example .env 从示例文件创建，然后填入你的 API 密钥。.env 文件不应提交到版本控制。

权限模式

AggRoot 支持多种审批模式，控制工具执行前是否需要用户确认：

auto（自动模式 / YOLO 模式）

所有工具自动执行，无需确认
适合可信赖的环境和自动化场景
安全控制（DANGEROUS_COMMANDS 黑名单）仍然生效

/yolo
✅ YOLO mode enabled - tools will auto-execute

safe_only（安全模式）

低风险工具（riskLevel: low）自动执行
中高风险工具需要用户确认
适合日常开发

always_ask（始终确认）

所有工具执行前都需要用户确认
适合对安全性要求极高的场景

切换模式

/yolo          # 切换到自动模式
/yolo          # 再次输入切换回之前模式

或在代理配置中指定：

{
  "name": "my-agent",
  "approval_mode": "safe_only"
}

安全配置

SAFE_MODE

启用安全模式后，AggRoot 会对代码执行和 Shell 命令进行安全检查：

代码执行 — 限制可执行的代码类型和操作范围
Shell 命令 — 拦截危险命令模式

SAFE_MODE=true

DANGEROUS_COMMANDS 黑名单

通过 DANGEROUS_COMMANDS 配置要拦截的危险命令模式：

DANGEROUS_COMMANDS=rm -rf,format,del /f /q,shutdown,reboot

此外，AggRoot 内置了正则表达式模式匹配，会拦截以下高风险操作：

模式	说明
`rm -rf /`	递归删除根目录
`rm -rf ~`	递归删除用户目录
`mkfs`	格式化文件系统
`dd if=`	磁盘镜像操作
`curl ... \| sh`	管道执行远程脚本
`chmod 777 /`	危险权限修改
`shutdown / reboot`	系统关机/重启
`systemctl start/stop`	系统服务管理

风险等级

每个工具都有风险等级标记，影响审批流程：

等级	典型工具	safe_only 行为
`low`	Read, Glob, Grep, DirectoryTree	自动执行
`medium`	Write, Edit, GitCommit	需确认
`high`	Shell, GitPush, CodeExecute	必须确认

Settings.json

AggRoot 支持通过 settings.json 进行更细粒度的配置。

配置文件位置

层级	路径	作用
项目级	`.aggroot/settings.json`	仅对当前项目生效
全局级	`~/.aggroot/settings.json`	对所有项目生效

配置结构

{
  "permissions": {
    "approvalMode": "safe_only",
    "allowedTools": ["Read", "Write", "Edit", "Glob", "Grep", "Shell"],
    "blockedTools": [],
    "riskThreshold": "medium"
  },
  "hooks": {
    "beforeToolCall": "echo 'About to call {{toolName}}'",
    "afterToolCall": "echo 'Tool {{toolName}} completed'"
  },
  "env": {
    "DEEPSEEK_API_KEY": "sk-xxxxxxxx",
    "LOG_LEVEL": "debug"
  },
  "features": {
    "vision": true,
    "mcp": true,
    "skills": true,
    "memory": true
  }
}

字段说明

permissions — 权限配置

字段	类型	说明
`approvalMode`	string	审批模式：`auto` / `safe_only` / `always_ask`
`allowedTools`	string[]	允许使用的工具白名单
`blockedTools`	string[]	禁止使用的工具黑名单
`riskThreshold`	string	自动执行的风险阈值：`low` / `medium` / `high`

hooks — 钩子配置

字段	类型	说明
`beforeToolCall`	string	工具调用前执行的 Shell 命令
`afterToolCall`	string	工具调用后执行的 Shell 命令

钩子命令支持模板变量：

{{toolName}} — 工具名称
{{toolArgs}} — 工具参数（JSON）

env — 环境变量

在 settings.json 中也可以配置环境变量，优先级低于 .env 文件。

features — 功能开关

字段	类型	说明
`vision`	boolean	启用视觉分析功能
`mcp`	boolean	启用 MCP 集成
`skills`	boolean	启用技能系统
`memory`	boolean	启用记忆系统

查看当前配置

使用 /config 命令查看当前生效的配置：

Agent> /config

会显示当前模型、审批模式、已加载的插件、MCP 服务器等信息。

← 上一篇

插件开发

CLI 参考