Omentir

Omentir

Omentir 是 HeyReach 和 Gojiberry 等 LinkedIn 外联与自动化工具的开源替代方案。

这是一个 AI 销售工作区，可用于寻找符合条件的 LinkedIn 潜在客户、撰写贴合上下文的外联内容、以符合真人节奏的方式开展营销活动并处理回复；但代码由你掌控，运行环境也由你自行管理。

你可以使用托管产品 omentir.com，也可以使用自己的 Firebase、Gemini 和 Unipile 账号自托管同一套应用代码。

单一代码库： 托管云端版本和自托管版本共用此代码库。RUN_LOCALLY=TRUE 会关闭身份验证、计费、营销和仅托管版本提供的邮件功能。omentir.com 的公开品牌联系信息会有意保留在源代码中（参见 src/lib/hosted-identity.ts）；自托管运行时不会使用这些信息。

从其他 AI 应用连接（Claude、ChatGPT、Grok、Grok Bot、Cursor，……）

用户无需共享 LinkedIn 密码，即可通过聊天和编码 Agent 使用 Omentir：

1. 在 Omentir 中：连接 LinkedIn 并填写工作区。
2. 聊天应用（Claude、ChatGPT、Grok）： 设置 → 连接器 → 添加
   https://omentir.com/api/agent/v1/mcp → 登录并批准连接工作区 → 在聊天中启用工具。
   无需 API 密钥。
