> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置引用

> 每一个 GOWA 环境变量和命令行标志，默认值。

GOWA 读取三个地点的配置：

* **命令行标志** 在 `whatsapp rest` (运行`./whatsapp rest --help` 以获取完整列表)。
* **环境变量**。
* 在工作目录中\*\*`.env`文件(`src/.env`从源运行时；复制 `src/.env.example`)。

`.env`文件只填充环境中尚未设置的变量。

> [!WARNING]
>
> 在当前代码中，环境变量（包括 `.env`）会在解析标志**之后**应用，因此已设置的变量会覆盖对应标志。MCP OAuth 设置、`--allow-unauthenticated`、`--trusted-origins`、`--chatwoot-webhook-allow-unsigned` 和 `--webhook-all-device-receipts` 是例外，它们以显式指定的标志为准。每个选项只在一处设置。例如，`WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true` 会覆盖 `--webhook-insecure-skip-verify=false`。

布尔值接受`true`/`false`。持续时间使用 Go 语法(`30s`, `5m`, `3h`). 列表值是用逗号分隔的。

## 命令

| 命令 | 描述 |
| - | - |
| `whatsapp rest` | 启动REST API、仪表盘、WebSocket 和 MCP 端点。v6后需要一个 bare `whatsapp` 并不启动服务器。 |
| `whatsapp version` | 打印版本并退出。 |
| `whatsapp --help` | 列出命令和标记。 |

## 服务器

| 变量 | 标志 | 默认设置 | 描述 |
| - | - | - | - |
| `APP_PORT` | `--port`, `-p` | `3000` | HTTP 端口。 |
| `APP_HOST` | `--host`, `-H` | `0.0.0.0` | 绑定地址。 |
| `APP_DEBUG` | `--debug`, `-d` | `false` | 详细日志记录。 |
| `APP_OS` | `--os` | `GOWA` | 在 WhatsApp的 **链接设备** 列表中显示的设备名称。 |
| `APP_BASIC_AUTH` | `--basic-auth`, `-b` | — | 完成`user:pass`对，逗号分隔。非循环监听器所需，除非设置了未验证的显式覆盖。 |
| `APP_ALLOW_UNAUTHENTICATED` | `--allow-unauthenticated` | `false` | 允许非循环监听器无基本认证。只在直接访问限制的身份验证代理后使用。 |
| `APP_TRUSTED_ORIGINS` | `--trusted-origins` | — | 允许变换状态和打开 WebSockets的浏览器来源。请求主机和特定的 CORS 来源也是可信的。 |
| `APP_BASE_PATH` | `--base-path` | — | 在子路径下服务，例如`/gowa`。`/health` 停留在根目录下。 |
| `APP_TRUSTED_PROXIES` | `--trusted-proxies` | — | 其转发请求头受信任的代理 IP 范围，例如 `10.0.0.0/8`。 |
| `APP_CORS_ALLOWED_ORIGINS` | `--cors-allowed-origins` | — (任何来源) | CORS 源。特定来源也会通过浏览器来源检查。通配符不允许突变或WebSockets。 |

## 仪表板

| 变量 | 标志 | 默认设置 | 描述 |
| - | - | - | - |
| `APP_UI_ENABLED` | `--ui-enabled` | `true` | 在`/`上提供gowa-ui仪表盘服务。 |
| `APP_UI_AUTO_UPDATE` | `--ui-auto-update` | `true` | 在启动时及之后定期下载最新的仪表板版本。对于已预先填充 `storages/ui` 缓存的隔离网络主机，请禁用此功能。 |
| `APP_UI_REPO` | `--ui-repo` | `aldinokemal/gowa-ui` | 要下载的 GitHub 存储库。 |
| `APP_UI_ASSET_NAME` | `--ui-asset-name` | `gowa-ui.html` | 发布资产下载。 |
| `APP_UI_UPDATE_INTERVAL` | `--ui-update-interval` | `3h` | 更新检查间隔。 |
| `APP_UI_GITHUB_TOKEN` | — | — | GitHub 令牌获取更高的 API 率限制。 |
| `APP_UI_ASSET_SHA256` | `--ui-asset-sha256` | — | 仅使用此 SHA 256 的仪表盘。 |

