NeoCRM CLI 完全指南：用命令行驾驭 AI CRM 的无限可能

从安装到实战 —— 手把手教你用 Claude Code + neocrm CLI 生成企业级 CRM 洞察报告

标签: NeoCRM 销售易 CLI AI CRM XOQL Claude Code ECharts
更新日期: 2026-04-25

---

目录

• 一、NeoCRM CLI 是什么？为什么你需要它？
• 二、安装与环境配置
• 三、认证体系详解
• 四、完整命令参考手册
• 五、架构与安全设计
• 六、实战：用 Claude Code 生成 CRM 洞察报告
• 七、进阶技巧与最佳实践
• 八、总结与展望

---

一、NeoCRM CLI 是什么？为什么你需要它？

1.1 重新定义 CRM 操作方式

NeoCRM CLI（neocrm-cli-client）是销售易推出的命令行工具，让你在终端中直接与 NeoCRM 平台交互。当前版本 v0.6.0，基于成熟的 oclif 框架构建。

核心价值：

维度	GUI 操作	CLI 操作
交互方式	点击、表单	命令、脚本
批量操作	手动逐条	一行命令处理数百条
AI 集成	不支持	Claude Code / Hermes 直接调用
可编程性	无法自动化	CI/CD、定时任务、数据管道
数据查询	手动筛选	XOQL（类 SQL）精确查询

1.2 AI CRM 的关键桥梁

CLI 是 AI Agent 与 CRM 数据之间的关键纽带：

这意味着什么？ 你可以用自然语言告诉 Claude Code：“帮我分析本季度所有赢单商机的客户行业分布”，Claude Code 会自动编写 XOQL 查询、执行命令、分析数据、生成可视化报告。

1.3 五大核心能力

1. 数据查询（XOQL）：用类 SQL 语法查询 CRM 数据
2. CRUD 操作：创建、读取、更新、删除任意业务对象
3. 元数据发现：自动获取所有对象和字段定义
4. API 代理：直接调用底层 OpenAPI，突破 XOQL 限制
5. 数据锁定：支持并发安全的数据锁定机制

---

二、安装与环境配置

2.1 前置条件

要求	说明	验证命令
Node.js	>= 18.0.0	node -v
npm	随 Node.js 安装	npm -v
OAuth Client ID	从销售易管理后台获取	—

2.2 一键安装

# 全局安装
npm install -g neocrm-cli-client

# 验证安装
neocrm --version
# 输出: 0.6.0 darwin-arm64 node-v24.13.0

# 查看帮助
neocrm --help

安装成功后，neocrm 命令将注册到系统 PATH 中。

2.3 首次配置

CLI 的配置存储在 ~/.neocrm/config.json，支持以下配置项：

配置项	默认值	说明	取值范围
bffEndpoint	https://crmclaw.xiaoshouyi.com/	BFF 网关地址	合法 HTTPS URL
apiVersion	v58.0	API 版本号	字符串
requestTimeout	30	请求超时（秒）	5 - 300
maxRetries	3	最大重试次数	0 - 5
defaultOutputFormat	table	默认输出格式	table / json / csv
debug	false	调试模式	true / false

# 查看配置
neocrm config:get requestTimeout
# 输出: requestTimeout = 30

# 修改配置
neocrm config:set requestTimeout 60
neocrm config:set debug true

安全提示: 凭证文件 ~/.neocrm/credentials.json 使用 AES-256-GCM 算法加密，密钥通过 PBKDF2（100,000 次迭代，SHA-512）从主机名 + 用户名派生。即使文件被复制到其他机器也无法解密。

---

三、认证体系详解

3.1 OAuth 2.0 + clawId 轮询认证

NeoCRM CLI 采用独特的 clawId 轮询认证机制，兼顾安全性与用户体验：

认证流程详解：

1. CLI 生成随机 clawId（格式：neocrm-{8位hex}）
2. 构造 OAuth 2.0 授权 URL，自动打开浏览器
3. 用户在浏览器中完成登录和授权
4. 授权服务器将 Token 与 clawId 关联
5. CLI 每 2 秒 轮询 Token 状态（最长 5 分钟）
6. 获取 accessToken + refreshToken，加密存储到本地
7. 自动调用 getUserInfo() 获取用户详情
8. 更新凭证文件，显示登录成功信息