3. Grok Bot（常驻队友应用，而非 grok.com 聊天）：设置 → 插件 → 在 Marketplace 中搜索 Omentir。如果列表中没有，请将同一个 MCP URL 添加为自定义服务端 → 批准连接工作区。不要在 Bot 电脑上登录 LinkedIn。Grok Bot 集成。
4. Cursor / Claude Code / 脚本： 在 API 页面创建密钥，并向 MCP 端点或 REST /api/agent/v1/* 发送
   Authorization: Bearer <token>。
5. 请助手创建经典潜在客户查找器或 Steal Customers Agent（mode: steal_customers + 竞争对手公司 URL）。如果你有多个公司，请让它列出工作区并切换。

文档：MCP 集成、Agent API、agents.md（机器指南）、OpenAPI。

---

自托管

Omentir 可通过外部托管服务实现自托管。它并非离线运行，也不免除依赖项。你需要提供 Firebase/Firestore、Unipile，以及 Gemini API 密钥或 Google Cloud Vertex AI 项目。

自托管无需订阅 Omentir，但 Firebase/Google AI 和 Unipile 仍可能产生费用。

在 localhost 上快速启动

安装 Git，以及 Docker 和 Docker Compose，或 Bun 1.3。然后克隆并配置项目：

git clone https://github.com/vanshyadav1408/Omentir.git
cd Omentir
cp .env.example .env

打开 .env，为所有未注释的空白值填写内容。启动服务端之前，请完成下方的服务提供商设置。

使用以下命令生成彼此独立的密钥：

openssl rand -base64 48

至少将生成的密钥（或密码管理器）用于以下项目：

• LOCAL_SESSION_SECRET（必需）
• LOCAL_APP_PASSWORD（必需，除非你明确允许公开访问——参见访问控制）
• CRON_SECRET（必需，除非完全禁用自动化）
• UNIPILE_WEBHOOK_SECRET（处理回复和关系 Webhook 时必需）

如果初次设置时要禁用所有自动化，请将 CRON_SECRET 留空，并改为设置 AUTOMATION_DISABLED=true。在检查完试运行输出之前，请保持 ENABLE_LIVE_AUTOMATION=false。

使用 Docker 运行

Docker 是受支持的自托管方式。Omentir 可在 amd64 和 arm64 上运行。

docker compose up --build -d
docker compose logs -f omentir

打开 http://localhost:3000。按 Ctrl+C 退出日志视图，但不会停止 Omentir。之后使用 docker compose down 停止服务。

端口绑定： Compose 仅将应用发布为 127.0.0.1:3000:3000。这意味着容器只能从同一台机器访问（http://localhost:3000），无法从局域网中的其他设备或公共互联网访问。这是有意为之：不能仅仅因为 Docker 已启动，就让配置错误或未设置密码的实例变得可访问。

如需在实际主机（局域网/VPS）上公开应用：

1. 在公共接口上配置 HTTPS 反向代理（Caddy、nginx、Traefik 等）。
2. 将请求代理到 127.0.0.1:3000（只有在了解风险的情况下才更改 Compose 绑定）。
3. 将 APP_BASE_URL 设置为准确的公共 HTTPS 来源（末尾不要带斜杠）。
4. 设置强度足够的 LOCAL_APP_PASSWORD（不要在公共 URL 上启用开放访问）。

使用 Bun 运行

用于本地开发：

bun install
bun run dev

用于生产风格的本地服务：

bun install
bun run build
bun start

打开 http://localhost:3000。使用 LOCAL_APP_PASSWORD 登录，除非你选择启用开放访问（见下文）。

Bun 是包管理器和脚本运行器，但 bun run dev 会有意在 Node 上启动 Next，而不是通过 bun --bun 运行。在开发模式下，Turbopack 会通过哈希标识符（例如 firebase-admin-<hash>/firestore）加载 serverExternalPackages 中的每个包（其中包括 firebase-admin），这类标识符只能通过 Next 在 Node 中安装的加载器钩子解析。Bun 的解析器不会运行该钩子，因此 bun --bun next dev 会在首次导入 Firestore 时因 ResolveMessage: Cannot find module 而失败。生产环境不受影响：构建产物会生成普通的 require，因此 build 和 start 仍可在 Bun 下运行。

访问控制（本地登录）

自托管模式使用单个工作区和经过签名的 HTTP-only 会话 Cookie（omentir_local_session），而非 Clerk。

设置	行为
设置了 LOCAL_APP_PASSWORD（12 个或更多字符，且熵高）	登录表单要求输入该密码。这是默认预期配置。
LOCAL_APP_PASSWORD 为空，且未设置 LOCAL_ALLOW_OPEN_ACCESS 或其值为 false	启动失败。 空密码已不足以运行不受保护的实例。
LOCAL_ALLOW_OPEN_ACCESS=true 且密码为空	明确选择启用：显示带有“Continue to overview”按钮的欢迎屏幕（无需密码）。仅在可信机器/专用网络上使用。
LOCAL_ALLOW_OPEN_ACCESS=true 且已设置密码	仍然需要密码（开放访问标志不会削弱已配置的密码保护）。
LOCAL_SESSION_SECRET	始终为必需项。至少 32 个字符，且熵高。用于对会话令牌进行 HMAC 签名。更改此值会使所有现有会话失效。

对运维人员而言，以下额外登录加固措施也很重要：

• 来源检查： POST /api/local-auth/login 仅接受 Origin 与 APP_BASE_URL 匹配的请求。
• 暴力破解限流： 按来源 IP 对错误密码进行限流（进程内）。
• 登录后重定向： ?next= 返回路径会经过清理，因此 //evil.com 之类的值无法在登录后将浏览器重定向到其他站点。只允许同源相对路径（以单个 / 开头）。
• Cookie 标志： 会话 Cookie 设置了 HttpOnly 和 SameSite=Lax；当 APP_BASE_URL 使用 HTTPS 时，还会设置 Secure。

1. 服务提供方设置

1. 创建一个专用的 Firebase 项目。启用 Firestore 并创建服务账号。切勿重复使用托管的 Omentir 项目。
2. 使用 firebase deploy --only firestore:indexes 部署所需索引，或通过 Firestore 错误链接创建索引。索引源文件为 firestore.indexes.json。
   • 同时部署 firebase deploy --only firestore:rules。Omentir 仅通过服务端 Admin SDK 访问 Firestore，因此随附的 firestore.rules 会拒绝所有直接的浏览器/客户端访问。请保持其处于已部署状态——这样即使有人泄露了项目 ID 或 Web API 密钥，也无法读取或写入你的数据。
3. 创建 Unipile 账号并获取其 DSN、API 密钥和 Webhook 密钥。Unipile 是付费服务，且 LinkedIn 可能会限制自动化账号。
4. 创建 Gemini API 密钥。若改用 Vertex，请设置 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION 和 GOOGLE_APPLICATION_CREDENTIALS_JSON，启用 Vertex AI，并向服务账号授予 Vertex AI User 角色。

2. 配置

将 .env.example 复制为 .env。服务器启动时会验证必需的本地设置：

变量	范围	密钥	运行时行为
RUN_LOCALLY=TRUE	本地	否	选择内置的单工作区身份验证
APP_BASE_URL	共享	否	规范服务器 URL；非 localhost 环境下必须使用 HTTPS
LOCAL_APP_PASSWORD	本地	是*	除非明确允许开放访问，否则必须设置访问密码；设置后长度至少为 12 个字符
LOCAL_ALLOW_OPEN_ACCESS	本地	否	必须严格设为 true 才能允许无密码欢迎界面
LOCAL_SESSION_SECRET	本地	是	独立的随机值，至少 32 个字符
LOCAL_USER_NAME / LOCAL_USER_EMAIL	本地	否	单个本地工作区的显示身份信息
FIREBASE_PROJECT_ID	共享	否	专用 Firebase 项目
FIREBASE_SERVICE_ACCOUNT_KEY	共享	是	服务账号 JSON；JSON 格式错误会导致启动失败
UNIPILE_DSN / UNIPILE_API_KEY	共享	混合	Unipile 端点和凭据
UNIPILE_WEBHOOK_SECRET	共享	是	验证回复和关系 Webhook
GEMINI_API_KEY	本地/简单	是	Gemini Developer API 路径
Vertex 变量	共享/高级	是	GEMINI_API_KEY 的替代方案
CRON_SECRET	共享	是	除非已禁用自动化，否则必须设置；供内置调度器和作业路由使用
ENABLE_LIVE_AUTOMATION	本地	否	只有严格设为 true 时才会启用实时发送
AUTOMATION_DISABLED	共享	否	紧急停止开关；跳过调度器和作业执行
RESEND_API_KEY / RESEND_FROM_EMAIL	可选	是/混合	仅在本地模式下用于事务性通知
ALLOWED_DEV_ORIGINS	仅开发	否	使用隧道/代理时，为 Next.js HMR 添加额外主机名

* 即使 LOCAL_APP_PASSWORD 由人工输入，也应将其视为密钥。

请使用具备密码学安全性的密码管理器或 openssl rand -base64 48 生成密钥。启动时会拒绝 replace-me 等占位字符串。

3. HTTPS 和回调

支持在本地浏览器中使用 http://localhost。任何局域网、VPS、隧道或互联网部署都必须使用 HTTPS。在端口 3000 前放置 Caddy 或 nginx 等反向代理（优先代理到上述回环地址），并将 APP_BASE_URL 设置为精确的公开来源。不要在没有 TLS 和密码保护的情况下，将端口 3000 暴露到 0.0.0.0。

Unipile 连接和回复回调需要可访问的 HTTPS URL，且该 URL 必须与 APP_BASE_URL 一致。

LinkedIn 连接通知回调

用户连接 LinkedIn 时，Omentir 会向 Unipile 注册一个服务器到服务器通知 URL：

{APP_BASE_URL}/api/connect/callback

该端点要求提供流程启动时签发、成功后即被使用的一次性高熵连接令牌。它还会验证返回的账户是否存在于已配置的 Unipile 账户中，然后再保存该账户。回调 URL 中绝不会放置共享密钥。

回复／关系 Webhook 使用单独的 Unipile Webhook 路由和相同的 UNIPILE_WEBHOOK_SECRET（请求头 x-omentir-webhook-secret）。

4. 安全地启用自动化

保持 ENABLE_LIVE_AUTOMATION=false，连接 LinkedIn，并在 automationRuns 中检查试运行决策。只有在账户、目标对象、消息草稿和配额都正确后，才将其设为 true。AUTOMATION_DISABLED=true 是紧急停止开关，也允许省略 CRON_SECRET。

该进程可以运行内置调度器，使用 CRON_SECRET 调用 GET /api/jobs/automation-tick（请求头为 x-cron-secret 或 Authorization: Bearer …）。作业密钥比较采用恒定时间算法。请勿将 CRON_SECRET 放入面向浏览器的 URL 或公开日志中。

电子邮件

本地模式绝不会发送 Omentir 营销、创始人、联系表单或邮件列表电子邮件。运营通知可以使用你自己的 Resend 账户。未配置 Resend 时，外联仍可正常工作，但会跳过通知发送。

同一代码仓库为 omentir.com 和可自托管安装提供支持。托管产品身份信息（支持邮箱地址、欢迎邮件的发件人信息、公开联系渠道）位于 src/lib/hosted-identity.ts，作为云模式的有意默认设置。当 RUN_LOCALLY=TRUE 时，这些路径会被禁用。自托管用户只需配置自己的 RESEND_FROM_EMAIL（可选）。

备份

所有数据均由运营方负责。请配置定期 Firestore 托管导出或 Google Cloud 备份，将其保存在应用项目之外，并测试恢复流程。请安全备份 .env，切勿将其提交到 Git。

Firestore 还会在 rateLimits 等集合中接收运营文档（用于在应用进程间共享请求上限）。这些不是客户 CRM 数据；请将其纳入备份，或允许它们在恢复后自然重建。

升级和回滚

仅安装不可变的发布标签：

git fetch --tags
git checkout v0.x.y
docker compose up --build -d

通过检出上一个已知正常的标签并重新构建来回滚。请阅读每个版本说明中的架构或运营变更。产品发布时，只有最新的发布标签会获得安全修复。

---

面向自托管用户的默认安全设置

本节介绍自行运行 Omentir 时至关重要的保护措施。托管版 omentir.com 在适用情况下使用相同的代码路径，此外还使用本地模式不会使用的 Clerk／Whop。

锁定的安全措施

区域	行为
Firestore 客户端	firestore.rules 会拒绝所有浏览器／客户端的读写操作。只有服务器上的 Admin SDK 可以访问数据。
仓库中的密钥	.env 已加入 gitignore。仅提供空白的 .env.example。切勿提交服务账号 JSON 或 API 密钥。
本地密码	默认要求设置密码；如需开放访问，必须显式设置 LOCAL_ALLOW_OPEN_ACCESS=true。
Docker 端口	默认绑定到环回地址（127.0.0.1:3000）。
网站分析／预览 API	需要已登录的会话。未通过身份验证的调用方无法消耗 Gemini 配额，也无法将服务器用作开放式网站抓取器。
潜在客户预览 API	仅限已登录用户使用，并设有速率限制和 JSON 请求体大小上限。
Agent API 和 MCP	使用 Bearer Agent 令牌（以哈希形式存储）。设有单令牌和全局速率限制。修改操作的请求体上限约为 256 KB。
共享速率限制	使用进程内计数器和由 Firestore 支持的可过期上限（rateLimits），防止多个容器叠加配额。
作业路由（/api/jobs/*）	需要通过恒定时间比较验证 CRON_SECRET / AUTOMATION_JOB_SECRET。
登录重定向	?next= 仅允许安全的同源相对路径。
HTTP 安全标头	CSP（框架、form-action、object-src、base-uri 等）、X-Frame-Options: DENY、HSTS、nosniff、引荐来源策略。

应有的成本与滥用控制

即使自托管环境中只有你一个用户，应用仍会强制执行配额上限，防止泄露的 Agent 令牌、有缺陷的集成或遭入侵的浏览器会话无限调用 Gemini 或 Unipile：

• 网站分析（POST /api/website-analysis）：需要身份验证；设有共享的每小时速率限制。
• 网站预览（POST /api/website-preview）：需要身份验证；设有共享的每小时速率限制。
• 引导流程潜在客户预览（POST /api/onboarding/lead-preview）：需要身份验证；设有共享的每小时速率限制；请求体大小设有上限。
• Agent API（/api/agent/v1/*，包括 MCP）：通过 Authorization: Bearer omentir_agent_… 进行身份验证；设有共享的每分钟速率限制；写入操作的 JSON 请求体大小设有上限。
• 问卷／Unipile Webhook／连接回调：均设有速率限制；Webhook 需要共享密钥，连接回调需要一次性使用的令牌。

用于分析的网站抓取仍会屏蔽私有／保留 IP 地址（SSRF 防护：将 DNS 固定到已验证的公共地址、不允许带凭据的 URL、重定向后重新验证）。

多进程／多容器说明

如果你针对同一个 Firestore 项目运行多个 Node 进程或副本：

• 共享速率限制使用 rateLimits 集合，因此配额会在各进程间统一生效。
• 自动化仍依赖 Firestore tick 锁，确保同一时间只有一个自动化 tick 推进工作。
• 进程内映射（例如登录尝试计数器）按进程独立，并会在重启后重置；请将其视为软性防护，不要将其作为唯一的控制措施。

自托管不包含的内容

• 多用户 SaaS 身份验证（Clerk）、账单（Whop）或 Omentir 营销邮件。
• 自动公开应用——你必须主动在前面配置反向代理并开放防火墙端口。
• 离线／隔离网络运行——完整功能仍需要 Firebase、Unipile 和 Gemini/Vertex。

---

安全默认设置（自动化）

• 本地模式使用带签名且会过期的会话；除非显式启用开放访问，否则必须设置密码。
• 除非设置 ENABLE_LIVE_AUTOMATION=true，否则自动化将以 dry-run 模式运行。
• AUTOMATION_DISABLED=true 会阻止调度器启动和手动执行 tick。
• 本地会移除商业版方案的配额上限，但仍会执行邀请间隔、每日配额、重试上限和每 tick 发送预算。
• 验证不得发送真实的外联消息。请使用 dry-run 输出和 automationRuns。

---

开发

bun install
bunx tsc --noEmit
bun run build

服务器启动时会验证运行时配置，因此构建和贡献者 CI 无需密钥。

支持

对于 Omentir 中可复现的缺陷和功能提案，请使用 GitHub issues。请提供发布标签、部署方式、已清理的日志和复现步骤。

提供商设置、账单、配额、服务中断和账户限制问题，请联系 Firebase/Google Cloud、Unipile、LinkedIn、Gemini 或 Resend 的支持团队。社区或许能提供帮助，但本项目无法为可自托管用户运营或调试第三方账户。

请勿发布机密、客户数据、访问令牌、服务账户 JSON 或私密的 LinkedIn 消息。

---

许可证和商标

MIT — 参见 LICENSE。软件许可证不授予 Omentir 名称和徽标的使用权；分支项目应更换品牌，而不是自称为 Omentir 或 omentir.com。

**第三方声明：**生产依赖主要采用 MIT、Apache-2.0、BSD 或 ISC 许可证。值得注意的非 MIT 生产许可证：Apache-2.0（Google GenAI、Firebase Admin 和相关 Google 库）、LGPL-3.0-or-later（@img/sharp-libvips-*，动态链接的平台二进制文件）、MPL-2.0 OR Apache-2.0（dompurify，双重许可）以及 CC-BY-4.0（caniuse-lite，传递依赖的数据归属要求）。package.json 中的 "private": true 仅表示“不要将此软件包发布到 npm registry”，并不表示源代码已闭源。public/ 下的博客和营销图片是项目资产；重新分发这些图片的分支项目不应暗示与 Omentir 或 omentir.com 存在关联。