## MCP

| 变量 | 标志 | 默认设置 | 描述 |
| - | - | - | - |
| `MCP_ENABLED` | `--mcp-enabled` | `true` | 在 `/mcp` 中提供MCP 端点。 |
| `MCP_OAUTH_ENABLED` | `--mcp-oauth-enabled` | `false` | 启用 OAuth 2.1 for `/mcp`。需要 `APP_BASIC_AUTH`。 |
| `MCP_OAUTH_ISSUER_URL` | `--mcp-oauth-issuer-url` | — | 公开的 HTTPS 发布器URL。需要使用 OAuth |
| `MCP_OAUTH_RESOURCE_URL` | `--mcp-oauth-resource-url` | 发行者 + 基本路径 + `/mcp` | 标准公开的 MCP URL。 |
| `MCP_OAUTH_DB_URI` | `--mcp-oauth-db-uri` | `file:storages/oauth.db` | 用于 OAuth 客户端的 SQLite 商店和令牌哈希。 |

请参阅[MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)。

## 存储

| 变量 | 标志 | 默认设置 | 描述 |
| - | - | - | - |
| `DB_URI` | `--db-uri` | `file:storages/whatsapp.db` | Session store: SQLite (`file:...`) or PostgreSQL (`postgres://...`). |
| `DB_KEYS_URI` | `--db-keys-uri` | 与 `DB_URI` 相同 | 可选的单独存储加密密钥缓存。在生产中避免内存存储。 |
| `CHAT_STORAGE_MAX_OPEN_CONNS` | — | `5` | 最大的 SQLite 连接用于聊天存储。如果发送时间过大，请升高。 |

聊天存储 (聊天、消息、schedules) 一直都在 `storages/chatstorage.db` 中生活，且不可配置。

使用 `0600` 权限创建 SQLite 会议、聊天存储和 OAuth 数据库。GOWA 为这些文件创建的目录使用 `0700`。 现有目录保留其权限。文件系统不支持的权限更改将被记录为警告。

对于 PostgreSQL 会话和密钥存储，当 `sslmode` 被省略或为空时，远程连接目标默认使用 `verify-full`。`localhost`、环回 IP 和 Unix 套接字默认使用 `disable`。显式 URI 设置、`PGSSLMODE` 和服务配置仍然有效。`PGSERVICE` 条目可以覆盖 URI 主机和 TLS 模式。使用托管 PostgreSQL 时，请显式提供 `sslmode=verify-full` 及所需的 CA 配置。

## WhatsApp 行为

| 变量 | 标志 | 默认设置 | 描述 |
| - | - | - | - |
| `WHATSAPP_AUTO_REPLY` | `--autoreply` | — | 修复了每个收到消息的回复。 |
| `WHATSAPP_AUTO_MARK_READ` | `--auto-mark-read` | `false` | 标记收到的消息为已读 |
| `WHATSAPP_AUTO_DOWNLOAD_MEDIA` | `--auto-download-media` | `true` | 将接收到的媒体保存到 `statics/media`。 |
| `WHATSAPP_IGNORE_STATUS_MEDIA` | `--ignore-status-media` | `false` | 跳过下载状态媒体。 |
| `WHATSAPP_AUTO_REJECT_CALL` | `--auto-reject-call` | `false` | 拒绝来电。 |
| `WHATSAPP_ACCOUNT_VALIDATION` | `--account-validation` | `true` | 发送前检查收件人在 WhatsApp 上。 |
| `WHATSAPP_PRESENCE_ON_CONNECT` | `--presence-on-connect` | `unavailable` | 连接时发送的在线状态：`available`、`unavailable` 或 `none`。 |
| `WHATSAPP_PRESENCE_PULSE_ENABLED` | `--presence-pulse-enabled` | `true` | 定期上网简略，然后再次离线。 |
| `WHATSAPP_PRESENCE_PULSE_INTERVAL` | `--presence-pulse-interval` | `24h` | 脉冲之间的时间。 |
| `WHATSAPP_PRESENCE_PULSE_DURATION` | `--presence-pulse-duration` | `5m` | 每个脉冲在线停留多长时间。 |
| `WHATSAPP_PROXY` | `--whatsapp-proxy` | — | WhatsApp 连接使用的代理：`socks5://`、`http://` 或 `https://`。`HTTP_PROXY` 不适用于此连接。 |

