Janee

🚀 Janee 🔐

Janee是一款藉助MCP為AI智能體提供密鑰管理的工具，它能保障API密鑰的安全存儲與使用，為AI智能體的API訪問保駕護航。

AI智能體需要API訪問權限才能發揮作用，但它們不應直接持有你的原始API密鑰。Janee介於智能體和API之間，負責注入憑證、執行策略並記錄所有操作。

✨ 主要特性

🚀 快速開始

安裝

npm install -g @true-and-useful/janee

初始化

janee init

此命令會在 ~/.janee/ 目錄下創建包含示例服務的 config.yaml 文件。

添加服務

選項1：交互式添加（推薦首次使用的用戶）

janee add

Janee將引導你完成服務添加過程：

Service name: stripe
Base URL: https://api.stripe.com
Auth type: bearer
API key: sk_live_xxx

✓ Added service "stripe"

Create a capability for this service? (Y/n): y
Capability name (default: stripe): 
TTL (e.g., 1h, 30m): 1h
Auto-approve? (Y/n): y

✓ Added capability "stripe"

Done! Run 'janee serve' to start.

如果你使用AI智能體：請參閱非交互式設置以瞭解跳過提示的標誌，或查看以下特定智能體指南。

選項2：直接編輯配置文件

編輯 ~/.janee/config.yaml 文件：

services:
  stripe:
    baseUrl: https://api.stripe.com
    auth:
      type: bearer
      key: sk_live_xxx

capabilities:
  stripe:
    service: stripe
    ttl: 1h
    autoApprove: true

添加CLI工具（執行模式）

有些工具需要將憑證作為環境變量，而不是HTTP頭。執行模式可以處理這種情況：

janee add twitter --exec \
  --key "tvly-xxx" \
  --allow-commands "bird,tweet-cli" \
  --env-map "TWITTER_API_KEY={{credential}}"

現在，智能體可以通過Janee運行CLI工具，而無需看到API密鑰：

// 智能體調用janee_exec工具
janee_exec({
  capability: "twitter",
  command: ["bird", "post", "Hello world!"],
  cwd: "/home/agent/project",  // 可選的工作目錄
  reason: "User asked to post a tweet"
})

Janee會注入 TWITTER_API_KEY 環境變量並啟動進程，運行命令並返回標準輸出/錯誤信息。憑證不會進入智能體的上下文。

關鍵標誌：

• --exec：配置為執行模式（CLI包裝器而非HTTP代理）
• --allow-commands：允許的可執行文件白名單（安全設置）
• --env-map：將憑證映射到環境變量
• --work-dir：子進程的工作目錄
• --timeout：最大執行時間（默認：30秒）

Git操作（自動HTTPS認證）

在執行模式下使用GitHub憑證時，Janee會自動處理git認證。無需額外配置，git push、git pull 和 git clone 操作即可正常使用：

capabilities:
  - name: git-ops
    service: github
    mode: exec
    allowCommands: [git]
    env:
      GH_TOKEN: "{{credential}}"

// 智能體可以推送代碼而無需看到令牌
janee_exec({
  capability: "git-ops",
  command: ["git", "push", "origin", "main"],
  cwd: "/workspace/my-repo"
})

Janee會檢測環境變量中包含 GH_TOKEN/GITHUB_TOKEN 的 git 命令，並創建一個臨時的askpass腳本進行HTTPS認證。命令完成後，腳本會自動清理。

添加GitHub應用程序認證（適用於自主智能體）

靜態令牌對於長期運行的智能體來說存在風險。GitHub應用程序認證可按需生成短期安裝令牌，無需長期有效的PAT。

選項1：使用create-gh-app（推薦）

npx @true-and-useful/create-gh-app create my-agent --owner @me
# 打開瀏覽器 → 創建應用程序 → 本地保存憑證

# 在你的倉庫上安裝應用程序
# https://github.com/apps/my-agent/installations/new

# 使用一個命令在Janee中註冊
npx @true-and-useful/create-gh-app janee-add my-agent

