跳到主要内容

config.json 配置参考

本文是 ~/.open-ace/config.json（Open ACE 服务端应用配置文件）的参考文档，覆盖当前示例文件（config/config.json.sample）的全部字段，并整理了 the former config/CONFIG_GUIDE.md (absorbed here) 中的行为说明。

位置与优先级​

  • 默认路径：~/.open-ace/config.json。目录可通过 OPENACE_CONFIG_DIR 环境变量重定位（Kubernetes 清单中设为 /home/open-ace/.open-ace，挂载 PVC）。
  • 配置优先级：环境变量 > config.json > 内置默认值。 已核实的消费方：
    • DATABASE_URL（或拆分形式的 DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD）优先于 config.json 中的 database.* —— docker entrypoint 与 scripts/shared/config.py 都按该顺序解析数据库连接。
    • 环境中设置了 SECRET_KEY 时优先于 secret_key 字段。
    • DATA_FETCH_INTERVAL / DATA_FETCH_ENABLED 优先于 data_fetch 段。
  • Docker 下，entrypoint 首次启动时根据环境变量生成 config.json（PORT 写入 server.web_port，SERVER_IP 拼出 server.server_url，缺失密钥自动生成并持久化）。容器自身固定监听 19888；PORT 只映射宿主机端口。
  • 与 ENV_REFERENCE.md 的分工：环境变量负责部署层关注点（端口、数据库、安全模式、密钥 —— Docker Compose 见 .env.example），config.json 负责应用行为（工作区、告警、集成、功能开关）。本文是 config.json 的权威字段表。
  • 应用读取方对 config.json 有最长 60 秒的缓存（app/utils/config.py），多数修改在一分钟内免重启生效。需要重启的例外：自主开发调度器只在启动时拉起（autonomous.enabled）。

顶层字段​

字段说明示例 / 默认值
host_name主机名标识，用于区分不同机器的数据。这是唯一的主机名字段，所有工具的数据都以它归属；请勿在 tools.* 下重复配置主机名。localhost, server-01
secret_keyFlask 会话签名密钥。SECRET_KEY 环境变量优先。谨慎轮换 —— 轮换会使所有已登录会话失效。随机字符串

server.*​

字段说明默认值
server.upload_auth_key上传认证密钥，用于验证远程机器上传的数据（/api/upload/batch 的 X-Auth-Key 头）随机字符串
server.server_url服务器地址，远程机器需要配置此地址http://192.168.1.100:19888
server.web_portWeb 服务端口19888
server.web_hostWeb 绑定地址0.0.0.0
server.events_ingest_key调度器 → Web 的 SSE 事件摄取共享密钥（自主开发活动面板）。至少 32 字符，过短将被忽略""
server.events_ingest_url调度器转发自主开发 SSE 事件的摄取 URL""
server.events_ingest_trusted_sources允许提交摄取事件的受信来源列表[]

database.*​

字段说明默认值
database.type数据库类型，可选 sqlite 或 postgresqlsqlite
database.pathSQLite 数据库路径（仅 SQLite 有效）~/.open-ace/ace.db
database.urlPostgreSQL 连接 URL（仅 PostgreSQL 有效）null

注意： 环境变量 DATABASE_URL 优先级高于配置文件。如果设置了 DATABASE_URL，将忽略配置文件中的数据库配置。

SQLite 配置示例：

{
  "database": {
    "type": "sqlite",
    "path": "~/.open-ace/ace.db"
  }
}

PostgreSQL 配置示例：

{
  "database": {
    "type": "postgresql",
    "url": "postgresql://user:password@localhost:5432/ace"
  }
}

workspace.*​

字段说明默认值
workspace.enabled是否启用 Workspace 功能false
workspace.urlWorkspace 服务地址http://localhost:8080
workspace.isolation用户之间的隔离：{"level": ..., "backend": ...}，见下表与 WORKSPACE_ISOLATION.md{"level": "none", "backend": "shared"}
workspace.port_range_start多用户模式下端口池起始端口3100
workspace.port_range_end多用户模式下端口池结束端口3200
workspace.max_instances最大同时运行的 webui 实例数30
workspace.idle_timeout_minutes空闲实例自动关闭时间（分钟）30
workspace.cleanup_interval_minutes空闲实例清理扫描间隔（分钟）5
workspace.token_secretToken 签名密钥（建议使用强随机字符串）""
workspace.webui_pathqwen-code-webui 安装路径（留空自动探测）""

多用户模式下，Open ACE 会为每个用户启动独立的 qwen-code-webui 进程，以该用户的 system_account 身份运行。这确保了：

  • 每个用户只能看到自己的 qwen 项目和对话历史
  • 用户操作会以正确的身份记录到 qwen 日志中
  • 多用户环境下的数据隔离和审计追溯

workspace.isolation：level 与 backend（每个 backend 只属于一个 level；不匹配的组合、已移除的旧键 multi_user_mode / required_isolation_level / os_user_confinement / sandbox_tier / confinement_* 都会让服务器拒绝启动并给出替代写法）：