## Webhooks

| 变量 | 标志 | 默认设置 | 描述 |
| - | - | - | - |
| `WHATSAPP_WEBHOOK` | `--webhook`, `-w` | — | Webhook URL(s)，逗号分隔。 |
| `WHATSAPP_WEBHOOK_SECRET` | `--webhook-secret` | 每个进程的随机数 | `X-Hub-Signature-256`的HMAC密钥。设置一个稳定生成的密钥。空的，`secret`, `super-secret-key`, 和`your-private-key`, 生成一个星等密钥。 |
| `WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY` | `--webhook-insecure-skip-verify` | `false` | 跳过 TLS 验证 (仅开发)。 |
| `WHATSAPP_WEBHOOK_EVENTS` | `--webhook-events` | — (全部) | 事件允许列表，例如：`message,message.ack`。 |
| `WHATSAPP_WEBHOOK_IGNORE_JIDS` | `--webhook-ignore-jids` | — | JIDs或通配符(`@g.us`, `@s.whatsapp.net`, `@lid`) 没有转发。 |
| `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL` | `--webhook-device-merge-global` | `false` | 将设备的事件发送到全局的 URL 以及它自己的 Web 钩子。 |
| `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS` | `--webhook-all-device-receipts` | `false` | 从联系人链接的设备以及他们的主要设备转发收据。可能会为一个消息生成多个确认信息。 |

见 [Webhooks](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md)。

## Chatwoot

| 变量 | 标志 | 默认设置 |
| - | - | - |
| `CHATWOOT_ENABLED` | `--chatwoot-enabled` | `false` |
| `CHATWOOT_URL` | — | — |
| `CHATWOOT_API_TOKEN` | — | — |
| `CHATWOOT_ACCOUNT_ID` | — | — |
| `CHATWOOT_INBOX_ID` | — | — |
| `CHATWOOT_DEVICE_ID` | `--chatwoot-device-id` | — |
| `CHATWOOT_ALLOWED_HOSTS` | `--chatwoot-allowed-hosts` | — |
| `CHATWOOT_IMPORT_MESSAGES` | `--chatwoot-import-messages` | `false` |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `--chatwoot-days-limit-import-messages` | `3` |
| `CHATWOOT_IMPORT_DB_URI` | `--chatwoot-import-db-uri` | — |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `--chatwoot-import-placeholder-media-message` | `true` |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `--chatwoot-import-media-with-rest` | `false` |
| `CHATWOOT_AUTO_CREATE` | `--chatwoot-auto-create` | `false` |
| `CHATWOOT_INBOX_NAME` | `--chatwoot-inbox-name` | `WhatsApp` |
| `CHATWOOT_WEBHOOK_URL` | `--chatwoot-webhook-url` | — |
| `CHATWOOT_WEBHOOK_SECRET` | `--chatwoot-webhook-secret` | — |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `--chatwoot-webhook-allow-unsigned` | `false` |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `--chatwoot-webhook-signature-tolerance` | `5m` |
| `CHATWOOT_REOPEN_CONVERSATION` | `--chatwoot-reopen-conversation` | `true` |
| `CHATWOOT_CONVERSATION_PENDING` | `--chatwoot-conversation-pending` | `false` |
| `CHATWOOT_IGNORE_JIDS` | `--chatwoot-ignore-jids` | — |
| `CHATWOOT_SIGN_MSG` | `--chatwoot-sign-msg` | `false` |
| `CHATWOOT_SIGN_DELIMITER` | `--chatwoot-sign-delimiter` | `\n\n` |
| `CHATWOOT_FORWARD_EDITS` | `--chatwoot-forward-edits` | `true` |
| `CHATWOOT_FORWARD_DELETES` | `--chatwoot-forward-deletes` | `true` |
| `CHATWOOT_EVENTS` | `--chatwoot-events` | 在空时跟随`WHATSAPP_WEBHOOK_EVENTS` |
| `CHATWOOT_MESSAGE_READ` | `--chatwoot-message-read` | `false` |
| `CHATWOOT_MESSAGE_DELETE` | `--chatwoot-message-delete` | `false` |
| `CHATWOOT_REVOKE_ON_DELETE` | `--chatwoot-revoke-on-delete` | `false` |