3.2 三大认证命令

neocrm auth:login — 登录

neocrm auth:login -c <your-client-id>

执行后会看到：

正在打开浏览器进行认证...
[INFO] clawId: neocrm-685dea8a

登录成功！
登录环境: https://scrm.xiaoshouyi.com/
用户名称: 测试-远甲
租户名称: 高科技行业售前Demo

neocrm auth:whoami — 查看当前用户

neocrm auth:whoami

返回完整用户信息：

{
  "id": 4252537841177438,
  "tenantId": 4018560293554834,
  "tenantName": "高科技行业售前Demo",
  "name": "测试-远甲",
  "phone": "13332401641",
  "phoneVerified": true,
  "status": 1,
  "timezone": "Asia/Shanghai",
  "languageCode": "zh",
  "local": "CN"
}

neocrm auth:logout — 登出

neocrm auth:logout
# 清除 ~/.neocrm/credentials.json

3.3 Token 自动刷新

当 accessToken 过期时（HTTP 401），BFFClient 会自动：

1. 调用 /neocrm/claw/refer/token/refresh 刷新 Token
2. 更新本地凭证文件
3. 用新 Token 重试原始请求

整个过程对用户完全透明。

---

四、完整命令参考手册

CLI 提供 5 大命令组，共 20 个命令：

neocrm
├── auth          # 认证管理 (3个命令)
│   ├── login     # 登录
│   ├── logout    # 登出
│   └── whoami    # 查看当前用户
├── config        # 配置管理 (2个命令)
│   ├── get       # 获取配置
│   └── set       # 设置配置
├── data          # 数据操作 (7个命令)
│   ├── query     # XOQL 查询
│   ├── get       # 获取单条记录
│   ├── create    # 创建记录
│   ├── update    # 更新记录
│   ├── delete    # 删除记录
│   ├── lock      # 锁定记录
│   └── unlock    # 解锁记录
├── metadata      # 元数据 (3个命令)
│   ├── objects   # 列出所有对象
│   ├── describe  # 对象字段描述
│   └── busitype  # 业务类型列表
└── api           # API代理 (5个命令)
    ├── get       # GET 请求
    ├── post      # POST 请求
    ├── patch     # PATCH 请求
    ├── put       # PUT 请求
    └── delete    # DELETE 请求

---

4.1 Auth 命令组 — 认证管理

命令	说明	必填参数
neocrm auth:login	OAuth 登录	-c, --client-id
neocrm auth:logout	登出并清除凭证	无
neocrm auth:whoami	查看当前用户信息	无

---

4.2 Config 命令组 — 配置管理

# 获取配置值
neocrm config:get <key>

# 设置配置值
neocrm config:set <key> <value>

示例：

neocrm config:get requestTimeout       # → requestTimeout = 30
neocrm config:set requestTimeout 60    # 设置超时为 60 秒
neocrm config:set maxRetries 5         # 设置最大重试 5 次
neocrm config:set debug true           # 开启调试模式

---

4.3 Data 命令组 — 数据操作

这是最核心的命令组，提供完整的 CRUD + 高级查询能力。

4.3.1 neocrm data:query — XOQL 查询（最常用）

neocrm data:query -q "SELECT fields FROM object [WHERE ...] [LIMIT N]"

XOQL 语法：

-- 基础查询
SELECT id, accountName, industryId FROM account LIMIT 10

-- 条件过滤
SELECT id, accountName FROM account WHERE industryId = '高科技'

-- 模糊搜索
SELECT id, accountName FROM account WHERE accountName LIKE '%科技%'

-- 多字段查询
SELECT id, opportunityName, money, status, winRate
FROM opportunity
LIMIT 200

限制： 查询语句最大 20,000 字符

返回结构：

{
  "code": "200",
  "msg": null,
  "data": {
    "totalSize": 200,
    "count": 200,
    "records": [
      { "id": "...", "accountName": "...", "industryId": ["高科技"] }
    ]
  }
}

