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智能体了，开始掌控访问权限吧。 🔐