` | -- | 每个频道的防抖覆盖 |
### `messages.tts`
文本转语音配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `auto` | `"off" \| "always" \| "inbound" \| "tagged"` | -- | 自动 TTS 模式（优先于 `enabled`） |
| `enabled` | `boolean` | -- | 旧版：当 `auto` 未设置时启用自动 TTS |
| `mode` | `"final" \| "all"` | -- | 仅对最终回复还是所有回复应用 TTS |
| `provider` | `"elevenlabs" \| "openai" \| "edge"` | -- | 主 TTS 提供商 |
| `summaryModel` | `string` | -- | TTS 自动摘要的模型覆盖（提供商/模型或别名） |
| `maxTextLength` | `number` | -- | 发送到 TTS 的文本硬上限（字符） |
| `timeoutMs` | `number` | -- | API 请求超时（毫秒） |
| `prefsPath` | `string` | -- | 本地 TTS 用户偏好 JSON 的路径 |
#### `messages.tts.modelOverrides`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用模型提供的 TTS 覆盖 |
| `allowText` | `boolean` | -- | 允许模型提供的 TTS 文本块 |
| `allowProvider` | `boolean` | -- | 允许模型提供的提供商覆盖 |
| `allowVoice` | `boolean` | -- | 允许模型提供的 voice/voiceId 覆盖 |
| `allowModelId` | `boolean` | -- | 允许模型提供的 modelId 覆盖 |
| `allowVoiceSettings` | `boolean` | -- | 允许模型提供的语音设置覆盖 |
| `allowNormalization` | `boolean` | -- | 允许模型提供的规范化或语言覆盖 |
| `allowSeed` | `boolean` | -- | 允许模型提供的 seed 覆盖 |
#### `messages.tts.elevenlabs`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `apiKey` | `string` | -- | ElevenLabs API 密钥 |
| `baseUrl` | `string` | -- | ElevenLabs 基础 URL |
| `voiceId` | `string` | -- | 语音 ID |
| `modelId` | `string` | -- | 模型 ID |
| `seed` | `number` | -- | 确定性生成的种子 |
| `applyTextNormalization` | `"auto" \| "on" \| "off"` | -- | 文本规范化 |
| `languageCode` | `string` | -- | 语言代码 |
| `voiceSettings.stability` | `number` | -- | 语音稳定性 |
| `voiceSettings.similarityBoost` | `number` | -- | 相似度增强 |
| `voiceSettings.style` | `number` | -- | 风格 |
| `voiceSettings.useSpeakerBoost` | `boolean` | -- | 使用说话人增强 |
| `voiceSettings.speed` | `number` | -- | 速度 |
#### `messages.tts.openai`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `apiKey` | `string` | -- | OpenAI API 密钥 |
| `model` | `string` | -- | TTS 模型 |
| `voice` | `string` | -- | 语音标识符 |
#### `messages.tts.edge`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 明确允许 Edge TTS（无需 API 密钥） |
| `voice` | `string` | -- | 语音标识符 |
| `lang` | `string` | -- | 语言 |
| `outputFormat` | `string` | -- | 输出格式 |
| `pitch` | `string` | -- | 音调 |
| `rate` | `string` | -- | 语速 |
| `volume` | `string` | -- | 音量 |
| `saveSubtitles` | `boolean` | -- | 保存字幕 |
| `proxy` | `string` | -- | 代理 URL |
| `timeoutMs` | `number` | -- | 超时（毫秒） |
---
## `commands`
命令注册和访问控制。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `native` | `NativeCommandsSetting` | `"auto"` | 启用原生命令注册 |
| `nativeSkills` | `NativeCommandsSetting` | `"auto"` | 启用原生技能命令注册 |
| `text` | `boolean` | `true` | 启用文本命令解析 |
| `bash` | `boolean` | `false` | 允许 bash 聊天命令（`!` / `/bash` 别名） |
| `bashForegroundMs` | `number` | `2000` | bash 后台运行前的等待时间（0 = 立即） |
| `config` | `boolean` | `false` | 允许 `/config` 命令 |
| `debug` | `boolean` | `false` | 允许 `/debug` 命令 |
| `restart` | `boolean` | `false` | 允许重启命令/工具 |
| `useAccessGroups` | `boolean` | `true` | 对命令执行访问组允许列表/策略 |
---
## `approvals`
执行审批转发到聊天频道。
### `approvals.exec`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `false` | 启用将执行审批转发到聊天频道 |
| `mode` | `"session" \| "targets" \| "both"` | `"session"` | 投递模式 |
| `agentFilter` | `string[]` | -- | 仅为这些代理 ID 转发（省略 = 全部） |
| `sessionFilter` | `string[]` | -- | 仅为这些会话键模式转发（子字符串或正则表达式） |
| `targets` | `ExecApprovalForwardTarget[]` | -- | 显式投递目标（当模式包含 `"targets"` 时使用） |
#### ExecApprovalForwardTarget
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `channel` | `string` | 频道 ID（例如 `"discord"`、`"slack"`） |
| `to` | `string` | 目标 ID（根据频道为频道/用户 ID） |
| `accountId` | `string` | 多账户频道的可选账户 ID |
| `threadId` | `string \| number` | 可选的线程 ID |
---
## `session`
会话作用域、空闲超时和重置配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `scope` | `SessionScope` | -- | 会话作用域策略 |
| `dmScope` | `DmScope` | `"main"` | 私信会话作用域 |
| `identityLinks` | `Record` | -- | 将平台前缀的身份映射到规范的私信对等 |
| `resetTriggers` | `string[]` | -- | 触发会话重置的消息模式 |
| `idleMinutes` | `number` | -- | 空闲多少分钟后重置会话 |
| `reset` | `SessionResetConfig` | -- | 全局会话重置配置 |
| `resetByType` | `SessionResetByTypeConfig` | -- | 按类型的重置覆盖（dm、group、thread） |
| `resetByChannel` | `Record` | -- | 按频道的重置覆盖 |
| `store` | `string` | -- | 会话存储路径 |
| `typingIntervalSeconds` | `number` | -- | 输入指示器间隔 |
| `typingMode` | `TypingMode` | -- | 输入指示器模式 |
| `mainKey` | `string` | -- | 主会话键 |
| `sendPolicy` | `SessionSendPolicyConfig` | -- | 会话发送策略 |
| `agentToAgent.maxPingPongTurns` | `number` | `5` | 请求者/目标之间的最大乒乓轮次（0--5） |
---
## `web`
WhatsApp Web 提供商配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `true` | 启用 WhatsApp Web 提供商 |
| `heartbeatSeconds` | `number` | -- | 心跳间隔 |
| `reconnect.initialMs` | `number` | -- | 初始重连延迟（毫秒） |
| `reconnect.maxMs` | `number` | -- | 最大重连延迟（毫秒） |
| `reconnect.factor` | `number` | -- | 退避因子 |
| `reconnect.jitter` | `number` | -- | 抖动因子 |
| `reconnect.maxAttempts` | `number` | -- | 最大重连尝试次数（0 = 无限制） |
---
## `connectors`
消息连接器配置。每个键是一个连接器 ID（例如 `telegram`、`discord`、`slack`）。`channels` 键已弃用，请使用 `connectors` 代替。
```json
{
"connectors": {
"telegram": {
"enabled": true,
"botToken": "123456:ABC..."
},
"discord": {
"enabled": true,
"token": "Bot ..."
}
}
}
```
每个连接器的通用字段：
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `enabled` | `boolean` | 启用/禁用而无需移除配置 |
| `botToken` / `token` / `apiKey` | `string` | 认证凭证 |
| `dmPolicy` | `"open" \| "pairing" \| "closed"` | 私信访问控制 |
| `configWrites` | `boolean` | 允许连接器在事件上写入配置 |
`channels` 键已弃用。请迁移到 `connectors` 以获得前向兼容性。
---
## `cron`
定时任务配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用定时任务 |
| `store` | `string` | -- | 定时任务状态持久化路径 |
| `maxConcurrentRuns` | `number` | -- | 最大并发定时任务运行数 |
---
## `hooks`
事件驱动的钩子系统：Webhook、Gmail 集成和内部代理事件钩子。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用钩子系统 |
| `path` | `string` | -- | Webhook 端点路径 |
| `token` | `string` | -- | Webhook 认证令牌 |
| `maxBodyBytes` | `number` | -- | 最大 Webhook 请求体大小 |
| `presets` | `string[]` | -- | 要加载的钩子预设 |
| `transformsDir` | `string` | -- | 钩子转换模块的目录 |
| `mappings` | `HookMappingConfig[]` | -- | 钩子映射规则数组 |
### 钩子映射配置（`hooks.mappings[]`）
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `id` | `string` | -- | 映射标识符 |
| `match.path` | `string` | -- | 要匹配的 URL 路径模式 |
| `match.source` | `string` | -- | 源过滤器 |
| `action` | `"wake" \| "agent"` | -- | 钩子操作类型 |
| `wakeMode` | `"now" \| "next-heartbeat"` | -- | 何时唤醒代理 |
| `name` | `string` | -- | 钩子名称 |
| `sessionKey` | `string` | -- | 会话键覆盖 |
| `messageTemplate` | `string` | -- | 消息内容模板 |
| `textTemplate` | `string` | -- | 文本内容模板 |
| `deliver` | `boolean` | -- | 是否投递结果 |
| `allowUnsafeExternalContent` | `boolean` | -- | **危险：** 禁用外部内容安全包装 |
| `channel` | `string` | -- | 目标频道：`"last"`、`"whatsapp"`、`"telegram"`、`"discord"`、`"googlechat"`、`"slack"`、`"signal"`、`"imessage"`、`"msteams"` |
| `to` | `string` | -- | 目标 ID |
| `model` | `string` | -- | 此钩子的覆盖模型（提供商/模型） |
| `thinking` | `string` | -- | 思考级别覆盖 |
| `timeoutSeconds` | `number` | -- | 钩子处理超时 |
| `transform.module` | `string` | -- | 转换模块路径 |
| `transform.export` | `string` | -- | 转换模块的导出名称 |
### `hooks.gmail`
通过 Google Pub/Sub 的 Gmail Webhook 集成。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `account` | `string` | -- | Gmail 账户 |
| `label` | `string` | -- | 要监视的 Gmail 标签 |
| `topic` | `string` | -- | Pub/Sub 主题 |
| `subscription` | `string` | -- | Pub/Sub 订阅 |
| `pushToken` | `string` | -- | 推送通知令牌 |
| `hookUrl` | `string` | -- | Webhook URL |
| `includeBody` | `boolean` | -- | 包含邮件正文 |
| `maxBytes` | `number` | -- | 最大邮件正文字节数 |
| `renewEveryMinutes` | `number` | -- | 监视续订间隔（分钟） |
| `allowUnsafeExternalContent` | `boolean` | -- | **危险：** 禁用外部内容安全包装 |
| `serve.bind` | `string` | -- | 本地服务器绑定地址 |
| `serve.port` | `number` | -- | 本地服务器端口 |
| `serve.path` | `string` | -- | 本地服务器路径 |
| `tailscale.mode` | `"off" \| "serve" \| "funnel"` | -- | Tailscale 暴露模式 |
| `tailscale.path` | `string` | -- | Tailscale 路径 |
| `tailscale.target` | `string` | -- | Tailscale serve/funnel 目标（端口、host:port 或完整 URL） |
| `model` | `string` | -- | Gmail 钩子处理的模型覆盖 |
| `thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high"` | -- | 思考级别覆盖 |
### `hooks.internal`
内部代理事件钩子。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用内部钩子系统 |
| `handlers` | `InternalHookHandlerConfig[]` | -- | 旧版处理器列表 |
| `entries` | `Record` | -- | 每个钩子的配置覆盖（`enabled`、`env` 和任意键） |
| `load.extraDirs` | `string[]` | -- | 要扫描的额外钩子目录 |
| `installs` | `Record` | -- | 已安装的钩子包 |
#### InternalHookHandlerConfig
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `event` | `string` | 要监听的事件键（例如 `"command:new"`、`"session:start"`） |
| `module` | `string` | 处理器模块路径 |
| `export` | `string` | 模块的导出名称（默认：`"default"`） |
#### HookInstallRecord
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `source` | `"npm" \| "archive" \| "path"` | 安装来源 |
| `spec` | `string` | npm 规范或归档 URL |
| `sourcePath` | `string` | 原始源路径 |
| `installPath` | `string` | 本地安装路径 |
| `version` | `string` | 已安装版本 |
| `installedAt` | `string` | 安装时的 ISO 时间戳 |
| `hooks` | `string[]` | 此包提供的钩子名称 |
---
## `discovery`
网络发现配置（mDNS 和广域 DNS-SD）。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `wideArea.enabled` | `boolean` | -- | 启用广域 DNS-SD 发现 |
| `wideArea.domain` | `string` | -- | 单播 DNS-SD 域（例如 `"eliza.internal"`） |
| `mdns.mode` | `"off" \| "minimal" \| "full"` | `"minimal"` | mDNS 广播模式（`off` = 禁用，`minimal` = 省略 cliPath/sshPort，`full` = 包含全部） |
---
## `talk`
ElevenLabs Talk 模式语音设置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `voiceId` | `string` | -- | 默认 ElevenLabs 语音 ID |
| `voiceAliases` | `Record` | -- | 语音名称到 ElevenLabs 语音 ID 的映射 |
| `modelId` | `string` | -- | 默认 ElevenLabs 模型 ID |
| `outputFormat` | `string` | -- | 默认输出格式（例如 `mp3_44100_128`） |
| `apiKey` | `string` | -- | ElevenLabs API 密钥（回退到 `ELEVENLABS_API_KEY`） |
| `interruptOnSpeech` | `boolean` | `true` | 用户开始说话时停止发声 |
---
## `gateway`
网关服务器配置：端口、绑定地址、TLS、认证、HTTP 端点和节点路由。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `port` | `number` | `18789` | 网关 WS + HTTP 端口 |
| `mode` | `"local" \| "remote"` | -- | 网关模式（`"remote"` 禁用本地启动） |
| `bind` | `"auto" \| "lan" \| "loopback" \| "tailnet" \| "custom"` | `"loopback"` | 绑定地址策略 |
| `customBindHost` | `string` | -- | `bind="custom"` 的自定义 IP（回退：`0.0.0.0`） |
| `trustedProxies` | `string[]` | -- | `x-forwarded-for` 的受信任反向代理 IP |
### `gateway.tls`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 为网关服务器启用 TLS |
| `autoGenerate` | `boolean` | `true` | 当 cert/key 缺失时自动生成自签名证书 |
| `certPath` | `string` | -- | PEM 证书路径 |
| `keyPath` | `string` | -- | PEM 私钥路径 |
| `caPath` | `string` | -- | 用于 mTLS 或自定义根证书的 CA 包路径 |
### `gateway.auth`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `mode` | `"token" \| "password"` | `"token"` | 认证模式 |
| `token` | `string` | -- | 令牌模式的共享令牌 |
| `password` | `string` | -- | 密码模式的共享密码 |
| `allowTailscale` | `boolean` | -- | 当 serve 模式启用时允许 Tailscale 身份头 |
### `gateway.controlUi`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 提供控制 UI（默认：`/`） |
| `basePath` | `string` | -- | 基础路径前缀（例如 `"/eliza"`） |
| `root` | `string` | -- | 控制 UI 资源的文件系统根目录（默认为 `dist/control-ui`） |
| `allowedOrigins` | `string[]` | -- | WebSocket 连接允许的浏览器来源 |
| `allowInsecureAuth` | `boolean` | `false` | 允许在不安全的 HTTP 上使用仅令牌认证 |
| `dangerouslyDisableDeviceAuth` | `boolean` | `false` | **危险：** 禁用设备身份检查 |
### `gateway.tailscale`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `mode` | `"off" \| "serve" \| "funnel"` | -- | Tailscale 暴露模式 |
| `resetOnExit` | `boolean` | -- | 关闭时重置 serve/funnel 配置 |
### `gateway.remote`
远程网关连接设置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `url` | `string` | -- | 远程网关 WebSocket URL（`ws://` 或 `wss://`） |
| `transport` | `"ssh" \| "direct"` | -- | macOS 远程连接的传输方式 |
| `token` | `string` | -- | 远程认证令牌 |
| `password` | `string` | -- | 远程认证密码 |
| `tlsFingerprint` | `string` | -- | 预期的 TLS 证书指纹（SHA-256） |
| `sshTarget` | `string` | -- | 隧道的 SSH 目标（`user@host`） |
| `sshIdentity` | `string` | -- | SSH 身份文件路径 |
### `gateway.reload`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `mode` | `"off" \| "restart" \| "hot" \| "hybrid"` | `"hybrid"` | 配置更改的重新加载策略 |
| `debounceMs` | `number` | `300` | 配置重新加载的防抖窗口（毫秒） |
### `gateway.http`
HTTP API 端点配置。
#### `gateway.http.endpoints.chatCompletions`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `false` | 提供 `POST /v1/chat/completions` |
#### `gateway.http.endpoints.responses`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `false` | 提供 `POST /v1/responses`（OpenResponses API） |
| `maxBodyBytes` | `number` | 20MB | 最大请求体大小（字节） |
| `files.allowUrl` | `boolean` | `true` | 允许 `input_file` 的 URL 获取 |
| `files.allowedMimes` | `string[]` | -- | 允许的 MIME 类型（不区分大小写） |
| `files.maxBytes` | `number` | 5MB | 每个文件的最大字节数 |
| `files.maxChars` | `number` | 200k | 每个文件的最大解码字符数 |
| `files.maxRedirects` | `number` | `3` | 获取 URL 时的最大重定向次数 |
| `files.timeoutMs` | `number` | 10s | 获取超时（毫秒） |
| `files.pdf.maxPages` | `number` | `4` | 要解析/渲染的最大页数 |
| `files.pdf.maxPixels` | `number` | 4M | 每个渲染页面的最大像素数 |
| `files.pdf.minTextChars` | `number` | `200` | 跳过光栅化的最小文本长度（字符） |
| `images.allowUrl` | `boolean` | `true` | 允许 `input_image` 的 URL 获取 |
| `images.allowedMimes` | `string[]` | -- | 允许的 MIME 类型（不区分大小写） |
| `images.maxBytes` | `number` | 10MB | 每个图像的最大字节数 |
| `images.maxRedirects` | `number` | `3` | 最大重定向次数 |
| `images.timeoutMs` | `number` | 10s | 获取超时（毫秒） |
### `gateway.nodes`
节点路由配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `browser.mode` | `"auto" \| "manual" \| "off"` | `"auto"` | 节点托管浏览器代理的浏览器路由策略 |
| `browser.node` | `string` | -- | 固定到特定的节点 ID/名称 |
| `allowCommands` | `string[]` | -- | 允许的额外 `node.invoke` 命令 |
| `denyCommands` | `string[]` | -- | 即使在默认值或节点声明中也拒绝的命令 |
---
## `memory`
记忆后端配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `backend` | `"builtin" \| "qmd"` | `"builtin"` | 记忆后端 |
| `citations` | `"auto" \| "on" \| "off"` | -- | 引用模式 |
| `qmd` | `MemoryQmdConfig` | -- | QMD 记忆后端配置 |
### `memory.qmd`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `command` | `string` | -- | QMD 二进制命令 |
| `includeDefaultMemory` | `boolean` | -- | 包含默认记忆路径 |
| `paths` | `MemoryQmdIndexPath[]` | -- | 索引路径（每个：`{ path, name?, pattern? }`） |
| `sessions.enabled` | `boolean` | -- | 启用会话索引 |
| `sessions.exportDir` | `string` | -- | 会话导出目录 |
| `sessions.retentionDays` | `number` | -- | 会话保留天数 |
| `update.interval` | `string` | -- | 更新间隔 |
| `update.debounceMs` | `number` | -- | 更新防抖（毫秒） |
| `update.onBoot` | `boolean` | -- | 启动时运行更新 |
| `update.embedInterval` | `string` | -- | 嵌入更新间隔 |
| `limits.maxResults` | `number` | -- | 最大搜索结果数 |
| `limits.maxSnippetChars` | `number` | -- | 最大摘要字符数 |
| `limits.maxInjectedChars` | `number` | -- | 最大注入字符数 |
| `limits.timeoutMs` | `number` | -- | 搜索超时（毫秒） |
| `scope` | `SessionSendPolicyConfig` | -- | 作用域策略 |
---
## `embedding`
本地嵌入模型配置（支持 Metal GPU 的 GGUF 模型）。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `model` | `string` | -- | GGUF 模型文件名（例如 `"nomic-embed-text-v1.5.Q5_K_M.gguf"`） |
| `modelRepo` | `string` | -- | 用于模型解析的 Hugging Face 仓库/来源 |
| `dimensions` | `number` | `768` | 嵌入向量维度 |
| `contextSize` | `number` | -- | 嵌入上下文窗口大小（必须匹配模型） |
| `gpuLayers` | `number \| "auto" \| "max"` | -- | 模型加载的 GPU 层数 |
| `idleTimeoutMinutes` | `number` | `30` | 不活动多少分钟后从内存中卸载模型（0 = 永不卸载） |
---
## `database`
数据库提供商和连接配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `provider` | `"pglite" \| "postgres"` | `"pglite"` | 活动数据库提供商 |
### `database.pglite`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `dataDir` | `string` | `~/.eliza/workspace/.eliza/.elizadb` | PGLite 数据目录 |
### `database.postgres`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `connectionString` | `string` | -- | 完整的 PostgreSQL 连接字符串（优先于单独字段） |
| `host` | `string` | `localhost` | PostgreSQL 主机 |
| `port` | `number` | `5432` | PostgreSQL 端口 |
| `database` | `string` | -- | 数据库名称 |
| `user` | `string` | -- | 数据库用户 |
| `password` | `string` | -- | 数据库密码 |
| `ssl` | `boolean` | `false` | 启用 SSL 连接 |
---
## `cloud`
Eliza Cloud 集成，用于远程代理配置、推理代理和状态备份。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `false` | 启用 Eliza Cloud 集成 |
| `provider` | `string` | -- | 云提供商 ID（例如 `"elizacloud"`；在引导时设置） |
| `baseUrl` | `string` | `https://elizacloud.ai/api/v1` | API 基础 URL |
| `apiKey` | `string` | -- | 缓存的 API 密钥（通过网关认证加密存储） |
| `inferenceMode` | `"cloud" \| "byok" \| "local"` | -- | 推理路由：`cloud`（代理）、`byok`（用户密钥）、`local`（无云端） |
| `autoProvision` | `boolean` | `false` | 创建时自动将代理部署到云端 |
### `cloud.bridge`
云代理的 WebSocket 通信设置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `reconnectIntervalMs` | `number` | `3000` | 重连间隔基数（毫秒） |
| `maxReconnectAttempts` | `number` | `20` | 最大重连尝试次数 |
| `heartbeatIntervalMs` | `number` | `30000` | 心跳间隔（毫秒） |
### `cloud.backup`
代理状态快照设置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `autoBackupIntervalMs` | `number` | `3600000` (1 hour) | 自动备份间隔（毫秒） |
| `maxSnapshots` | `number` | `10` | 保留的最大自动快照数 |
### `cloud.container`
新云部署的默认容器设置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `defaultImage` | `string` | -- | 代理容器的默认 ECR 镜像 URI |
| `defaultArchitecture` | `"arm64" \| "x86_64"` | `"arm64"` | 默认 CPU 架构 |
| `defaultCpu` | `number` | `1792` | 默认 CPU 单元 |
| `defaultMemory` | `number` | `1792` | 默认内存（MB） |
| `defaultPort` | `number` | `2138` | 默认容器端口 |
---
## `x402`
x402 HTTP 支付协议配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用 x402 支付 |
| `privateKey` | `string` | -- | 钱包私钥 |
| `network` | `string` | -- | 网络标识符 |
| `payTo` | `string` | -- | 收款地址 |
| `facilitatorUrl` | `string` | -- | 中介服务 URL |
| `maxPaymentUsd` | `number` | -- | 单笔最大支付金额（美元） |
| `maxTotalUsd` | `number` | -- | 最大总支付金额（美元） |
| `dbPath` | `string` | -- | 支付数据库路径 |
---
## `media`
媒体生成配置（图像、视频、音频、视觉提供商）。
### `media.image`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用图像生成 |
| `mode` | `"cloud" \| "own-key"` | -- | 云端（代理）或自有 API 密钥 |
| `provider` | `"cloud" \| "fal" \| "openai" \| "google" \| "xai"` | -- | 图像提供商 |
| `defaultSize` | `string` | -- | 默认图像大小 |
| `fal` | `{ apiKey?, model?, baseUrl? }` | -- | Fal.ai 配置 |
| `openai` | `{ apiKey?, model?, quality?, style? }` | -- | OpenAI 配置（`quality`：`"standard"` 或 `"hd"`，`style`：`"natural"` 或 `"vivid"`） |
| `google` | `{ apiKey?, model?, aspectRatio? }` | -- | Google 配置 |
| `xai` | `{ apiKey?, model? }` | -- | xAI 配置 |
### `media.video`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用视频生成 |
| `mode` | `"cloud" \| "own-key"` | -- | 云端（代理）或自有 API 密钥 |
| `provider` | `"cloud" \| "fal" \| "openai" \| "google"` | -- | 视频提供商 |
| `defaultDuration` | `number` | -- | 默认视频时长 |
| `fal` | `{ apiKey?, model?, baseUrl? }` | -- | Fal.ai 配置 |
| `openai` | `{ apiKey?, model? }` | -- | OpenAI 配置 |
| `google` | `{ apiKey?, model? }` | -- | Google 配置 |
### `media.audio`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用音频生成 |
| `mode` | `"cloud" \| "own-key"` | -- | 云端（代理）或自有 API 密钥 |
| `provider` | `"cloud" \| "suno" \| "elevenlabs"` | -- | 音频提供商 |
| `suno` | `{ apiKey?, model?, baseUrl? }` | -- | Suno 配置 |
| `elevenlabs` | `{ apiKey?, duration? }` | -- | ElevenLabs SFX 配置 |
### `media.vision`
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `enabled` | `boolean` | -- | 启用视觉（图像理解） |
| `mode` | `"cloud" \| "own-key"` | -- | 云端（代理）或自有 API 密钥 |
| `provider` | `"cloud" \| "openai" \| "google" \| "anthropic" \| "xai" \| "ollama"` | -- | 视觉提供商 |
| `openai` | `{ apiKey?, model?, maxTokens? }` | -- | OpenAI 配置 |
| `google` | `{ apiKey?, model? }` | -- | Google 配置 |
| `anthropic` | `{ apiKey?, model? }` | -- | Anthropic 配置 |
| `xai` | `{ apiKey?, model? }` | -- | xAI 配置 |
| `ollama` | `{ baseUrl?, model?, maxTokens?, autoDownload? }` | -- | Ollama 配置 |
---
## `mcp`
MCP（模型上下文协议）服务器定义。
```json
{
"mcp": {
"servers": {
"my-server": {
"type": "stdio",
"command": "bunx",
"args": ["-y", "@some/mcp-server"],
"env": { "API_KEY": "..." }
},
"remote-server": {
"type": "sse",
"url": "https://mcp.example.com/sse",
"headers": { "Authorization": "Bearer ..." }
}
}
}
}
```
### MCP 服务器条目
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `type` | `string` | -- | 服务器类型（例如 `"stdio"`、`"sse"`） |
| `command` | `string` | -- | 要执行的命令（用于 `stdio` 类型） |
| `args` | `string[]` | -- | 命令参数 |
| `url` | `string` | -- | 服务器 URL（用于 `sse` 或远程类型） |
| `env` | `Record` | -- | 服务器进程的环境变量 |
| `headers` | `Record` | -- | 远程连接的 HTTP 头部 |
| `cwd` | `string` | -- | 服务器进程的工作目录 |
| `timeoutInMillis` | `number` | -- | 连接超时（毫秒） |
---
## `registry`
ERC-8004 代理注册表和 ElizaMaker NFT 收藏配置。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `mainnetRpc` | `string` | -- | 以太坊主网（或本地 Anvil）RPC URL |
| `registryAddress` | `string` | -- | ElizaAgentRegistry 合约地址 |
| `collectionAddress` | `string` | -- | ElizaMaker 收藏合约地址 |
---
## `features`
插件自动启用和功能开关的功能标志。每个键映射到一个布尔值或一个包含 `enabled` 和其他选项的对象。
```json
{
"features": {
"shellEnabled": true,
"someFeature": { "enabled": true, "option": "value" }
}
}
```
---
## `customActions`
用户定义的代理自定义操作。`CustomActionDef` 对象的数组。
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `id` | `string` | -- | **必需。** 唯一操作标识符 |
| `name` | `string` | -- | **必需。** 操作显示名称 |
| `description` | `string` | -- | **必需。** 操作描述 |
| `similes` | `string[]` | -- | 替代触发短语 |
| `parameters` | `Array<{ name, description, required }>` | -- | **必需。** 操作参数 |
| `handler` | `CustomActionHandler` | -- | **必需。** 处理器定义（见子表） |
| `enabled` | `boolean` | -- | **必需。** 操作是否启用 |
| `createdAt` | `string` | -- | **必需。** ISO 创建时间戳 |
| `updatedAt` | `string` | -- | **必需。** ISO 最后更新时间戳 |
### CustomActionHandler
处理器是以下三种类型之一：
**HTTP 处理器：**
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `type` | `"http"` | 处理器类型 |
| `method` | `string` | HTTP 方法 |
| `url` | `string` | 请求 URL |
| `headers` | `Record` | 可选的请求头 |
| `bodyTemplate` | `string` | 可选的请求体模板 |
**Shell 处理器：**
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `type` | `"shell"` | 处理器类型 |
| `command` | `string` | 要执行的 Shell 命令 |
**代码处理器：**
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `type` | `"code"` | 处理器类型 |
| `code` | `string` | 要执行的 JavaScript 代码 |