AI导哈

AI代理CLI工具

n8n-agent-cli是一个为零信任AI代理设计的命令行工具，通过webhook模式安全调用n8n的400+集成服务，提供API密钥隔离、执行审计和负载验证功能。

  • by bcharleson
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 bcharleson/n8n-agent-cli

使用说明

n8n代理客户端

用于n8n的AI代理CLI+MCP服务器——用于OpenClaw和AI代理的零信任webhook工具平台。

让您的人工智能代理拥有n8n的400+集成功能，而无需交给它API密钥。

npm install -g n8n-agent-cli

问题

当人工智能代理可以直接访问API时，会出现三个问题：

  1. 非确定性 -相同的指令在运行中产生不同的API调用。对于关键业务运营来说，这是一种责任。
  2. 过度特权访问 --原始Airtable键可以读取每个表，写入每个字段，删除每条记录。您的代理只需要一个表中的3个字段。
  3. 无审计追踪 --当出现问题时，LLM上下文窗口是您唯一的日志。这对企业来说还不够好。

解决方案：Webhook作为工具

构建一个锁定的n8n工作流。只给代理人一个 webhook URL.

Agent → POST { payload } → Webhook URL
                                │
                          n8n Workflow
                          (validation → CRM/API → format)
                          (credentials stored in n8n vault)
                                │
                          Respond to Webhook
                                │
Agent ← structured JSON result ←┘

代理发送作用域有效负载。n8n运行您设计的确切工作流——确定性、日志记录、凭证安全。代理获取数据。它从未接触过API键。

这是 零信任工具模式：webhook URL是一个代理。它代理的东西——Airtable、HubSpot、Salesforce、Stripe、你的数据库——对代理完全隐藏。

安装

# CLI
npm install -g n8n-agent-cli

# Or run directly
npx n8n-agent-cli --help

快速开始

1.连接到n8n实例

n8n-agent instance connect \
  --url https://YOUR-INSTANCE.app.n8n.cloud \
  --api-key YOUR_N8N_API_KEY

获取n8n中的API密钥： Settings → API → Create API key

2.验证连接

n8n-agent instance health

3.列出您的工作流程

n8n-agent workflows list
n8n-agent workflows list --active       # only active
n8n-agent workflows list --tags agent-tools  # filter by tag

4.触发webhook工具

n8n-agent webhooks trigger \
  --url https://YOUR-INSTANCE.app.n8n.cloud/webhook/query-leads \
  --payload '{ "status": "Open", "limit": 10 }'

5.启动MCP服务器（适用于OpenClaw/Claude Desktop）

n8n-agent mcp

MCP配置

添加到您的OpenClaw或Claude Desktop配置中：

{
  "mcpServers": {
    "n8n-agent": {
      "command": "n8n-agent",
      "args": ["mcp"],
      "env": {
        "N8N_URL": "https://YOUR-INSTANCE.app.n8n.cloud",
        "N8N_API_KEY": "YOUR_N8N_API_KEY"
      }
    }
  }
}

或者使用已保存的实例连接——MCP服务器读取 ~/.n8n-agent/config.json 自动。

CLI参考

实例管理

n8n-agent instance connect --url <url> --api-key <key> [--name <alias>]
n8n-agent instance health

工作流

n8n-agent workflows list [--active] [--tags <tag>] [--limit <n>]
n8n-agent workflows get --id <workflow-id>
n8n-agent workflows activate --id <workflow-id>
n8n-agent workflows deactivate --id <workflow-id>
n8n-agent workflows delete --id <workflow-id>

执行

n8n-agent executions list [--workflow-id <id>] [--status success|error|waiting] [--limit <n>]
n8n-agent executions get --id <execution-id>
n8n-agent executions delete --id <execution-id>

网络钩子

# Trigger a production webhook tool (the core zero-trust call)
n8n-agent webhooks trigger --url <webhook-url> --payload '<json>'

# Test a webhook while developing (workflow must be in "Listen for Test Event")
n8n-agent webhooks test --url <test-webhook-url> --payload '<json>'

凭证

# List what's in the vault (names/types only — never exposes values)
n8n-agent credentials list

n8n-agent credentials delete --id <credential-id>

环境变量

变量 描述
N8N_URL n8n实例URL（覆盖已保存的配置）
N8N_API_KEY n8n API密钥（覆盖已保存的配置）
N8N_AGENT_JSON 设置为 1 强制JSON输出（在管道中自动检测）

四种模式

模式1：零信任CRM查询

为每个CRM操作构建一个n8n工作流。工作流验证有效负载，使用存储的凭据查询CRM，并返回结构化JSON。代理没有CRM凭据，只有webhook URL。

n8n工作流结构：

Webhook Trigger → Code (validate) → Airtable/HubSpot/Salesforce → Respond to Webhook

关键Webhook触发器设置： Response Mode: "Using 'Respond to Webhook' Node"

代理工具定义（添加到SOUL.md）：

### query_leads — n8n Tool
URL: https://YOUR-INSTANCE/webhook/query-leads
Method: POST
Payload: { status: "Open"|"Qualified"|"Lost", limit: 1-100 }
Returns: { status, data: [], count }
Note: API key managed in n8n. Never access CRM directly.

