跳转至

服务端配置

配置文件格式：YAML，默认文件名 server.yaml。

最小配置

server:
  host: 0.0.0.0          # 监听地址
  port: 8787              # 监听端口

storage:
  postgres_url: ${env.DATABASE_URL}   # PostgreSQL 连接串
  redis_url: ${env.REDIS_URL}         # Redis 连接串（可选）

paths:
  workspace_dir: /srv/openharness/workspaces       # project workspace 根目录
  chat_dir: /srv/openharness/chat-workspaces       # chat workspace 根目录
  template_dir: /srv/openharness/templates         # workspace 模板目录
  model_dir: /srv/openharness/models               # 平台模型目录
  tool_dir: /srv/openharness/tools                 # 公共 tool 目录
  skill_dir: /srv/openharness/skills               # 公共 skill 目录

llm:
  default_model: openai-default   # 默认模型名（须存在于 model_dir）

info 支持 ${env.VAR_NAME} 语法引用环境变量。

配置字段

server

字段 类型 默认值 说明
host string 127.0.0.1 监听地址
port number 8787 监听端口

storage

字段 类型 必填 说明
postgres_url string 是 PostgreSQL 连接串，唯一事实源
redis_url string 否 Redis 连接串，用于队列、锁、限流、SSE 事件分发

tip 不配置 Redis 时，Run 会在 API 进程内直接执行（适合本地开发）。配置 Redis 后支持多实例 Worker 消费队列。

paths

字段 类型 说明
workspace_dir string project workspace 根目录
chat_dir string chat workspace 根目录
template_dir string workspace 模板目录
model_dir string 平台模型定义目录
tool_dir string 公共 MCP tool server 定义目录
skill_dir string 公共 skill 目录

llm

字段 类型 说明
default_model string 默认模型名，须存在于 model_dir 中，运行时解析为 platform/<name>

目录说明

workspace_dir

每个直接子目录视为一个 project workspace。仅扫描一级子目录。

chat_dir

每个直接子目录视为一个只读 chat workspace。这些目录本身即可用的对话空间，不需要从模板创建。

template_dir

存放 workspace 模板。通过 POST /workspaces 创建新 workspace 时，从此目录选择模板作为初始化源。运行时不会把模板当作活跃 workspace 加载。

model_dir

扫描目录下的 *.yaml 文件。文件格式与 workspace 内 .openharness/models/*.yaml 一致。加载后以 platform/<name> 进入模型目录。

示例（model_dir/openai-default.yaml）：

openai-default:
  provider: openai
  key: ${env.OPENAI_API_KEY}
  name: gpt-5

tool_dir

公共 MCP tool server 定义。目录结构建议与 workspace .openharness/tools 保持一致（settings.yaml + servers/*）。由服务端统一加载，作为平台级能力参与 catalog 组装。

skill_dir

公共 skill 定义。与 workspace .openharness/skills 合并组成可见 skill 集合。同名 skill 中 workspace 级优先。

warning tool_dir 和 skill_dir 的内容主要在模板初始化时导入。workspace 运行时默认只使用自身 .openharness 目录中声明的能力。

运行模式

模式 启动方式 说明
API + embedded worker pnpm dev:server -- --config server.yaml 默认模式，一个进程包含 API 和 Worker
API only pnpm dev:server -- --config server.yaml --api-only 只启动 API，需配合独立 Worker
Standalone worker pnpm dev:worker -- --config server.yaml 独立 Worker，消费 Redis 队列

Schema

JSON Schema：schemas/server-config.schema.json