通过 @aliyun-es/eke 插件将 Codex、OpenClaw、Hermes、Claude Code 等 Agent 接入企业上下文引擎,使 Agent 检索工作空间下的知识库、智能记忆与技能,并获得带引用的上下文。-检索分析服务 Elasticsearch版(ES)-阿里云帮助中心

前提条件

已在阿里云 Elasticsearch 引擎增强版实例上初始化企业上下文引擎，并创建工作空间与成员，获取成员的接入参数（endpoint、workspace、user_id、api_key）。详情请参见使用企业上下文引擎。
运行目标 Agent 的环境已安装 Node.js 22 及以上版本，且 npm、npx 可用。
目标 Agent 已正确安装并能正常启动。

接入参数

企业上下文引擎控制台的 接入 Agent 面板会根据所选成员自动生成安装命令并填充参数。手动执行安装时，参数说明如下。

必填参数

参数	取值
`--endpoint`	企业上下文引擎数据访问服务的基础地址，例如 `https://<服务域名>`。不是 ES 地址或管控 API 地址，也不附加 `/v1/...` 等路径。
`--workspace`	已开通的工作空间名称，不是工作空间 ID。
`--user_id`	代表当前业务用户的稳定 ID（成员 ID）。不要用 Agent 名称代替，也不要每次安装随机生成。
`--api_key`	成员的 API Key（`OS-` 开头）。不是 ES 密码、阿里云 AK/SK 或 npm Token。

同一业务用户跨 Agent 共享智能记忆时，使用相同的 --endpoint、--workspace 和 --user_id；不同用户不要共用同一个 --user_id。--user_id 与 --kb 不作为授权凭证，使用前需确认 API Key 具有对应的服务访问权限。

常用可选参数

参数	默认	说明
`--kb <知识库名称>`	不指定默认知识库	可重复指定，例如 `--kb "product_docs" --kb "team_handbook"`。仅作为默认查询指引，不是权限白名单。
`--auto-capture`	自动采集开启	显式开启智能记忆自动采集，通常无需填写。
`--no-auto-capture`	—	关闭智能记忆自动采集。与 `--auto-capture` 互斥。
`--auto-skill`	关闭	开启自动技能提取，仅 OpenClaw 支持，会上传相关新对话。
`--replace-memory-provider`	不替换	允许替换 Hermes 已有的 Memory Provider，仅在确认替换时使用。

智能记忆自动采集默认开启：插件生效后，会将新的用户与助手对话文本发送到所配置的企业上下文引擎服务，不补传历史会话，也不自动对正文做敏感信息脱敏。如需关闭，使用 --no-auto-capture。该安装配置面向单个业务用户，不能用一个固定 --user_id 代表多用户应用中的所有人。

环境与排障参数

常规安装无需填写以下参数。

参数	适用命令	说明
`--config-dir <目录>`	`install`、`status`、`uninstall`	指定 Agent 配置根目录（不是 `.eke` 子目录）。默认按宿主环境变量或默认位置定位；后续操作使用同一目录。
`--agent-bin <程序路径>`	`install`、`uninstall`	指定宿主程序路径。默认自动查找；仅在自定义位置或程序路径变化时指定，Hermes 不需要。
`--skip-check`	`install`	跳过安装前的 MCP 连接与工具列表检查。跳过不代表服务可用。
`--prepare`	`install`	只生成本地文件，不注册或启用插件。仍会检查服务连接，除非同时传入 `--skip-check`。

状态与输出参数

参数	适用命令	说明
`--check`	`status`	额外检查 MCP 连接与工具列表，不执行业务调用。
`--json`	`install`、`status`、`uninstall`	输出 JSON 结果（不含 API Key）。警告与错误仍可能写入 stderr，须同时检查退出码。
`--help`	独立使用	显示命令帮助后退出。
`--version`	独立使用	显示 EKE 插件版本后退出。

接入步骤

步骤一：确认目标 Agent 与接入参数

选择一个目标 Agent，命令中的 <agent> 取值如下。当前支持 Codex、OpenClaw、Hermes、Claude Code。

目标 Agent	`<agent>` 取值	必须具备的能力
OpenClaw	`openclaw`	本地插件安装与 `mcp.servers` 配置
Hermes	`hermes`	支持 `MemoryProvider` 与 `spawn_context_thread` 的 Python 环境
Codex	`codex`	`codex plugin add` 命令，且允许插件 hooks
Claude Code	`claude-code`	`claude plugin` 命令，且允许插件 hooks

准备好前述必填接入参数。缺少接入信息时，向企业上下文引擎负责人确认后再安装。

步骤二：检查并准备运行环境

在运行目标 Agent 的同一台机器、同一个操作系统账号、同一个环境中执行。远程 Agent 在服务器中安装，容器内的 Agent 在容器中安装，WSL 中的 Agent 在 WSL 中安装。不要通过切换 root 或管理员账号绕过安装问题，否则可能安装到错误的用户目录。

先检查运行环境：

node --version
npm --version

要求 Node.js 22 及以上，且 npm、npx 可用。已有符合要求的环境可直接复用；需要新装时，建议使用 nvm 在当前用户下安装，避免覆盖系统 Node.js，且不同时安装多套 Node.js。安装 Node.js 或修改 shell 配置属于环境变更，应遵守当前环境的授权要求。