→ 完整指南： 技能/n8n客户关系管理查询/SKILL.md → 模板： templates/zero-trust-crm-query.workflow.json

模式2：人在环（HITL）门

对于高风险操作——创建CRM记录、发送电子邮件、转移资金——插入Slack审批步骤。代理启动该操作。人类在执行之前会确认。

n8n工作流结构：

Webhook Trigger → Validate → Slack (approval request) → Wait → IF approved?
  YES → Execute action → Respond: { status: "completed" }
  NO  → Respond: { status: "rejected" }
  Timeout → Respond: { status: "timeout" }

代理优雅地处理每个响应。随着信任的建立，移除HITL门——执行历史就是你的证据。

→ 完整指南： 技能/n8n击球门/SKILL.md → 模板： 模板/hitl-gate.workflow.json

模式3：Cron自动化（n8n编排，代理原因）

对于定时自动化，不要要求代理管理cron。n8n的Cron触发器是编排器。OpenClaw是一个节点，通过HTTP请求调用，仅处理推理步骤（评分、分类、总结）。

每日潜在客户评分示例：

n8n Cron (9am) → Fetch new contacts → HTTP Request to OpenClaw → Score each lead
→ IF score > 70: Enroll in Instantly → IF score < 30: Mark Disqualified → Slack summary

Cron计时、API调用和路由： 确定性（n8n）. 领导评分判断： 龙虾.

→ 完整指南： 技能/n8n cron代理/SKILL.md

模式4:AI模型路由器

使用n8n的Switch节点根据任务类型将代理调用路由到不同的AI模型。OpenClaw调用一个webhook URL。n8n路由到Grok进行网络搜索，一个用于知识查找的RAG代理，一个图像视觉模型。代理不需要额外的API密钥。

Webhook: { task_type, query } → Switch →
  "web_search"     → Grok API
  "knowledge_base" → RAG Agent (Pinecone + Claude)
  "image_analysis" → Vision model
→ Respond: { status, result, model_used }

新模型？添加一个n8n节点。零OpenClaw重新配置。

→ 完整指南： 技能/n8-ai路由器/SKILL.md

在n8n中构建Webhook工具（一步一步）

  1. 新建工作流 → 命名它 [Tool] Your Tool Name → tag: agent-tools

  2. Webhook触发器节点：

    • HTTP方法： POST
    • 路径： your-tool-name （成为URL路径）
    • 响应模式： Using 'Respond to Webhook' Node ← 必需的

  3. 代码节点（验证）： 在接触任何API之前始终进行验证。

    const { status, limit } = $json.body;
if (!['Open', 'Qualified'].includes(status)) throw new Error(`Invalid status: ${status}`);
return { status, limit: Math.min(limit || 20, 100) };

  4. 您的逻辑节点： Airtable、HubSpot、HTTP请求等。--使用存储的凭据。

  5. 响应Webhook节点：

    { "status": "success", "data": [], "count": 0, "message": "..." }

  6. 测试： 点击 Listen for Test Event → run n8n-agent webhooks test --url <test-url> --payload '{}'

  7. 激活 → 将工作流切换为“活动”→ 生产URL是实时的。

  8. 添加到OpenClaw SOUL.md 包含生产URL、有效负载模式和使用说明。

调试执行

每次代理工具调用都会在n8n中创建一个日志执行。

# See recent executions
n8n-agent executions list --limit 20

# Find failures
n8n-agent executions list --status error

# Full trace for a specific run
n8n-agent executions get --id EXECUTION_ID

在n8n用户界面中： Executions → 单击任何执行→ 单击任何节点→ 查看确切的输入/输出。

可以在n8n UI中使用原始有效负载手动重试失败的执行，无需从代理重新触发。

工作流模板

预构建的n8n工作流已准备好导入：

模板 图案 描述
zero-trust-crm-query.workflow.json 模式1 Airtable查询——为任何CRM定制
hitl-gate.workflow.json 模式2 放宽任何操作的审批门槛

通过n8n UI导入： Workflows → Import from file

安全检查列表

在任何webhook工具投入生产之前：

  • []n8n凭据保管库中的API密钥（从不在工作流代码中）
  • []Webhook URL是HTTPS
  • []在任何API调用之前在代码节点中验证的有效负载
  • []操作参数使用枚举，而不是自由字符串
  • []添加HITL门用于创建/更新/删除操作
  • []Webhook URL未提交到任何公共存储库

为什么n8n代理cli与现有的n8n cli相比

现有 n8n-cli on npm是一个服务器端管理工具，它需要在本地安装n8n的内部包，并设计为运行 在n8n服务器上它不支持MCP，也没有AI代理模式的概念。

n8n-agent-cli 构建方式不同：

  • 纯HTTP -通过REST API与任何n8n实例（云或自托管）进行对话。没有本地n8n包。
  • 代理优先 --每个命令都是一个MCP工具。CLI和MCP服务器是相同的命令集。
  • 零信任模式 --围绕Webhook作为工具架构而设计，而不是服务器管理。
  • 最低存款 --Commander+Zod+MCP SDK。就这样

贡献

欢迎在 github/bcharleson/n8n-agent-cli.

许可证

麻省理工学院

相关 MCP