完成上述操作後，你的智能體現在可以通過Janee的MCP代理獲取短期GitHub令牌。

選項2：手動設置

janee add github-app \
  --auth-type github-app \
  --app-id 123456 \
  --pem-file /path/to/private-key.pem \
  --installation-id 789

或者通過配置文件設置：

services:
  github:
    baseUrl: https://api.github.com
    auth:
      type: github-app
      appId: "123456"
      pemFile: /path/to/private-key.pem
      installationId: "789"

工作原理：當智能體請求訪問時，Janee會使用應用程序的私鑰簽署JWT，通過GitHub的API將其交換為1小時的安裝令牌，並緩存該令牌直至過期。智能體永遠不會看到私鑰，只有短期令牌會發送到API。

啟動MCP服務器

janee serve

與智能體配合使用

支持MCP的智能體（Claude Desktop、Cursor、OpenClaw）現在可以調用 execute 工具，通過Janee進行API請求：

// 智能體調用execute工具
execute({
  capability: "stripe",
  method: "GET",
  path: "/v1/balance",
  reason: "User asked for account balance"
})

Janee會解密密鑰，發起請求，記錄所有操作，並返回響應。

📚 詳細文檔

集成

Janee可與任何支持MCP的智能體配合使用：

• OpenClaw：原生插件 (@true-and-useful/janee-openclaw)
  • 容器化智能體：請參閱容器設置指南
• Cursor：設置指南
• Claude Code：設置指南
• Codex CLI：設置指南
• 任何MCP客戶端：只需指向 janee serve

OpenClaw集成

如果你使用的是OpenClaw，可以安裝插件以獲得原生工具支持：

npm install -g @true-and-useful/janee
janee init
# 編輯~/.janee/config.yaml文件，添加你的服務

# 安裝OpenClaw插件
openclaw plugins install @true-and-useful/janee-openclaw

在智能體配置中啟用插件：

{
  agents: {
    list: [{
      id: "main",
      tools: { allow: ["janee"] }
    }]
  }
}

你的智能體現在可以使用以下工具：

• janee_list_services：發現可用的API
• janee_execute：通過Janee進行API請求

插件會自動啟動 janee serve。所有請求都會記錄到 ~/.janee/logs/ 目錄下。

MCP工具

Janee提供了三個MCP工具：

智能體可以發現可用的工具，然後通過Janee調用API。所有操作都有相同的審計跟蹤和保護機制。

配置

配置文件位於 ~/.janee/config.yaml：

server:
  host: localhost

services:
  stripe:
    baseUrl: https://api.stripe.com
    auth:
      type: bearer
      key: sk_live_xxx  # 靜態加密存儲

  github:
    baseUrl: https://api.github.com
    auth:
      type: bearer
      key: ghp_xxx

capabilities:
  stripe:
    service: stripe
    ttl: 1h
    autoApprove: true

  stripe_sensitive:
    service: stripe
    ttl: 5m
    requiresReason: true

服務：具有真實密鑰的實際API
功能：智能體可以請求的內容，並帶有相應的策略

訪問控制

控制哪些智能體可以使用哪些功能：

server:
  host: localhost
  defaultAccess: restricted   # 功能需要顯式的允許列表

capabilities:
  stripe:
    service: stripe
    ttl: 1h
    allowedAgents: ["agent-a", "agent-b"]   # 只有這些智能體可以使用

  github:
    service: github
    ttl: 1h
    # 沒有allowedAgents + defaultAccess: restricted → 沒有智能體可以使用此功能

• defaultAccess: restricted：沒有 allowedAgents 列表的功能對所有智能體隱藏
• defaultAccess: open（默認）：沒有 allowedAgents 列表的功能對所有智能體可用
• allowedAgents：每個功能的智能體名稱列表（與MCP初始化握手的 clientInfo.name 匹配）

智能體在運行時創建的憑證默認具有 agent-only 訪問權限，即只有創建該憑證的智能體可以使用，除非它通過 manage_credential 工具顯式授予訪問權限。

執行模式功能

services:
  twitter:
    auth:
      type: bearer
      key: tvly-xxx