插件会记录安装时使用的 Node.js 可执行文件路径。不要使用会被清理的临时 Node.js；后续更换或删除该 Node.js 时，需要重新安装 EKE。

步骤三：执行安装

将 <agent> 替换为步骤一中的取值，将其余占位符替换为真实接入信息，执行安装命令：

npx --yes @aliyun-es/eke@latest install <agent> \
  --endpoint "<服务地址>" \
  --workspace "<工作空间名称>" \
  --user_id "<业务用户ID>" \
  --api_key "<API Key>" \
  --json

无需全局安装 npm 包。--yes 仅跳过 npx 下载包的确认，不跳过 Agent 的信任与工具授权。可按需在命令末尾追加可选参数，例如追加 --kb "product_docs" --kb "team_handbook" 指定默认知识库，或追加 --no-auto-capture 关闭智能记忆自动采集。

安装器会先连接服务并检查 MCP 工具列表，再注册插件、保存配置，此过程不调用业务工具、不写入测试数据。退出码为 0 且结果为 CONFIGURED 才表示配置完成，不能仅根据退出码判定后续验证通过。

步骤四：加载插件并验证

根据目标 Agent 的提示，信任 EKE 插件、启用 hooks、批准工具访问。
重新加载插件或重启 Agent（Hermes 需要重启）。不要强制结束正在执行的任务。
使用相同的 Agent 名称与配置目录检查连接：
```
npx --yes @aliyun-es/eke@latest status <agent> --check --json
```
结果需同时满足 status 为 CONFIGURED、drift 为空、connection.connected 为 true 且 connection.missingTools 为空。hostExecution: NOT_VERIFIED 表示尚未验证 Agent 实际执行工具，不是连接错误。
在新会话中执行一次有权限的实际查询进行验证，例如：
```
请使用企业上下文引擎，从知识库 <知识库名称> 中查找 <一个非敏感问题> 的相关内容，并给出来源。
```
没有知识库时，可执行一次当前用户的智能记忆或技能查询。确认实际调用了 EKE 工具即可，数据为空不等于安装失败。

配置、连接与实际工具调用均通过后，即完成接入。

步骤五：调整配置、更新与卸载

调整配置或更新插件：重新执行步骤三的完整安装命令，无需先卸载。@latest install 会将新版本文件安装到 Agent；仅下载 npm 包不会更新已安装插件。
重新安装会替换整套接入配置：--kb 需传完整列表，不传则清空默认列表；需要保留的 --no-auto-capture、--auto-skill 也必须再次携带。修改后重新加载并验证。
卸载：
```
npx --yes @aliyun-es/eke@latest uninstall <agent> --json
```
返回 UNINSTALLED 后重新加载或重启 Agent。卸载只移除本地 EKE 配置与文件，不删除服务端的智能记忆、知识库或技能。

常见问题

安装或下载失败

现象	处理
PowerShell 提示禁止运行 `npm.ps1` 或 `npx.ps1`	将命令中的 `npm`/`npx` 换成 `npm.cmd`/`npx.cmd`，其他参数不变，不关闭执行策略。
包找不到、E404	检查 `npm config get registry` 与 `npm config get @aliyun-es:registry`，确认包名、版本与访问限制。允许公共 npm 时，可在包名前加 `--registry=https://registry.npmjs.org --@aliyun-es:registry=https://registry.npmjs.org` 重试。
缓存报 EACCES/EPERM	在包名前加独立缓存目录重试，例如 `--cache "$HOME/.cache/eke-npm"`；不使用 `sudo npm`。
网络超时、代理或证书错误	复用企业批准的 `HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY`；企业 CA 使用 `NODE_EXTRA_CA_CERTS` 指向获批的 PEM 文件，不关闭证书验证。代理与 CA 配置也须进入实际 Agent 的启动环境。

服务连接失败

现象	处理
endpoint 格式错误	从接入信息重新取基础地址，去掉 API 路径、查询参数与片段；不要用 ES 地址或浏览器控制台地址。
DNS 错误、连接超时	在实际运行 Agent 的环境执行 `curl -I --connect-timeout 10 "<服务基础地址>"` 诊断 DNS/TCP/TLS。私网域名需在可达网络中使用。
`401`、`403` 或 `CredentialsNotFound`	核对 API Key 所属服务、启用状态及资源权限；换用正确的 Key 后重新安装，不把 ES 密码或阿里云 AK/SK 填入 `--api_key`。
`MCP is missing required tools`	记录缺失的工具名与服务地址，联系企业上下文引擎负责人确认服务版本与接入地址。
Hermes 提示已有 Memory Provider	确认后在原命令追加 `--replace-memory-provider`，否则保留原配置并停止。

状态检查异常

状态	处理
`NOT_INSTALLED`	核对当前 Agent、账号与配置目录；环境正确时重新执行安装。
`PREPARED`	尚未注册插件，重新执行正常安装命令，不加 `--prepare`。
`FAILED` / `CONFIGURATION_CHANGED`	根据错误或 `drift` 定位文件及配置项；保留用户改动，解决冲突后重新安装，不清空整个配置目录。
配置与连接正常，但没有工具	完成宿主授权、重新加载并开启新会话；继续查看宿主的 EKE 加载错误，不重复安装到其他目录。

API Key 保存在 Agent 配置目录下的 .eke/connection.json 及所需 MCP 配置中，OpenClaw、Hermes 的安装记录也可能含凭证。请保护配置目录及其备份，勿共享给其他用户。