提示: picklist 类型字段的值以数组形式返回，例如 "industryId": ["汽车电子"]，在使用时注意取第一个元素。

4.3.2 neocrm data:get — 获取单条记录

neocrm data:get -o account -i 4285853289190959

4.3.3 neocrm data:create — 创建记录

neocrm data:create \
  -o account \
  -n "新客户名称" \
  --dim-depart dept001 \
  --entity-type 1 \
  --user-id u001 \
  --object-id obj001 \
  -v '{"phone":"13800138000","industryId":"1"}'

参数	说明
-o, --object	对象 API Key（如 account, contact）
-n, --name	记录名称
--dim-depart	所属部门
--entity-type	实体类型
--user-id	用户 ID
--object-id	对象 ID
-v, --values	额外字段（JSON 格式）

4.3.4 neocrm data:update — 更新记录

neocrm data:update -o account -i 4285853289190959 -v '{"accountName":"新名称"}'

4.3.5 neocrm data:delete — 删除记录

neocrm data:delete -o account -i 4285853289190959

4.3.6 neocrm data:lock / data:unlock — 数据锁定

# 锁定记录（防止并发修改）
neocrm data:lock -o account -r 4285853289190959

# 解锁记录
neocrm data:unlock -o account -r 4285853289190959

使用场景: 当需要确保数据一致性时（如报价审批、合同签署），先锁定记录，操作完成后再解锁。

---

4.4 Metadata 命令组 — 元数据发现

这是数据探索的起点，帮助你了解系统中有哪些对象、每个对象有哪些字段。

4.4.1 neocrm metadata:objects — 发现所有业务对象

neocrm metadata:objects

返回租户下的全部业务对象。例如，在一个典型的 CRM 系统中，你可能会看到：

apiKey	label	说明
account	客户	核心业务对象
contact	联系人	客户下联系人
opportunity	销售机会	销售管道
lead	销售线索	潜在客户
product	产品	产品目录
...	…	通常有数百个对象

4.4.2 neocrm metadata:describe — 查看字段定义

neocrm metadata:describe -o account

返回完整的字段列表，包含字段名称、标签、类型、是否必填、选项值等信息：

{
  "apiKey": "account",
  "label": "客户",
  "fields": [
    {
      "apiKey": "accountName",
      "label": "客户名称",
      "type": "text",
      "required": true,
      "maxLength": 256
    },
    {
      "apiKey": "industryId",
      "label": "行业",
      "type": "picklist",
      "selectitem": [
        { "label": "汽车电子", "value": 1 },
        { "label": "消费电子", "value": 2 },
        { "label": "高科技", "value": 4 }
      ]
    }
  ]
}

4.4.3 neocrm metadata:busitype — 查看业务类型

neocrm metadata:busitype -o opportunity
# 返回商机对象的业务类型列表（如新客户机会、老客户机会）

---

4.5 API 命令组 — 万能代理

当你需要调用底层 OpenAPI 接口（超出 XOQL 能力范围）时，使用 API 代理命令：

# GET 请求
neocrm api:get /rest/data/v2.0/xobjects/account/12345

# 带查询参数
neocrm api:get /rest/data/v2.0/xobjects/account/description \
  -p '{"includeFields":"true"}'

# POST 请求
neocrm api:post /rest/data/v2.0/xobjects/account \
  -d '{"name":"新客户"}'

# PATCH 请求
neocrm api:patch /rest/data/v2.0/xobjects/account/12345 \
  -d '{"name":"更新名称"}'

# DELETE 请求
neocrm api:delete /rest/data/v2.0/xobjects/account/12345

# PUT 请求
neocrm api:put /rest/data/v2.0/xobjects/account/12345 \
  -d '{"name":"完整更新"}'

参数	说明
path	OpenAPI 路径（如 /rest/data/v2.0/...）
-d, --data	请求体（JSON 格式）
-p, --params	查询参数（JSON 格式）

注意: API 路径会通过 BFF 网关自动添加认证信息，无需手动传递 Token。

---

五、架构与安全设计

5.1 三层架构

BFF 网关自动注入的请求头：

Authorization: Bearer <accessToken>
X-OpenAPI-BaseUrl: <baseUrl>
X-Tenant-Id: <tenantId>
X-User-Id: <userId>

