⚙️ 配置文件

ClawGoal 通过 YAML 格式的配置文件进行服务端设置。本文档逐项说明所有配置字段的含义和用法。

配置文件位置

默认配置文件位于数据目录下：

~/.clawgoal/data/config.yaml

可以通过以下方式自定义数据目录：

1. 修改 config.example.yaml 中的 dataPath 字段（将文件复制到数据目录，重命名为 config.yaml 后生效）
2. 设置环境变量 DATA_PATH，优先级高于配置文件内的 dataPath

首次启动时，系统会自动在数据目录创建默认的 config.yaml。

配置总览

# yaml-language-server: $schema=./config.schema.json

配置文件由以下几个顶级模块组成，下面逐一说明。

Server（服务端基础）

port: 53001
timezone: 8
lang: en-US
# dataPath: ~/.clawgoal/data

Backup（自动备份）

backup:
enable: true
cron: 0 2 */3 * *
keepDays: 30

Database（数据库）

database:
provider: sqlite
url: file:./data/db/database.db
# url: "mysql://root:123456@localhost:3306/database?timezone=Asia/Shanghai"

系统默认用户和租户

supervisorUserId: 1
supervisorTenantId: 1

用于 setup.yaml 初始化、API Token 认证等系统级操作。一般情况下保持默认值即可。

Auth（用户认证）

auth:
type: fixed
userId: 1
tenantId: 1
username: user
password: password

JWT（令牌签名）

jwt:
secret: your-secret-key-change-in-production-2026

Logging（日志）

# log:
#   path: /custom/log/path/

Upload（文件上传）

通用配置

upload:
type: local
url: "http://localhost:53001/uploads/"
limitExt: "jpg,png,gif,svg,doc,docx,xls,xlsx"
limitSize: 1024000

本地存储（local）

upload:
type: local
local:
path: ""

阿里云 OSS

# upload:
#   type: aliyunOss
#   aliyunOss:
#     accessKeyId: your-access-key-id
#     accessKeySecret: your-access-key-secret
#     bucket: your-bucket-name
#     region: oss-cn-hangzhou
#     endpoint: ""

腾讯云 COS

# upload:
#   type: tencentCos
#   tencentCos:
#     secretId: your-secret-id
#     secretKey: your-secret-key
#     bucket: your-bucket-1234567890
#     region: ap-guangzhou

七牛云

# upload:
#   type: qiniu
#   qiniu:
#     accessKey: your-access-key
#     secretKey: your-secret-key
#     bucket: your-bucket-name
#     region: z0

AWS S3 / MinIO

# upload:
#   type: awsS3
#   awsS3:
#     accessKeyId: your-access-key-id
#     secretAccessKey: your-secret-access-key
#     bucket: your-bucket-name
#     region: us-east-1
#     endpoint: ""

Azure Blob Storage

# upload:
#   type: azureBlob
#   azureBlob:
#     accountName: your-account-name
#     accountKey: your-account-key
#     containerName: your-container-name
#     endpoint: ""

ModStart

# upload:
#   type: modstart
#   modstart:
#     baseUrl: "https://your-modstart-site.com"
#     apiMemberSecret: "your-api-member-secret"

Proxy（代理服务器）

proxy:
- name: local
type: http
host: 127.0.0.1
port: "7890"
username: user       # 可选
password: pass       # 可选

proxy 是一个数组，可配置多个代理条目。每个条目包含：

Model Providers（模型供应商）

模型供应商是 ClawGoal 的核心配置之一。每个供应商定义一个驱动（apiBase / apiKey）并暴露一组模型。在整个配置中通过 供应商名称|模型名称 的格式引用模型。

通用字段

modelProviders:
- name: custom1
provider: custom
format: openai
apiBase: "https://api.openai.com/v1"
apiKey: your-openai-api-key-change-in-production-2026
isDefault: true
# proxyName: local
models:
- name: gpt-4o
- name: gpt-3.5-turbo

模型配置

每个模型可以单独设置参数：

models:
- name: gpt-4o
# imageInputs: ["url", "base64"]
# temperature: 0.7
# maxTokens: 4096
# contextWindow: 128000

支持的供应商示例

OpenAI 官方：

# - name: openai
#   provider: openai
#   apiKey: sk-...
#   models:
#     - name: gpt-4o

Google Gemini：

# - name: gemini
#   provider: gemini
#   apiKey: your-gemini-api-key
#   models:
#     - name: gemini-2.0-flash

Anthropic Claude：

# - name: claude
#   provider: claude
#   apiKey: sk-ant-...
#   models:
#     - name: claude-3-5-sonnet-20241022

Ollama（本地模型）：

# - name: ollama
#   provider: custom
#   format: ollama
#   apiBase: "http://localhost:11434"
#   apiKey: ""
#   models:
#     - name: llama3

DeepSeek：

# - name: deepseek
#   provider: deepseek
#   apiKey: your-deepseek-api-key
#   models:
#     - name: deepseek-chat

Embedding Model（嵌入模型）

控制知识记忆和语义搜索的向量嵌入后端。

embeddingModel:
type: default
# type: openai
# model: text-embedding-3-small
# apiKey: your-embedding-api-key
# apiBase: "https://api.openai.com/v1"

Model（模型别名与回退链）

将逻辑模型别名映射到具体的 供应商名称|模型名称。支持在同一键下配置多个模型，形成自动回退链：前一个失败时自动尝试下一个。

model:
default:
- name: "custom1|gpt-4o"
router:
- name: "custom1|gpt-4o"
# fallback:
#   - name: "custom1|gpt-4o"
#   - name: "custom1|gpt-3.5-turbo"

Runtime（运行时环境）

# runtime:
#   python:
#     path: /usr/bin/python3

Agent（Agent 任务）

agent:
maxConcurrent: 3
# taskPath: /custom/agent/tasks/

Env（环境变量注入）

# env:
#   PATH: "/opt/homebrew/bin:$PATH"
#   PYTHONPATH: "/custom/python/lib"

注入到 Shell / Python 子进程的额外环境变量。值中可以使用 $VAR 或 ${VAR} 引用已有环境变量。

Error Reporting（错误报告）

# reportUrl: "https://your-monitoring-endpoint/report"

可选的错误报告 URL。当系统发生错误时，通过 GET 请求发送 URL 编码的 JSON 数据到此地址：

GET <reportUrl>?data=<json>

Claw（Claw 模块）

claw:
skillDirs:
- /path/to/skills

快速上手

1. 将 config.example.yaml 复制为 config.yaml
2. 修改以下必要字段：

• jwt.secret — 至少 16 个字符的随机字符串
• auth.password — 设置登录密码
• modelProviders — 配置至少一个可用的 AI 模型供应商

3. 根据需求调整端口、数据库、存储后端等
4. 启动 ClawGoal 服务，系统会自动读取配置

📘 修改配置后需要重启 ClawGoal 服务才能使新配置生效。