capabilities:
  twitter:
    service: twitter
    mode: exec
    allowCommands: ["bird", "tweet-cli"]
    envMap:
      TWITTER_API_KEY: "{{credential}}"
    ttl: 1h
    autoApprove: true

執行模式功能使用 janee_exec 而不是 execute。憑證作為環境變量注入，智能體只能看到標準輸出/錯誤信息。

執行模式下的運行器強化默認設置：

• 隔離的最小環境（不繼承完整的主機環境）
• 每個命令使用臨時的 HOME 目錄
• 超時會終止進程組

運行器/授權模式（適用於容器）

當智能體在Docker容器中運行時，遠程主機上的 janee_exec 無法訪問容器文件系統。運行器/授權架構解決了這個問題：

• 授權服務：在主機上運行，持有憑證，執行策略，代理API請求
• 運行器服務：在每個容器內運行，為智能體提供MCP服務，將非執行調用轉發給授權服務，在本地運行 janee_exec

# 主機：啟動授權服務（在一個端口上提供MCP和執行授權）
janee serve -t http -p 3100 --host 0.0.0.0 --runner-key "$JANEE_RUNNER_KEY"

# 容器：啟動運行器服務（智能體與該服務通信）
janee serve -t http -p 3200 --host 127.0.0.1 \
  --authority http://host.docker.internal:3100 --runner-key "$JANEE_RUNNER_KEY"

智能體只需要設置 JANEE_URL=http://localhost:3200。

你還可以將授權服務作為獨立進程運行：

janee authority --runner-key "$JANEE_RUNNER_KEY" --host 127.0.0.1 --port 9120

請參閱運行器/授權指南以瞭解完整的架構、執行授權流程、Docker Compose示例和故障排除信息。

請求策略

使用 rules 精確控制每個功能可以發起的請求：