5.2 网络容错

机制	策略
连接错误重试	最多 maxRetries 次（默认 3 次）
退避策略	指数退避：1000ms × 2^attempt
401 自动刷新	检测到 401 立即刷新 Token 并重试
超时控制	可配置 requestTimeout（5-300 秒）

5.3 凭证安全

~/.neocrm/credentials.json
├── 加密算法: AES-256-GCM
├── 密钥派生: PBKDF2 (100,000 iterations, SHA-512)
├── 密钥来源: hostname + username (机器绑定)
└── 存储内容: accessToken, refreshToken, tenantId, expiresAt...

设计亮点: 密钥从机器标识派生，即使凭证文件被复制到其他机器也无法解密，实现天然的单机绑定。

---

六、实战：用 Claude Code 生成 CRM 洞察报告

这是本指南的核心部分 —— 我们将完整演示如何用 Claude Code + neocrm CLI，从零开始生成一份专业的 CRM 销售洞察报告。

6.1 实战目标

使用 Claude Code 编写 neocrm CLI 命令，探索系统数据，分析业务指标，最终生成一份包含 ECharts 可视化图表的 HTML 报告。

技术栈：

• 数据获取：neocrm CLI (XOQL)
• AI 分析：Claude Code
• 可视化：Apache ECharts 5.5
• 报告格式：HTML（自包含，可直接打开）

6.2 Step 1: 确认登录状态

$ neocrm auth:whoami

{
  "tenantName": "高科技行业售前Demo",
  "name": "测试-远甲",
  "phone": "13332401641",
  "timezone": "Asia/Shanghai"
}

6.3 Step 2: 发现业务对象

$ neocrm metadata:objects

系统返回了 518 个业务对象！其中核心对象包括：

对象	apiKey	核心用途
客户	account	客户信息管理
联系人	contact	客户联系人
销售机会	opportunity	销售管道
产品	product	产品目录
销售线索	lead	潜在客户

6.4 Step 3: 探索字段定义

$ neocrm metadata:describe -o account

通过字段定义，我们发现客户对象的关键字段：

accountName    → 客户名称 (text)
industryId     → 行业 (picklist: 汽车电子/消费电子/工业控制/5G通讯/高科技/制造业...)
customItem245__c → 客户级别 (picklist: L1/L2/L3/L4/L5)
customItem181__c → 合作状态 (picklist: 潜在/已合作)
fState         → 省份 (picklist)
annualRevenue  → 销售额 (currency)
totalWonOpportunityAmount → 结单商机总金额 (formula)

$ neocrm metadata:describe -o opportunity

商机对象的关键字段：

opportunityName  → 机会名称 (text)
money            → 预估总销售金额 (currency)
status           → 状态 (picklist: 进行中/赢单/输单)
winRate          → 赢率 (int: 0-100)
opportunityType  → 机会类型 (picklist: 新客户/老客户)
forecastCategory → 阶段分类 (picklist: 销售漏斗/最佳案例/客户承诺/结单)

6.5 Step 4: 数据采集

根据发现的字段，我们编写 XOQL 查询采集数据：

# 查询客户数据
$ neocrm data:query -q "SELECT id,accountName,industryId,customItem245__c,customItem181__c,fState,totalWonOpportunityAmount FROM account LIMIT 200"

# 查询销售机会
$ neocrm data:query -q "SELECT id,opportunityName,money,status,winRate,opportunityType,closeDate,createdAt FROM opportunity LIMIT 200"

# 查询产品
$ neocrm data:query -q "SELECT id,productName,customItem172__c,fscProductType FROM product LIMIT 200"

# 查询线索
$ neocrm data:query -q "SELECT id,status,createdAt FROM lead LIMIT 200"

6.6 Step 5: 数据分析

Claude Code 自动汇总所有查询结果，得出以下关键洞察：

客户分析

指标	数值
客户总数	200+
已合作客户	86 (43%)
潜在客户	62 (31%)

行业分布 Top 5：

行业	客户数	占比
高科技	46	23%
制造业	33	16.5%
消费电子	28	14%
汽车电子	17	8.5%
能源	10	5%

