Skip to Content
FacetX

配置

本页面涵盖 FacetX 应用的所有配置层——config.yaml、前端环境变量、extensions_config.json 和运行时环境变量。

config.yaml

config.yaml 是 FacetX 的主要配置文件。所有 Agent 行为、模型选择、工具加载和运行时功能都由它控制。

参见配置参考页面了解文件格式和每个章节的详细说明。

模型提供商

models:
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true
    thinking_enabled: false

沙箱

# 本地开发（默认）
sandbox:
  use: FacetX.sandbox.local:LocalSandboxProvider
  allow_host_bash: false
 
# 基于容器（推荐用于多用户）
sandbox:
  use: FacetX.community.aio_sandbox:AioSandboxProvider
  replicas: 3
  idle_timeout: 600

工具

参见工具页面了解完整的工具配置参考。快速参考：

tools:
  - use: FacetX.community.ddg_search.tools:web_search_tool
  - use: FacetX.community.jina_ai.tools:web_fetch_tool
  - use: FacetX.sandbox.tools:ls_tool
  - use: FacetX.sandbox.tools:read_file_tool
  - use: FacetX.sandbox.tools:write_file_tool
  - use: FacetX.sandbox.tools:bash_tool

技能

skills:
  container_path: /mnt/skills
  # path: /custom/path/to/skills  # 可选；默认为仓库 skills/ 目录

技能可用性在 extensions_config.json 中管理（参见下方）。

数据库后端

FacetX 使用 database 配置同时管理 LangGraph 检查点数据和应用数据，例如运行记录、反馈和线程元数据。

默认使用 SQLite，适合本地开发和单节点单用户持久化：

database:
  backend: sqlite
  sqlite_dir: .facetx/data

SQLite 模式会把数据写入同一个 facetx.db 文件。它适合开发或单用户部署，但生产并发流量可能触发 SQLite 的单写者限制，出现 sqlite3.OperationalError: database is locked。

生产环境或多用户部署请使用 Postgres：

database:
  backend: postgres
  postgres_url: $DATABASE_URL
 
run_events:
  backend: db

在环境变量中设置 DATABASE_URL，例如 postgresql://user:password@localhost:5432/FacetX。

本地运行时安装 PostgreSQL 支持：

cd backend && uv sync --all-packages --extra postgres

Docker 或脚本启动场景，在安装或构建前设置 UV_EXTRAS=postgres。旧的独立 checkpointer 配置仍然兼容，但新的部署应优先使用 database。

前端环境变量

前端通过 .env.local（本地开发）或 Docker Compose 环境中的环境变量配置。

变量必需描述
BETTER_AUTH_SECRET是（生产）会话管理的密钥（最少 32 个字符）
BETTER_AUTH_URL推荐你的应用公开 URL（例如 https://your-domain.com）
SKIP_ENV_VALIDATION否设为 1 跳过构建时环境变量验证

本地开发：

# frontend/.env.local
BETTER_AUTH_SECRET=local-dev-secret-at-least-32-chars

不要在生产中使用 SKIP_ENV_VALIDATION=1。为 BETTER_AUTH_SECRET 设置一个真实值。

extensions_config.json

extensions_config.json 控制 MCP 服务器和技能的运行时启用状态，独立于 config.yaml。

默认位置：项目根目录（与 config.yaml 同一目录）。

MCP 服务器

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "enabled": true
    }
  }
}

不要为 FacetX 工作区文件引入 MCP filesystem server。它会与 FacetX 内置文件工具形成路径语义不同的重复能力，让 LLM 行为不稳定。FacetX 当前没有为 filesystem server 适配 MCP Roots 模式，也不会把 /mnt/user-data/… 这类沙箱路径映射成 @modelcontextprotocol/server-filesystem 可接受的路径。

技能启用状态

技能启用状态会反映在 extensions_config.json 中。你可以直接编辑它，或通过 FacetX 应用界面进行管理。

运行时环境变量

这些变量在 FacetX 进程中设置（通过 .env、Docker 环境或 shell）：

变量默认值描述
FACETX_CONFIG_PATH自动发现config.yaml 的绝对路径
LOG_LEVELinfo日志详细程度（debug/info/warning/error）
FACETX_ROOT仓库根目录用于 Docker 中的技能和线程挂载
Harness 配置部署指南
简介