capabilities:
  stripe_readonly:
    service: stripe
    ttl: 1h
    rules:
      allow:
        - GET *
      deny:
        - POST *
        - PUT *
        - DELETE *

  stripe_billing:
    service: stripe
    ttl: 15m
    requiresReason: true
    rules:
      allow:
        - GET *
        - POST /v1/refunds/*
        - POST /v1/invoices/*
      deny:
        - POST /v1/charges/*  # 不能進行卡片收費
        - DELETE *

規則工作原理：

1. 首先檢查 deny 模式：顯式拒絕的規則總是優先
2. 然後檢查 allow 模式：必須匹配才能繼續
3. 未定義規則：允許所有請求（向後兼容）
4. 定義了規則但不匹配：默認拒絕

模式格式：METHOD PATH

• GET *：任何GET請求
• POST /v1/charges/*：對 /v1/charges/ 及其子路徑的POST請求
• * /v1/customers：對 /v1/customers 的任何方法請求
• DELETE /v1/customers/*：刪除任何客戶的請求

這增強了安全性：即使智能體對其“原因”進行虛假陳述，它也只能訪問策略允許的端點。策略執行發生在服務器端。

CLI參考

janee init                    # 使用示例配置設置~/.janee/目錄
janee add                     # 交互式添加服務
janee add stripe -u https://api.stripe.com -k sk_xxx  # 使用參數添加服務
janee remove <service>        # 刪除服務
janee remove <service> --yes  # 無需確認直接刪除服務
janee list                    # 列出已配置的服務
janee list --json             # 以JSON格式輸出（用於集成）
janee search [query]          # 搜索服務目錄
janee search stripe --json    # 以JSON格式輸出搜索結果
janee cap list                # 列出功能
janee cap list --json         # 以JSON格式列出功能
janee cap add <name> --service <service>  # 添加功能
janee cap edit <name>         # 編輯功能
janee cap remove <name>       # 刪除功能
janee serve                   # 啟動MCP服務器（標準輸入輸出，默認）
janee serve --transport http --port 9100  # 使用HTTP傳輸啟動（適用於容器）
janee serve --authority https://janee.example.com --runner-key $JANEE_RUNNER_KEY  # 運行器模式
janee authority --runner-key $JANEE_RUNNER_KEY  # 啟動授權API
janee logs                    # 查看審計日誌
janee logs -f                 # 即時查看審計日誌
janee logs --json             # 以JSON格式輸出審計日誌
janee sessions                # 列出活躍會話
janee sessions --json         # 以JSON格式輸出活躍會話
janee revoke <id>             # 終止會話

非交互式設置（適用於AI智能體）

AI智能體無法響應交互式提示。使用 --*-from-env 標誌從環境變量中讀取憑證，這樣可以避免將機密信息暴露給智能體的上下文窗口：

# Bearer認證（Stripe、OpenAI等）
janee add stripe -u https://api.stripe.com --auth-type bearer --key-from-env STRIPE_KEY

# HMAC認證（Bybit）
janee add bybit --auth-type hmac-bybit --key-from-env BYBIT_KEY --secret-from-env BYBIT_SECRET

# 帶有密碼短語的HMAC認證（OKX）
janee add okx --auth-type hmac-okx --key-from-env OKX_KEY --secret-from-env OKX_SECRET --passphrase-from-env OKX_PASS

# GitHub應用程序認證（短期令牌）
janee add github --auth-type github-app --app-id-from-env GH_APP_ID --pem-from-env GH_PEM --installation-id-from-env GH_INSTALL_ID

當所有必需的憑證都通過標誌提供時，Janee：

• 不會打開readline（不會在標準輸入上掛起）
• 會自動創建一個具有合理默認值的功能（1小時TTL，自動批准）

如果你願意，也可以直接編輯 ~/.janee/config.yaml 文件。

工作原理

┌─────────────┐      ┌──────────┐      ┌─────────┐
│  AI Agent   │─────▶│  Janee   │─────▶│  Stripe │
│             │ MCP  │   MCP    │ HTTP │   API   │
└─────────────┘      └──────────┘      └─────────┘
      │                   │
   No key           Injects key
                    + logs request

1. 智能體調用 execute MCP工具，提供功能、方法和路徑
2. Janee查找服務配置，解密真實密鑰
3. 使用密鑰向真實API發起HTTP請求
4. 記錄：時間戳、服務、方法、路徑、狀態
5. 將響應返回給智能體

智能體永遠不會接觸到真實密鑰。

📐 深入瞭解：請參閱架構與安全模型以獲取詳細的圖表、威脅模型以及與其他方案的比較。

安全特性

• 加密：密鑰使用AES-256-GCM算法進行存儲
• 智能體身份：從MCP初始化握手的 clientInfo.name 派生而來，無需自定義頭信息
• 智能體隔離：每個智能體都有自己的會話，具有隔離的身份（HTTP傳輸為每個會話創建一個服務器和傳輸層）
• 訪問控制：每個功能的 allowedAgents 白名單 + 服務器範圍的 defaultAccess 策略
• 憑證範圍：智能體創建的憑證默認具有 agent-only 訪問權限
• 審計日誌：每個請求都會記錄到 ~/.janee/logs/ 目錄下
• 會話管理：限時、可撤銷
• 緊急停止機制：使用 janee revoke 命令或刪除配置文件

Docker部署

可以將Janee作為容器運行，無需在本地安裝Node.js：

# 構建鏡像
docker build -t janee .

# 以HTTP模式運行
docker run -d -p 3000:3000 \
  -v ~/.janee:/root/.janee:ro \
  janee --transport http --port 3000 --host 0.0.0.0

或者使用Docker Compose：

mkdir -p config && cp ~/.janee/config.yaml config/
docker compose up -d

對於使用Docker的Claude Desktop，請參閱Docker文檔。

貢獻代碼

我們歡迎貢獻！在提交PR之前，請閱讀 CONTRIBUTING.md，其中包含所需的PR檢查列表（測試、變更日誌、版本號更新等）。

📄 許可證

本項目採用MIT許可證，由 True and Useful LLC 開發。

別再直接把密鑰交給AI智能體了，開始掌控訪問權限吧。 🔐