客户级别分布： L5(54) > L4(50) > L3(46) > L2(43) > L1(7)

销售机会分析

指标	数值
商机总数	200
商机总金额	¥20.94 亿
赢单金额	¥4.00 亿 (19.1%)
进行中金额	¥15.97 亿 (76.3%)
输单金额	¥0.97 亿 (4.6%)

商机状态分布：

进行中 ████████████████████████████████████████████████████████ 153 (76.5%)
赢单   ████████████ 38 (19.0%)
输单   ███ 9 (4.5%)

赢率分布：

赢率区间	商机数	解读
91-100%	38	即将赢单，重点跟进
61-90%	47	高概率，持续推动
31-60%	31	中等概率，需要策略
1-30%	74	早期阶段或风险较高
0%	10	需评估是否继续

产品线分布

产品线	产品数	占比
MCU PDT	48	24%
模拟信号链 PDT	24	12%
PC PDT	20	10%
AIoT PDT	16	8%
汽车电子 PDT	2	1%

线索转化

状态	数量	占比
未处理	35	85.4%
已转换	5	12.2%
已联系	1	2.4%

6.7 Step 6: 生成可视化报告

Claude Code 根据以上数据，自动生成了一份包含 9 个 ECharts 图表的专业 HTML 报告：

面板	图表类型	展示内容
KPI 概览	指标卡片	客户数、商机金额、赢单金额、线索数
客户行业分布	环形饼图	各行业客户占比
商机状态概览	双轴柱状图	商机数量 + 金额对比
销售漏斗	漏斗图	全部→进行中→高赢率→赢单
赢率分布	柱状图	各赢率区间的商机数量
产品线分布	玫瑰图	各产品线的产品数量
客户级别	横向柱状图	L1-L5 级别客户数
线索转化	漏斗图	全部→已联系→已转化
合作状态	饼图	已合作/潜在/未分类

报告配色方案：

主色: #1890FF (NeoCRM 蓝)    正向: #2FC25B (绿)
警告: #FACC14 (黄)           负向: #F04864 (红)
深色: #223273 (深蓝)         强调: #8543E0 (紫)

生成的报告效果：

完整报告文件：demo/crm-insight-report.html，可直接在浏览器中打开。

6.8 整个过程的 Claude Code 对话

以下是使用 Claude Code 完成上述全过程的实际对话流程：

👤 用户: 帮我分析 CRM 系统中的数据，生成一份专业的销售洞察报告

🤖 Claude Code:
1. 先确认登录状态...
   > neocrm auth:whoami  ✅ 已登录

2. 发现系统中有哪些业务对象...
   > neocrm metadata:objects  → 518个对象

3. 探索核心对象的字段定义...
   > neocrm metadata:describe -o account
   > neocrm metadata:describe -o opportunity
   > neocrm metadata:describe -o product

4. 编写 XOQL 查询采集数据...
   > neocrm data:query -q "SELECT ... FROM account LIMIT 200"   → 200条
   > neocrm data:query -q "SELECT ... FROM opportunity LIMIT 200" → 200条
   > neocrm data:query -q "SELECT ... FROM product LIMIT 200"    → 200条
   > neocrm data:query -q "SELECT ... FROM lead LIMIT 200"       → 41条

5. 分析数据，生成报告...
   ✅ 已生成 demo/crm-insight-report.html

整个分析过程从数据探索到报告生成，仅用了几分钟。

---

七、进阶技巧与最佳实践

7.1 XOQL 查询优化

# 只查询需要的字段，减少数据传输
✅ neocrm data:query -q "SELECT id,accountName,industryId FROM account LIMIT 50"
❌ neocrm data:query -q "SELECT * FROM account LIMIT 50"

# 利用 WHERE 条件精确筛选
neocrm data:query -q "SELECT id,accountName FROM account WHERE customItem181__c = '已合作' LIMIT 100"

# 多条件组合
neocrm data:query -q "SELECT id,opportunityName,money FROM opportunity WHERE status = '赢单' AND money > 1000000 LIMIT 50"

7.2 配合 jq 做数据管道