事件过滤器和单向吊销选项可在 GOWA `main` v9.9.0后使用 [Chatwoot integration](https://gowa-docs.mintlify.site/zh/integrations/chatwoot.md#%E9%85%8D%E7%BD%AE) 查看行为和示例。

## 固定限制

这些是编译的，无法通过配置更改：

| 限制 | 值 |
| - | - |
| 图片上传 | 20 MB |
| 文档上传 | 50 MB |
| 视频上传和 HTTP 请求内容 | 100 MB |
| 传入媒体下载 | 500 MB |
| 请求超时 | 45 s (`504 GATEWAY_TIMEOUT`) |
| Web 钩子交付 | 每次尝试10秒，5 次尝试 |

## 媒体URL下载

发送获取介质、文档或链接预览接受 HTTP 和 HTTPS URL的请求。 Public URL 获取拒绝循环、私有、链接、本地、元数据、多播和保留目的地。 重定向和实际拨号地址被选中。这些下载直接连接，不使用 `HTTP_PROXY` 或 `HTTPS_PROXY`。

GOWA可以从磁盘读取它自己的 `/statics` 网址。 Chatwoot 附件下载可以使用配置的Chatwoot 目标或允许主机，包括信任的内部主机通过集成。 此异常不适用于提交给发送 API 的任意URL。当源是私有时使用文件上传。

## 未使用

`src/.env.example` 列出了`WHATSAPP_WEBHOOK_INCLUDE_OUTGOING` 和 `WHATSAPP_CHAT_STORAGE` ，但当前的代码也没有读取。设置它们也没有效果。

## 示例

```bash .env theme={null}
APP_PORT=3000
APP_OS=MyCompany
APP_BASIC_AUTH=admin:a-long-random-password
APP_TRUSTED_PROXIES=10.0.0.0/8
DB_URI=postgres://gowa:replace-with-password@db.example.com:5432/gowa?sslmode=verify-full
WHATSAPP_WEBHOOK=https://example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=another-long-random-secret
WHATSAPP_WEBHOOK_EVENTS=message,message.ack
WHATSAPP_AUTO_MARK_READ=false
```

等效标志：

```bash theme={null}
./whatsapp rest --port=3000 --os=MyCompany \
  --basic-auth=admin:a-long-random-password \
  --webhook=https://example.com/wa-hook \
  --webhook-secret=another-long-random-secret \
  --webhook-events=message,message.ack
```


## Related topics

- [快速开始](https://gowa-docs.mintlify.site/zh/quickstart.md)
- [聊天woot 集成](https://gowa-docs.mintlify.site/zh/integrations/chatwoot.md)
- [获取设备webhook 配置](https://gowa-docs.mintlify.site/zh/api-reference/device/获取设备webhook-配置.md)
- [设置设备webhook 配置](https://gowa-docs.mintlify.site/zh/api-reference/device/设置设备webhook-配置.md)
- [列出每台设备的Chatwoot 配置](https://gowa-docs.mintlify.site/zh/api-reference/chatwoot/列出每台设备的chatwoot-配置.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.