n8n代理客户端
用于n8n的AI代理CLI+MCP服务器——用于OpenClaw和AI代理的零信任webhook工具平台。
让您的人工智能代理拥有n8n的400+集成功能，而无需交给它API密钥。
npm install -g n8n-agent-cli______________________________________________________________________
问题
当人工智能代理可以直接访问API时，会出现三个问题：
- 非确定性 -相同的指令在运行中产生不同的API调用。对于关键业务运营来说，这是一种责任。
- 过度特权访问 --原始Airtable键可以读取每个表，写入每个字段，删除每条记录。您的代理只需要一个表中的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 health3.列出您的工作流程
n8n-agent workflows list
n8n-agent workflows list --active # only active
n8n-agent workflows list --tags agent-tools # filter by tag4.触发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 --api-key [--name ]
n8n-agent instance health工作流
n8n-agent workflows list [--active] [--tags ] [--limit ]
n8n-agent workflows get --id
n8n-agent workflows activate --id
n8n-agent workflows deactivate --id
n8n-agent workflows delete --id 执行
n8n-agent executions list [--workflow-id ] [--status success|error|waiting] [--limit ]
n8n-agent executions get --id
n8n-agent executions delete --id 网络钩子
# Trigger a production webhook tool (the core zero-trust call)
n8n-agent webhooks trigger --url --payload ''
# Test a webhook while developing (workflow must be in "Listen for Test Event")
n8n-agent webhooks test --url --payload ''凭证
# List what's in the vault (names/types only — never exposes values)
n8n-agent credentials list
n8n-agent credentials delete --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 --payload '{}'`
1. **激活** → 将工作流切换为“活动”→ 生产URL是实时的。
1. **添加到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](templates/zero-trust-crm-query.workflow.json) |模式1| Airtable查询——为任何CRM定制|
| [hitl-gate.workflow.json](templates/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`](https://www.npmjs.com/package/n8n-cli) on npm是一个服务器端管理工具，它需要在本地安装n8n的内部包，并设计为运行 *在n8n服务器上*它不支持MCP，也没有AI代理模式的概念。
`n8n-agent-cli` 构建方式不同：
- **纯HTTP** -通过REST API与任何n8n实例（云或自托管）进行对话。没有本地n8n包。
- **代理优先** --每个命令都是一个MCP工具。CLI和MCP服务器是相同的命令集。
- **零信任模式** --围绕Webhook作为工具架构而设计，而不是服务器管理。
- **最低存款** --Commander+Zod+MCP SDK。就这样
______________________________________________________________________
## 贡献
欢迎在 .
## 许可证
麻省理工学院