# 提取所有客户名称
neocrm data:query -q "SELECT accountName FROM account LIMIT 200" | jq '.data.records[].accountName'

# 统计各行业客户数量
neocrm data:query -q "SELECT industryId FROM account LIMIT 200" | \
  jq '[.data.records[].industryId[0]] | group_by(.) | map({name: .[0], count: length}) | sort_by(-.count)'

# 提取赢单商机总金额
neocrm data:query -q "SELECT money,status FROM opportunity LIMIT 200" | \
  jq '[.data.records[] | select(.status[0]=="赢单") | .money | tonumber] | add'

7.3 API 代理突破 XOQL 限制

当 XOQL 无法满足需求时，用 api:* 命令直接调用底层接口：

# 获取完整的对象描述（含字段详情）
neocrm api:get /rest/data/v2.0/xobjects/account/description -p '{"includeFields":"true"}'

# 获取用户详细信息
neocrm api:get /rest/auc/v2.0/userInfo

# 通过 OpenAPI 查询（绕过 XOQL 限制）
neocrm api:post /rest/data/v2.0/query/xoql -d '{"xoql":"SELECT id FROM account"}'

7.4 CI/CD 集成模式

#!/bin/bash
# daily-crm-report.sh — 每日 CRM 数据报告

# 确保已登录
neocrm auth:whoami > /dev/null 2>&1 || exit 1

# 导出当日新增客户
TODAY=$(date +%Y-%m-%d)
neocrm data:query -q "SELECT id,accountName,industryId FROM account WHERE createdAt > '${TODAY}'" > "daily_report_${TODAY}.json"

# 统计商机状态
neocrm data:query -q "SELECT id,status,money FROM opportunity LIMIT 500" | \
  jq '[.data.records[] | {status: .status[0], money: (.money|tonumber)}] | group_by(.status) | map({status: .[0].status, total: (map(.money) | add)})' \
  >> "daily_report_${TODAY}.json"

echo "Report generated: daily_report_${TODAY}.json"

7.5 数据锁定保障数据安全

# 在批量更新前锁定记录
neocrm data:lock -o account -r 4285853289190959

# 执行更新
neocrm data:update -o account -i 4285853289190959 -v '{"annualRevenue":"5000000"}'

# 完成后解锁
neocrm data:unlock -o account -r 4285853289190959

---

八、总结与展望

8.1 NeoCRM CLI 核心要点

维度	总结
安装	npm install -g neocrm-cli-client，需要 Node.js >= 18
认证	OAuth 2.0 + clawId 轮询，AES-256-GCM 加密存储
命令	5 大组 20 个命令，覆盖认证、配置、数据、元数据、API 代理
查询	XOQL（类 SQL），最大 20,000 字符
安全	PBKDF2 密钥派生，机器绑定，自动 Token 刷新
架构	CLI → BFF Gateway → NeoCRM API 三层架构

8.2 AI + CLI 的新范式

NeoCRM CLI 的发布，标志着 CRM 从 GUI-only 时代迈向 AI Agent 可操作 时代。通过 CLI：

• Claude Code 可以直接读取和分析 CRM 数据
• Cursor / Copilot 可以在你的 IDE 中操作 CRM
• 自动化脚本 可以定时执行数据同步和报告生成
• CI/CD 流水线 可以集成 CRM 数据校验

这不是一个简单的命令行工具，而是 AI CRM 生态的基础设施。

8.3 快速上手

# 1. 安装
npm install -g neocrm-cli-client

# 2. 登录
neocrm auth:login -c <your-client-id>

# 3. 探索
neocrm metadata:objects

# 4. 查询
neocrm data:query -q "SELECT id,name FROM account LIMIT 10"

# 5. 在 Claude Code 中使用
# 直接告诉 Claude Code: "帮我分析 CRM 数据"

---

关于作者: 本文基于 NeoCRM CLI v0.6.0 文档分析及真实 CRM 数据实测撰写，是全网首份 NeoCRM CLI 详细使用指南。交流相关问题：linfeng@xsycrm.com.cn

参考资源:

• 安装包: npmjs.com/package/neocrm-cli-client
• 图表引擎: Apache ECharts
• CLI 框架: oclif.io