open-connector 的一些使用说明与部署

[oldman1969]

open-connector 使用说明与部署

终端统一使用 PowerShell。容器引擎使用 Podman（WSL2 machine）。目标：部署后重启电脑自动恢复，无需手动起终端。

---

目录

1. 概述
2. 认识三个仓库
3. 仓库之间的关系
4. open-connector 的协议层与开发者接入层
5. 部署
6. 接入方式详解
7. 如何添加自己的 Provider
8. 日常运维
9. 常见坑
10. 总结：如何选择

---

概述

OOMOL 开源生态围绕"AI agent 调用 SaaS 连接器"这个核心需求，由三个 GitHub 仓库组成。核心产品是 open-connector——一个开源的连接器网关运行时（Composio 的替代方案），统一存储第三方凭证，对外暴露 1,000+ providers、10,000+ actions 供 AI agent / 应用调用。

无论你用开源自托管还是 OOMOL SaaS 版本，provider id、action id、schema 契约都是同一套。

一图看懂整体架构

本机
 ├─ open-connector (Podman 容器，http://localhost:3000)
 │    ├─ 凭证保险箱（GitHub PAT / Gmail OAuth 加密落盘）
 │    ├─ Catalog（action 注册表 + schema）
 │    └─ 执行引擎（SSRF fetch → provider API）
 │
 ├─ oo-cli (命令行中继工具)
 │    └─ 让本机 AI agent 通过 shell 调 connector action
 │
 └─ Claude Code（你）
      ├─ /oo  → shell → oo-cli → open-connector
      └─ MCP  → JSON-RPC → open-connector  （不经过 shell）

凭证边界：第三方 token（GitHub PAT、Gmail OAuth 等）只存在 open-connector 容器里；oo-cli、SDK、MCP 调用方全程只接触 connectionName（一个 alias 字符串）和执行结果，真正的 token 从不到客户端。

---

认识三个仓库

1. open-connector（连接器网关运行时）

仓库：oomol-lab/open-connector

定位：开源的连接器网关运行时。可以部署在本机 Docker / Podman、Fly.io、Cloudflare Workers，或使用 OOMOL 托管运行时。

模块	作用
Catalog	1,000+ providers、10,000+ actions 的统一注册表，每个 action 带完整 schema（输入/输出/scopes）
凭证管理	API key、OAuth2、自定义凭证、no_auth——凭证只存在运行时，不暴露给外部调用方
Action 执行	解析凭证 → 策略校验 → SSRF-guarded fetch 调 provider API → 返回结果
运行时控制	runtime token、action allow/block 策略、文件中转、脱敏日志
接入层	以 2 种协议对外暴露 5 种接入方式

技术栈：Node.js 22+ / TypeScript（原生） / Hono（HTTP 框架）/ oxfmt + oxlint

2. oo-cli（本机 agent 中继 CLI）

仓库：oomol-lab/oo-cli

定位：本机 AI agent 的命令行中继工具。在你的 agent 和 open-connector 运行时之间充当智能客户端。

模块	作用
身份管理（login/auth）	把本机绑定到某个 OOMOL 账号，或指向一个自托管 open-connector
能力发现（connector search/schema）	向运行时搜索 action、拉取 schema、本地缓存
能力执行（connector run）	本地校验输入 → 发 HTTP 请求到运行时执行 action
异步轮询	对长耗时 action（转写、文档理解等）自动管理 polling（默认 6 小时超时）
Skill 分发（skills）	首次启动时把内置 skill markdown 注入本机 agent host，教 agent 何时/如何调 oo
LLM 配置（llm）	为本地代码提供 OOMOL LLM 的 OpenAI 兼容 base URL / api key / model name
文件管理（file）	本地上传 → 云端 downloadUrl

技术栈：Bun / TypeScript strict ESM / zod / pino

3. connector-sdk（TypeScript 客户端 SDK）

仓库：oomol-lab/connector-sdk

定位：给应用/agent 开发者用的 TypeScript 薄 HTTP 客户端库（npm 包 @oomol-lab/connector）。

类	用途	auth
OpenConnector	自托管 open-connector 运行时	runtime token
Connector	OOMOL 托管，个人连接	OOMOL 账号
ProjectConnector	OOMOL 托管，SaaS 终端用户连接	项目级 auth

技术栈：TypeScript / npm 包

---

仓库之间的关系

               ┌──────────────────────────┐
               │   open-connector (运行时)   │
               │   - 凭证边界 (Gmail/GitHub token 存这里)  │
               │   - Catalog + SSRF fetch + 策略 + 日志    │
               └────┬─────┬─────┬─────┬─────┘
                    │     │     │     │
          POST /v1  │     │  /mcp  │  /api & / (Web)
                    │     │  MCP   │
          ┌─────┐  │  ┌──┴──┐  ┌─┴──────┐
          │ SDK  │──┘  │ MCP │  │ Web    │
          │(npm) │     │host │  │Console │
          └─────┘     └─────┘  └────────┘
            │                        │
       应用/agent 开发者          本机 agent

  ┌──────────┐
  │ oo CLI   │ ← 也在 POST /v1 的 HTTP 路径上
  │ (本机中继)│    但额外带：skill 分发、schema 缓存、
  └──────────┘    本地校验、异步轮询、失败脱敏
     │
  本机 AI agent (Claude Code / Codex ...)

核心理解：

• open-connector 是"背板"——并不要求 oo-cli 或 connector-sdk 才能用。任何人用 curl 调 /v1/actions/* 就能用。它是所有接入方式的共同目标后端。
• oo-cli 和 connector-sdk 都是"HTTP 客户端"——底层都走 /v1 REST API，只是面向不同使用者、带不同附加值。
• 凭证边界在运行时——Gmail OAuth token、GitHub PAT 等第三方凭证存在 open-connector 运行时那一侧。oo-cli 只存身份配置，SDK 只传 runtime token。真正的 token 从不到客户端。

---

open-connector 的协议层与开发者接入层

open-connector 从设计上分为两层：

协议层（2 种协议）

这是 open-connector 服务端 Hono 路由真正区分的网络协议——只有两种：

协议	路由	说明
HTTP REST	GET/POST /v1/* + GET/POST/PUT/DELETE /api/* + /openapi.json	JSON over HTTP，统一信封 { success, data, meta }
MCP	POST /mcp（Streamable HTTP transport）	Model Context Protocol，JSON-RPC

开发者接入层（5 种方式）

这 5 种是面向不同使用场景的客户端形态。MCP 是独立协议，其余 4 种底层均为 HTTP REST：

接入方式	底层协议	所属仓库	给谁用
HTTP / OpenAPI	HTTP REST	open-connector	任何能发 HTTP 的客户端、脚本、生成器
Connector SDK	HTTP REST	connector-sdk	应用/agent 开发者（写代码集成）
oo CLI	HTTP REST	oo-cli	本机 AI agent（shell 中继）
MCP	MCP	open-connector	MCP-capable agent host（原生协议）
Web Console	HTTP REST（/api/*）	open-connector（web/）	运维/调试者（浏览器 Dashboard）

---

部署

目标架构

本机两个组件：
  open-connector  →  http://localhost:3000   (Podman 容器，存凭证、执行 action、开机自启)
  oo-cli (oo)     →  本机命令，指向上面那个运行时 (按需调用的 CLI，装一次即可)

第 0 步：安装 Podman 与拉取源码

0.1 安装 Podman

winget install RedHat.Podman

Podman on Windows 依赖 WSL2。若 podman machine init 报 WSL 相关错误，先跑 wsl --install 并重启。

重开终端后验证：

podman --version                # 应输出 4.x+（本机 5.6.0）

0.2 初始化并启动 podman machine

podman machine init             # 创建 WSL2 machine（仅首次，耐心等）
podman machine start            # 启动 machine
podman machine list             # 确认状态为 Currently running

以后 machine 不会开机自启，第 2 步会配登录时自动 podman machine start。

0.3 安装 Node.js

winget install OpenJS.NodeJS.LTS

重开终端后验证：

node --version                  # 需 22+（本机 v24）

0.4 拉取源码

mkdir D:\software\open_connector\package -Force
cd D:\software\open_connector\package
git clone https://github.com/oomol-lab/open-connector.git
git clone https://github.com/oomol-lab/oo-cli.git

没装 git：winget install Git.Git。也可以拉你自己的 fork，方便后续改 provider。

拉取后目录结构：

D:\software\open_connector\package\
├── open-connector\     ← 运行时源码（第 1 步部署）
└── oo-cli\             ← CLI 源码（第 3 步部署）

Bun 在第 3 步装 oo-cli 时再装。

第 1 步：部署 open-connector（Podman 持久化）

进入目录：

cd D:\software\open_connector\package\open-connector

1.1 生成加密密钥

这个密钥用来加密落盘的 provider 凭证。生成后务必保存好，丢了已存的凭证就解不开。

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

1.2 创建 .env

在 open-connector\ 目录下新建 .env（已被 gitignore）：

# 用第 1.1 步生成的密钥替换
OOMOL_CONNECT_ENCRYPTION_KEY=粘贴你生成的密钥

# 本地自用先留空（容器默认只绑 127.0.0.1，仅本机可访问）
OOMOL_CONNECT_ADMIN_TOKEN=
OOMOL_CONNECT_RUNTIME_TOKEN=

1.3 创建 docker-compose.override.yml

仓库自带的 docker-compose.yml 没有 restart 策略。在同目录新建 docker-compose.override.yml（compose 会自动叠加它，不动原文件）：

services:
  connector:
    restart: unless-stopped
    environment:
      OOMOL_CONNECT_ENCRYPTION_KEY: ${OOMOL_CONNECT_ENCRYPTION_KEY}
      OOMOL_CONNECT_ADMIN_TOKEN: ${OOMOL_CONNECT_ADMIN_TOKEN}
      OOMOL_CONNECT_RUNTIME_TOKEN: ${OOMOL_CONNECT_RUNTIME_TOKEN}

1.4 验证配置

podman compose config | Select-Object -First 30

应能看到 restart: unless-stopped 和你填的 OOMOL_CONNECT_ENCRYPTION_KEY。

1.5 启动容器

podman compose up -d

第一次会拉镜像（ghcr.io/oomol-lab/open-connector:latest，几百 MB），耐心等。

1.6 验证

# 容器状态（应 Up）
podman compose ps

# 健康检查
curl.exe -s http://localhost:3000/v1/health

# 跑一个无需凭证的 action（验证执行链路）
curl.exe -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories `
  -H "content-type: application/json" `
  -d '{}'

# 浏览器打开 Web Console
# http://localhost:3000

PowerShell 里必须用 curl.exe（真 curl），不能用 curl（那是 Invoke-WebRequest 的别名）。

三项都通过，open-connector 部署完成。数据持久化在 Docker 命名卷 connector-data，删容器不丢数据。

第 2 步：配置开机自启（Podman 专有，关键）

Podman 无守护进程，restart: unless-stopped 只在 machine 运行期间生效。Windows 重启后 machine 不会自启，需要登录时自动起 machine + 容器。

2.1 创建启动脚本

在 open-connector\ 目录下新建 start-open-connector.bat：

@echo off
podman machine start
cd /d "D:\software\open_connector\package\open-connector"
podman compose up -d

2.2 注册登录自启（二选一）

方式 A：任务计划程序（推荐，静默无窗口）

以管理员身份打开 PowerShell：

schtasks /create /tn "OpenConnector AutoStart" /tr "D:\software\open_connector\package\open-connector\start-open-connector.bat" /sc onlogon /rl highest /f

方式 B：启动文件夹（不需要管理员，但登录时闪一下黑窗）

Win+R → 输入 shell:startup → 把 start-open-connector.bat 的快捷方式拖进打开的文件夹。

2.3 验证自启

重启电脑、登录 Windows，等十几秒后：

podman compose ps
curl.exe -s http://localhost:3000/v1/health

能通就说明自启生效。之后每次开机，open-connector 自动回来。

删除自启任务：schtasks /delete /tn "OpenConnector AutoStart" /f

第 3 步：安装 oo-cli

oo-cli 是按需调用的 CLI，装一次即可，不常驻。

3.1 装 Bun（oo-cli 要求 1.3.x）

irm bun.sh/install.ps1 | iex

重开终端后验证：

bun --version

3.2 装 oo-cli 依赖

cd D:\software\open_connector\package\oo-cli
bun install

3.3 让 oo 全局可用

新建一个专门放命令的目录（如 D:\software\open_connector\package\oo-cli-path），在里面创建 oo.bat：

@echo off
bun run --silent D:\software\open_connector\package\oo-cli\index.ts -- %*

必须用绝对路径指向 index.ts。仓库自带 oo.bat 用相对路径 .\index.ts，只在 oo-cli 目录下有效。

然后把该目录加进用户 PATH（永久生效，不需要管理员）：

$bin = "D:\software\open_connector\package\oo-cli-path"
$old = [Environment]::GetEnvironmentVariable("Path", "User")
if ($old -notlike "*$bin*") {
    [Environment]::SetEnvironmentVariable("Path", "$old;$bin", "User")
}

重开终端后验证：

oo --version

PATH 改动只对新开的终端生效。VS Code 需完全重启（不是重开终端窗口）才能让扩展读到新 PATH。

第 4 步：把 oo 连到本地 open-connector

oo connector login http://localhost:3000

这条写进 oo 的 connector.toml（持久配置）。因为 .env 里 runtime token 留空，不需要 --token。

验证闭环：

oo connector search "top hacker news" --json
oo connector run hackernews --action get_top_stories --data '{}' --json

第二条应返回 story_ids 数组。通了说明 oo-cli ↔ 本地 open-connector 链路完整。

第 5 步（可选）：配 GitHub 凭证 + 接入 AI agent

# 存 GitHub PAT
$body = '{"authType":"api_key","values":{"apiKey":"github_pat_你的token"}}'
Invoke-RestMethod -Method Put -Uri http://localhost:3000/api/connections/github `
  -ContentType 'application/json' -Body $body

# 调 GitHub action
oo connector run github --action get_current_user --data '{}' --json

也可以在 Web Console（http://localhost:3000）的 Connections 页面图形化配置。

让本机 AI agent 用上 oo：

oo skills preflight       # 检测到的 agent host
oo skills install         # 注入 bundled skill

之后在 agent 里说 /oo 看一下我的github账户名，agent 会按 skill 状态机走 search → schema → run。

---

接入方式详解

1. HTTP / OpenAPI

是什么：直接调 /v1 REST API。无依赖，无需 SDK/CLI。任何语言、任何 HTTP client 都能用。

适合：写脚本、一次性调试、非 TS 语言集成、CI/CD pipeline。

核心端点：

方法	端点	作用
GET	/v1/actions	列所有 action，支持 ?service= 过滤
GET	/v1/actions/search?q=	语义搜索 action
GET	/v1/actions/:actionId	拿一个 action 的完整 schema
POST	/v1/actions/:actionId	执行 action
GET	/v1/apps	列已连接的服务及其状态
POST	/v1/proxy/:service	透传 provider API
GET	/openapi.json	OpenAPI 3.1 规范文档

完整调用流程（4 步）：

第1步：发现
  curl -s http://localhost:3000/v1/actions?service=github

第2步：配置连接
  curl -s -X PUT http://localhost:3000/api/connections/github \
    -H "content-type: application/json" \
    -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'

第3步：执行 action
  curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
    -H "content-type: application/json" \
    -d '{"input":{}}'

第4步：读响应
  { "success": true, "data": { ... }, "meta": { "executionId": "..." } }

鉴权区分：

端点类	用哪个 token	请求头
/v1/*, /mcp	runtime token	Authorization: Bearer oct_...
/api/*, /docs, Web Console	admin token	Authorization: Bearer <admin>

本地开发没设 token 就是无鉴权模式。

OpenAPI 附赠：浏览器开 http://localhost:3000/docs（Scalar 交互式文档），或 /openapi.json 导入 openapi-generator 生成客户端。

---

2. Connector SDK

是什么：npm 包 @oomol-lab/connector，给开发者在自己代码里调 open-connector action 的 TypeScript 客户端。把 URL 拼接、auth 头、序列化全部藏掉。

适合：在自己 agent/app 代码里集成 connector 能力，不想手写 HTTP。

调用流程：

// 安装：npm install @oomol-lab/connector

import { OpenConnector } from "@oomol-lab/connector";

const open = new OpenConnector({
  baseUrl: "http://localhost:3000",
  runtimeToken: process.env.OOMOL_CONNECT_RUNTIME_TOKEN,
});

// 调用：open.<service>.<action>(input)
const stories = await open.hackernews.get_top_stories({});
const user = await open.github.get_current_user({});

和 HTTP 直接调的区别：SDK 省掉 URL 拼接、auth 头、序列化/反序列化，不做额外逻辑。

---

3. oo CLI

是什么：安装在本地机器上的命令行工具，让本机 AI agent 在 shell 里调 open-connector。oo 先把内置 skill 注入 agent host，skill 再驱动 agent 按状态机走 search → schema → validate → run。

适合：本机已有 agent host，想让 agent 调 Gmail/Slack/GitHub/Notion 等。不需要写代码。

两种配置模式：OOMOL 账号 vs 自托管 connector

oo-cli 有两套独立配置，决定它连哪个后端、解锁哪些能力。两者可并存，不是二选一：

	OOMOL 账号模式	自托管 connector 模式
配置命令	oo login	oo connector login <url> [--token]
存哪	本地 auth.toml（OOMOL apiKey）	本地 connector.toml（URL + 可选 token）
oo connector 命令打到哪	OOMOL 托管运行时	你的 open-connector（如 http://localhost:3000）
第三方凭证存哪	OOMOL 云端	你的本地 open-connector 容器
解锁的非 connector 能力	skill 目录搜索/安装、托管 AI（OCR/翻译/TTS）、LLM 配置	仅 connector 命令；skills/llm/file 仍需 OOMOL 账号

connector 命令的优先级是"自托管优先"。resolveConnectorTarget() 按顺序决定打哪个后端：

1. env OO_CONNECTOR_URL        → 自托管（显式，最高）
2. env OO_API_KEY              → OOMOL 托管（显式）
3. connector.toml              → 自托管（持久化）
4. auth.toml 里的 OOMOL 账号    → OOMOL 托管（兜底）

所以配了自托管 connector 后，oo connector 命令始终走本地，不会被 OOMOL 账号 hijack。

配置方法（PowerShell）：

# 模式 A：只用自托管（本地部署 open-connector 时的推荐做法）
oo connector login http://localhost:3000

# 模式 B：用 OOMOL 账号（解锁 skill 目录和托管能力）
oo login                          # 设备登录，浏览器跳转授权

# 两者并存：先 connector login，再 oo login，互不影响
oo auth status --json             # 查看当前两套配置状态

凭证安全：自托管模式下，GitHub PAT / Gmail token 全程留在你的本地 open-connector 容器，OOMOL 云碰不到。oo login 不会把已存的本地凭证搬到云端。

实例：用 oo 列出 GitHub 仓储（含数据流程）

# 1. 发现 action
oo search "list github repositories" --json
# → 返回 { service:"github", name:"list_my_repositories", authenticated:true }

# 2. 检查契约
oo connector schema github.list_my_repositories --json
# → inputSchema: {} (无必填)，outputSchema: { repositories:[{name,full_name,private,...}] }

# 3. 执行
oo connector run github --action list_my_repositories --data '{}' --json
# → { data:{ repositories:[...] }, meta:{ executionId:"..." } }

数据流程：

用户: "/oo 看一下github有哪些仓储"
  │
  ▼ agent 按 skill 状态机
oo search "list github repositories"  ──HTTP──▶ open-connector GET /v1/actions/search
  │
  ▼
oo connector schema github.list_my_repositories ──HTTP──▶ GET /v1/actions/github.list_my_repositories
  │
  ▼ agent 按 schema 构造 payload {}
oo connector run github --action list_my_repositories --data '{}' --json
  │
  ▼ resolveConnectorTarget() → connector.toml → http://localhost:3000
  │   loadConnectorActionSchema() → 本地缓存命中
  │   validateConnectorActionInput() → 本地校验 {}
  ▼
POST http://localhost:3000/v1/actions/github.list_my_repositories   body:{input:{}}
  │
  ▼ open-connector ActionRunner.run(caller="http")
  │   getConnectionSummary("github") → 从 sqlite 取出加密的 GitHub PAT → 解密
  │   executeAction → executor → context.fetcher(SSRF) → GitHub API /user/repos
  ▼
返回 { data:{repositories:[16个]}, meta:{executionId} } → agent 报告 "共 16 个仓储"

注意：oo 全程没碰 GitHub token，只传了 connectionName。PAT 的解密、出网调 GitHub 都在 open-connector 容器内完成。

---

4. MCP

是什么：Agent host 通过原生 MCP（Model Context Protocol）协议直接连 open-connector。不走 /v1 REST，走 POST /mcp（Streamable HTTP JSON-RPC）。

适合：MCP-native 的 agent host（Claude Desktop、Claude Code 等）——不用装 CLI，不用引 SDK，标准协议原生支持。

4 个 MCP tool

open-connector 的 MCP server 暴露 4 个"元 tool"（定义在 src/mcp.ts），通过组合它们触达全部 10000+ action：

tool	作用	等价 HTTP
list_apps	列已连接的服务	GET /v1/apps
search_actions	语义搜索 action	GET /v1/actions/search?q=
get_action_guide	取某 action 的人可读指南	GET /api/actions/:id/agent.md
execute_action	执行 action	POST /v1/actions/:id

不把每个 action 暴露成一个 MCP tool（会导致几万个 tool），而用"搜索 + 动态执行"的元 tool 设计。

配置进 Claude（Claude Code / Claude Desktop）

Claude Code——一条命令：

claude mcp add --transport http open-connector http://localhost:3000/mcp -s user

参数含义：--transport http（HTTP 传输）/ open-connector（服务器名，工具前缀成 mcp__open-connector__*）/ URL / -s user（用户级，所有项目可用）。

或手写 .mcp.json（项目级，可提交）：

{
  "mcpServers": {
    "open-connector": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

设了 runtime token 时加 headers: { "Authorization": "Bearer oct_..." }。

Claude Desktop——编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "open-connector": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

保存后完全退出客户端再重开。验证：claude mcp list（Claude Code）或桌面端左下角工具图标。

端点必须可达：容器停了 MCP 工具就超时——所以容器开机自启对 MCP 同样关键。

实例：用 MCP 列出 GitHub 仓储（含数据流程）

Claude 自主按需调用 4 个 tool，你只需要用自然语言说话：

用户对 Claude: "看一下我 github 有哪些仓储"
  │
  ▼ Claude 从 tools/list 看到 4 个 tool，自主决定调用链
mcp__open-connector__search_actions { query:"list github repositories" }
  │ ──JSON-RPC──▶ POST /mcp → 返回匹配 action
  ▼
mcp__open-connector__execute_action { actionId:"github.list_my_repositories", input:{} }
  │
  ▼ POST /mcp → open-connector MCP server → ActionRunner.run(caller="mcp")
  │   getConnectionSummary("github") → 解密本地存的 GitHub PAT
  │   executeAction → executor → context.fetcher(SSRF) → GitHub API /user/repos
  ▼
返回 { repositories:[16个] } → Claude 报告 "共 16 个仓储"

关键点：你不需要指定工具名、参数、调几次——Claude 根据 tool 的 description 匹配你的意图，自主完成多步链式调用。和 oo 路径相比，两者打到同一个 open-connector、用同一份 GitHub 凭证、走同一个 ActionRunner.run()，区别仅在 caller 标记（http vs mcp）和接入协议。

MCP vs oo CLI 协议区别

	MCP	oo CLI
协议	MCP（JSON-RPC）	HTTP REST（/v1/actions/*）
Agent 如何发现 action	MCP tools/list 原生机制	oo skill 文本教 agent 用 oo search
需要装什么	不装 oo-cli，agent host 自带 MCP	需要装 oo（含 skill 分发）
payload 校验	仅服务端	本地 + 服务端双重校验

---

5. Web Console

是什么：open-connector 自带的浏览器管理面板，Docker/Podman 下在 http://localhost:3000/。

功能：

• Connector Catalog：浏览/搜索 provider，展开看 action 和凭证配置
• 连接管理：配 api key / OAuth client / 自定义凭证，命名连接
• Runtime Token 管理：创建/删除 runtime token（给 SDK / HTTP / MCP 用）
• Action 调试：在线看 schema、填参数、执行、看结果
• 执行日志：最近 run log（脱敏输入、connection profile、ok/errorCode）

Web Console 是唯一走 /api/* 管理端点的接入方式，也是唯一供"人"而不是"程序/agent"用的。

---

如何添加自己的 Provider

open-connector 的 provider 都是 src/providers/<service>/ 下的源码。添加一个完整 provider 只需要三个文件，然后跑生成命令即可注册进 catalog。

Provider 文件结构

src/providers/<service>/
  definition.ts      # 必需：catalog 源数据（service名、displayName、authTypes、actions清单）
  actions.ts         # 推荐：action 的 inputSchema / outputSchema 定义
  executors.ts       # 必需：action 的实际执行逻辑（懒加载）
  scopes.ts          # 可选：非平凡的 provider-native scopes
  runtime-*.ts       # 可选：某个 API 域的运行时辅助逻辑

关键约束：

• 不要建 index.ts barrel 文件
• definition.ts 不能 import executors.ts（保持 definition 可无网络/凭证导入，executor 懒加载）
• schema 用 src/core/json-schema.ts 的 s helper 构建，别复制 catalog JSON
• 所有出网必须走 context.fetcher（SSRF-guarded），不能用 global fetch
• 不要手改生成的 registry.generated.ts / catalog/apps/*.json

按鉴权类型选样板

鉴权	参考 provider	用哪个 helper
无鉴权（公开 API）	hackernews / nasa	defineProviderExecutors + context.fetcher
API key	avoma / attention	defineApiKeyProviderExecutors
OAuth2 + API key 双支持	github	defineBearerProviderExecutors
OAuth2 only	gmail	defineOAuthProviderExecutors + credential 校验
自定义凭证 / 用户配 base URL	clickhouse / dataforseo	custom credential + URL 校验
需要代理透传	baselinker / autotask	provider proxy + endpoint guards

最小示例：加一个 no_auth 的内部服务

假设要接一个内部 status 页 API（无鉴权，GET /api/incidents）：

definition.ts —— 声明 provider 元数据 + action 清单：

import type { ProviderDefinition } from "../../core/types.ts";
import { internalStatusActions } from "./actions.ts";

export const provider: ProviderDefinition = {
  service: "internal_status",
  displayName: "Internal Status",
  categories: ["Monitoring"],
  authTypes: ["no_auth"],
  auth: [{ type: "no_auth" }],
  homepageUrl: "https://status.internal.example.com",
  actions: internalStatusActions,
};

actions.ts —— 定义 action 的 schema（用 s helper）：

import { defineProviderAction } from "../../core/provider-definition.ts";
import { s } from "../../core/json-schema.ts";

export const internalStatusActions = [
  defineProviderAction("internal_status", "get_incidents")
    .description("Get current open incidents from the internal status page.")
    .input(
      s.object({
        severity: s.integer("severity", { minimum: 1, maximum: 5 })
          .optional()
          .describe("Filter by severity level (1-5)."),
      }),
    )
    .output(
      s.object({
        incidents: s.array(
          s.object({
            id: s.string("id"),
            title: s.string("title"),
            status: s.string("status"),
            severity: s.integer("severity"),
            createdAt: s.string("createdAt"),
          }),
        ),
      }),
    )
    .build(),
];

executors.ts —— 实现 action 逻辑（用 context.fetcher 出网）：

import type { ProviderExecutors } from "../../core/types.ts";
import { defineProviderExecutors, readProviderJson, setSearchParams } from "../provider-runtime.ts";

interface InternalStatusContext {
  fetcher: typeof fetch;
}

const handlers: Record<string, (input: Record<string, unknown>, context: InternalStatusContext) => Promise<unknown>> = {
  async get_incidents(input, context) {
    const url = new URL("https://status.internal.example.com/api/incidents");
    if (input.severity !== undefined) {
      setSearchParams(url, { severity: String(input.severity) });
    }
    return readProviderJson(await context.fetcher(url), "internal_status incidents");
  },
};

export const executors: ProviderExecutors = defineProviderExecutors<InternalStatusContext>({
  service: "internal_status",
  handlers,
  createContext(_context, fetcher): InternalStatusContext {
    return { fetcher };
  },
});

实现流程

1. 定 service id（稳定小写）和最小可运行 action 集（宁少而能跑，不要 catalog-only 占位）
2. 读官方 API 文档 + 1~2 个相近 provider 的源码
3. 写 definition.ts / actions.ts / executors.ts（+ 必要的 runtime-*.ts）
4. npm run generate:catalog —— 注册进 catalog（生成 registry.generated.ts 和 catalog/apps/*.json，这俩是 gitignore 的）
5. npm run fix-check —— lint + 格式化 + typecheck
6. 改了 shared helper 或加了非平凡逻辑时，补针对性测试
7. review diff：确认无生成文件手改、无第三方品牌资产复制、import 保持懒

跑完 generate:catalog 后，你的 provider 会出现在：

• /v1/providers、/v1/actions catalog 接口
• Web Console 的 provider 浏览页
• MCP 的 search_actions 搜索结果
• oo connector search 的结果

五种接入方式立刻通用——因为它们共用同一个 catalog。

贡献回上游 vs 私有自托管

路径	适合	注意
PR 回 oomol-lab/open-connector	通用的、别人也会用的 provider	不抄第三方 logo/截图/API spec，只放有权利分发的内容
自己的 fork / 自托管部署	内部系统、私有 API	没有上述限制，fork 加完私有 provider 自己用

---

日常运维

cd D:\software\open_connector\package\open-connector
podman compose logs -f                              # 实时日志
podman compose ps                                   # 状态
podman compose restart                              # 改 .env 后重启生效
podman compose down                                 # 停止并删容器（数据保留）
podman compose up -d                                # 再启动
podman compose pull; podman compose up -d           # 升级镜像

改了 .env 后必须 podman compose up -d（或 restart）才生效——环境变量在容器启动时注入。

---

常见坑（PowerShell）

问题	原因	解决
curl 报 "找不到驱动器 http"	PowerShell 的 curl 是 Invoke-WebRequest 别名	用 curl.exe
--data '{}' 报 "Single quotes not allowed in JSON"	在 cmd 里单引号被原样传入	PowerShell 里 '{}' 正常；cmd 里用 "{}"
复杂 JSON 转义麻烦	PowerShell/curl 引号叠加	用 Invoke-RestMethod，或 --data "@payload.json" 从文件读
换行 \ 不识别	那是 bash 语法	PowerShell 换行用反引号 `
改了 PATH 但 oo 找不到	旧终端是改 PATH 前启动的	重开终端；VS Code 需完全重启
podman compose 打印 "Executing external compose provider"	借用 Docker Desktop 的 docker-compose.exe 做前端	不影响功能，可忽略
action 偶发 fetch failed (500)	容器刚起、DNS 还没热	重试一次即可

---

文件清单

部署后涉及的文件：

文件	作用
open-connector\.env	加密密钥 + 可选 token（gitignore）
open-connector\docker-compose.override.yml	加 restart 策略 + 从 .env 注入变量
open-connector\start-open-connector.bat	登录时自启 machine + 容器
oo-cli-path\oo.bat	oo 全局命令（绝对路径指向 index.ts）
oo 的 connector.toml	oo 连接本地 open-connector 的配置

---

总结：如何选择

你要做什么                                                         → 用什么
────────────────────────────────────────────────────────────────────────────
部署一个连接器网关，让 AI agent/应用调用 SaaS 工具                  → open-connector
在本机 AI agent 里直接调 Gmail/Slack/GitHub（不想写代码）          → oo CLI
在自己写的 app/agent runtime 代码里调 connector action              → Connector SDK
用 MCP-native 的 agent host 原生接入（不想装 CLI、不想引 SDK）     → MCP
写脚本 / curl / CI Pipeline / 非 TS 的客户端                      → HTTP / OpenAPI
浏览 provider、配凭证、debug、看执行日志                          → Web Console
open-connector 没有我需要的 provider/action                       → 在 src/providers/ 自己加

路径收敛：不管你选哪条接入路径，最终都经过同一套执行管线：

接入通道 → 解析 connectionName → 取凭证(刷新OAuth/解密) → 策略校验
         → schema 二次校验      → SSRF fetch provider    → 写脱敏run log
         → 返回结果
                  ↑
           ActionRunner.run()
         (action-runner.ts:44)

这条管线不关心 caller 是 "http" / "mcp" / "web"——行为完全一致。这就是"一个运行时，多种接入方式"在代码层的实质。