设置与环境变量

分层 settings

优先级从低到高（后者覆盖前者）：

层	路径	用途
user	$FORGEAX_CONFIG_DIR/settings.json 或 ~/.forgeax/settings.json	全局偏好
project	<cwd>/.forgeax/settings.json	团队共享（可进 git）
local	<cwd>/.forgeax/settings.local.json	本机私有（写时自动 gitignore）

合并语义：对象递归深合并、数组合并去重、标量覆盖。

示例

~/.forgeax/settings.json：

{
  "model": "claude-opus-4-8",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Read", "Bash(git *)"],
    "ask": ["Bash(git push*)"],
    "deny": ["Bash(rm *)", "Write(/etc/*)"]
  },
  "sandbox": {
    "enabled": false
  }
}

目录结构

~/.forgeax/                 # 或 $FORGEAX_CONFIG_DIR
  settings.json
  skills/
  commands/
  mcp.json

<project>/.forgeax/
  settings.json             # 可提交
  settings.local.json       # 本机
  skills/
  commands/
  mcp.json
  sessions/                 # WAL
  memory/                   # auto-memory

环境变量

变量	作用
ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL	Anthropic Messages 族凭证与端点
OPENAI_API_KEY / OPENAI_BASE_URL	OpenAI 兼容族（需 FORGEAX_PROVIDER_API=openai-compat）
FORGEAX_PROVIDER_API	强制 provider 后端 id（如 openai-compat、anthropic-messages、gemini）
FORGEAX_MODEL	默认模型（可被 --model 覆盖）
FORGEAX_CONFIG_DIR	全局配置根（默认 ~/.forgeax）
FORGEAX_MEMORY_DIR	auto-memory 目录
FORGEAX_SANDBOX	启用 OS Bash 沙箱
FORGEAX_SEARCH_URL	web_search 后端
BRAVE_API_KEY	可选搜索后端
FORGEAX_NO_TUI	禁用 Ink TUI
FORGEAX_MCP_ALLOW_WRITES	mcp-serve 允许改动型工具
FORGEAX_CORE_SOCK	--serve 的 sock 路径兜底

宿主（如 Studio）若使用代理网关，应把代理配置翻译成上面这些中立变量再注入；CLI 本身不绑定某一家代理产品名。

模型选择

forgeax --model claude-opus-4-8
forgeax --model gpt-4.1                 # 名称前缀会推断 openai-compat
export FORGEAX_PROVIDER_API=openai-compat   # 端点协议无法从模型名推断时显式声明

下一步

• 权限 — permissions.* 规则细节
• MCP — mcp.json 形状
• CLI 参考 — 全量 flag