levelbackend需要什么Docker 安装可用
noneshared无（默认）✅
os_userplain每用户系统账户 + openace-webui-launch wrapper（安装脚本提供）✅（root 叠加配置）
os_userbwrapLinux + systemd + bubblewrap ≥ 0.8 + webui_callback_url + 约束 wrapper❌
sandboxedlocal-gvisor同 bwrap + Docker + gVisor 运行时 + root 策略文件 local-gvisor 分节❌
sandboxedlocal-kata同 bwrap + Docker + /dev/kvm + Kata ≥ 3.32 + root 策略文件 local-kata 分节❌
sandboxedopensandboxKubernetes 上的 OpenSandbox + sandbox-backends.json 中的 webui_image + webui_callback_url✅

可选键：tier（仅 opensandbox）、limits（memory / cpu_percent / tasks）与 egress_allow（仅 bwrap / local-gvisor / local-kata）、container_webui（仅 local-gvisor / local-kata）。

单用户模式配置示例：

{
  "workspace": {
    "enabled": true,
    "url": "http://localhost:8080",
    "isolation": {"level": "none", "backend": "shared"}
  }
}

多用户模式配置示例：

{
  "workspace": {
    "enabled": true,
    "url": "http://localhost",
    "isolation": {"level": "os_user", "backend": "plain"},
    "port_range_start": 3100,
    "port_range_end": 3200,
    "max_instances": 30,
    "idle_timeout_minutes": 30,
    "token_secret": "generate-a-strong-random-secret-key-here"
  }
}

其他段落​

字段说明默认值
data_fetch.interval数据采集间隔（秒，最小 60）300
data_fetch.enabled是否启用应用内数据采集调度器true
quota_enforcement.interval配额执行扫描间隔（秒）60
quota_enforcement.enabled是否启用配额执行true
autonomous.enabled是否启用 AI 自主开发功能（需重启生效）true
autonomous.acceptance_verification_enabled自主开发流程合并后是否执行验收校验true
run_timeline.enabled是否持久化远程会话运行时间线false
model_gateway.enabled是否启用 LiteLLM 兼容模型网关false
policy.enabled是否启用中央策略与审批功能false
policy.approval_ttl_seconds策略审批的默认有效期（单条规则可覆盖）3600
insights.temperature / insights.max_tokens洞察生成的采样参数0.3 / 4096

data_fetch.* 与 quota_enforcement.* 可被 DATA_FETCH_INTERVAL / DATA_FETCH_ENABLED 与 QUOTA_ENFORCEMENT_INTERVAL / QUOTA_ENFORCEMENT_ENABLED 环境变量覆盖，优先级见上文。

alerts.*​

字段说明默认值
alerts.allow_private_webhook_urls是否允许告警 webhook 指向私网 / 回环 / 链路本地地址。默认关闭，用于阻断 SSRF 风险。false
alerts.dingtalk_webhook_secret钉钉自定义机器人"加签"密钥（全局，所有用户共用）。留空时按普通 webhook 发送；配置后发送前自动附加 timestamp / sign。也可在「告警偏好」里按用户设置各自的密钥（写入 webhook URL 的 openace_dingtalk_secret=<secret>，加密存储），其优先级高于此全局值。""
alerts.webhook_secret通用 webhook（非飞书 / 非钉钉）的 HMAC-SHA256 共享密钥。配置后对发送的请求体签名并把签名写入 X-OpenACE-Signature 头，接收方可据此校验请求来源；留空则不签名。""

默认情况下，告警 webhook 仅允许公开可达的 http(s) 地址。飞书 / Lark 和钉钉群机器人 webhook 可直接使用；如果你确实需要向内网地址推送，请显式打开 alerts.allow_private_webhook_urls，并在网络层自行控制访问范围。

tools.*​

字段说明默认值
tools.openclaw.enabled是否启用 OpenClawtrue
tools.openclaw.token_envOpenClaw API Token 环境变量名OPENCLAW_TOKEN
tools.openclaw.gateway_urlOpenClaw Gateway 地址http://localhost:18789
tools.claude.enabled是否启用 Claudetrue
tools.qwen.enabled是否启用 Qwentrue

feishu.* 与 dingtalk.*​

两个集成都覆盖导入会话中的用户/群名解析、手动或定时的组织架构同步，以及（钉钉）告警中心机器人推送；均不包含飞书 SSO 登录。完整字段表、配置步骤与排障见专属指南：

  • 飞书：feishu.app_id、feishu.app_secret、feishu.org_sync_enabled（默认 false）、feishu.org_sync_tenant_id（默认 1）、feishu.org_sync_interval_minutes（默认 60）—— 见 FEISHU_CONFIG.md
  • 钉钉：dingtalk.app_key、dingtalk.app_secret、dingtalk.org_sync_enabled（默认 false）、dingtalk.org_sync_tenant_id（默认 1）、dingtalk.org_sync_interval_minutes（默认 60）、dingtalk.org_sync_root_dept_id（默认 "1"）—— 见 DINGTALK_CONFIG.md

配置步骤​

  1. 复制示例配置文件：

    cp config/config.json.sample ~/.open-ace/config.json

  2. 编辑 ~/.open-ace/config.json：

    • 设置 host_name 为主机名
    • 生成随机的 upload_auth_key
    • 根据需要配置其他可选参数

  3. 启动服务：

    python3 server.py