用一个 Zaru 端点连接你的工具、配置文件和批准

其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南

声明:Zaru 由 100monkeys AI, Inc. 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体根据 Zaru 文档(2026 年 10 月 29 日阅读:Connect Zaru to Any MCP Client, MCP Tools, Profiles, API Keys, The Vault, Calendar, Refusals and Errors)起草,并经公司审阅;这个简体中文版是英文原版指南的译文。下面的每条命令、每个请求头和每条消息都抄自这些页面,引用保留英文原文,译文附在旁边。它们没有说明某件事如何运作的地方,我们直接说明,而不去描述它。

你的邮箱、日历、一个 GitHub token 和一个 Carbon Forge token 都可以放在 Zaru 里,而 Claude Code 通过一个地址就能触及它们全部。token 留在 Zaru 里,配置文件决定一个密钥可以碰其中哪些,而会发送或修改东西的调用会在 Zaru Web 里等你答复。本指南从 zaru init 一直走到第一个被挂起的调用。

第 1 步:连接你的工具要用的服务

点击 Get Zaru free(免费使用 Zaru)注册;只需要名字和邮箱。在 Vault 的 Connections 页面,可以连接 Google 邮箱、Google Calendar、通过 IMAP 和 SMTP 的邮箱,或通过 CalDAV 的日历。GitHub token 或 Carbon Forge MCP token 用 New Credential 保存。关于这个值,文档说得很清楚:"No agent, operator, API key or other person is given the value."(任何智能体、运营者、API 密钥或其他人都拿不到这个值。)

第 2 步:建立一个配置文件

在你说明一个密钥可以触及什么之前,它什么都触及不到。API Keys 页面在列表上方写着:"A key reaches only the connections in the profile you choose for it; with no profile it reaches none."(密钥只能触及你为它选择的配置文件中的连接;没有配置文件,就一个也触及不到。)用编辑器应当拥有的连接和工具建立一个配置文件;让每次 Zaru 运行只用到它需要的连接一步步讲解这个表单。

第 3 步:创建 API 密钥并选择它的配置文件

打开 Settings → API Keys,点击 New API Key,命名,选一个权限范围预设,选择密钥的配置文件(默认是 None),选择有效期,然后点击 Create。"The key value is shown once."(密钥的值只显示一次。)

第 4 步:把端点添加到 Claude Code

每个客户端都连接同一个地址 https://mcp.myzaru.com/mcp/v1,通过 StreamableHTTP,把密钥作为 Bearer token。对于 Claude Code,文档给出:

claude mcp add zaru \
  --transport http \
  https://mcp.myzaru.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_API_KEY"

同一页面还给出了 Claude Desktop、Cursor、Windsurf、VS Code(GitHub Copilot)和 Gemini CLI 的设置,以及任何支持 StreamableHTTP 的客户端的设置。

第 5 步:输入 zaru init

在会话中对助手说:

zaru init

它会调用 zaru.init 工具并采用 Zaru 的角色。zaru init agentic 会以指定的模式开始。这是 MCP 服务器的一个工具;Zaru CLI 指南中命令行程序的 zaru init 与它无关,也不会连接 Zaru Web。

第 6 步:如有需要,为每个连接选择配置文件

密钥的配置文件适用于每个请求。客户端也可以改为发送 x-zaru-contexts 请求头,其中只含保留键 @profile:

x-zaru-contexts: {"@profile":"0000daeb-ae45-4d06-9712-9d498a653b24"}

这个 id 是文档中的示例。使用密钥时,请求中的 @profile 会在该请求中取代密钥自己的配置文件,提供的工具也随之变成该配置文件的工具。任何其他形式都会得到 400。

Connect Zaru to Any MCP Client 页面说明了请求头放在哪里:"Every client above sends one header, Authorization, from its configuration. The same place takes a second header, x-zaru-contexts, which chooses for every request of that connection which of your connections its tools use."(上面的每个客户端都会从其配置中发送一个请求头 Authorization。同一个位置可以再放第二个请求头 x-zaru-contexts,它为该连接的每个请求选择工具使用你的哪些连接。)在 Claude Code 中,再加一个 --header:

claude mcp add zaru \
  --transport http \
  https://mcp.myzaru.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header 'x-zaru-contexts: {"@profile":"<profile id>"}'

用 JSON 配置的客户端(Claude Desktop、Windsurf、VS Code)把它作为 headers 下的第二项。"The profile's id is the last part of the address of its page in Zaru Web, ask.myzaru.com/vault/profiles/<profile id>."(配置文件的 id 是它在 Zaru Web 中页面地址的最后一部分。)文档留下了一个问题:"Whether a given client sends a header it was configured with on every request is the client's behaviour, not documented here."(某个客户端是否在每个请求中都发送配置好的请求头,属于客户端的行为,文档中没有说明。)

第 7 步:发起一次使用连接的调用

客户端会看到配置文件中各连接类别的工具:邮箱对应邮件工具,日历对应日历工具,GitHub 或 Carbon Forge 对应远程服务器的工具。没有指明邮箱或账号的邮件或日历调用,会使用唯一的那个,否则使用最新的那个,并在答复的 mailbox_name 或 account_name 中写明。关于日历工具,文档说:"Your Google token or your password never reaches an agent or the model."(你的 Google token 或密码永远不会到达智能体或模型。)

MCP Tools 页面列出了它们:"The remote servers a person can connect today are GitHub and Carbon Forge (formerly Nuclear Notes)."(如今可以连接的远程服务器是 GitHub 和 Carbon Forge(原名 Nuclear Notes)。)自定义 SEAL 网关:即将推出。

第 8 步:读懂一次拒绝

当 AEGIS by 100monkeys.ai(测试版)拒绝一次调用时,客户端会收到一个普通的工具结果,带有 isError: true,其中包含 error.code、error.message 和一个 request_id。有两种拒绝与触及范围有关:

CREDENTIAL_BINDING_REQUIRED,在任何东西运行之前出现。对于没有配置文件的密钥:"This key reaches none of your connections. Choose a profile for it on the API keys page in Zaru Web, or name one in the request."(这个密钥触及不到你的任何连接。请在 Zaru Web 的 API 密钥页面为它选择一个配置文件,或在请求中指明一个。)对于你从未连接过的类别,答复会指向 Connections 页面。
TOOL_NOT_IN_PROFILE:"This tool is not in the profile chosen for this conversation."(这个工具不在为本次对话选择的配置文件中。)

每种拒绝都带有 error.needs,写明类别和能解决问题的 Zaru Web 页面。对于一次运行,Zaru Web 的卡片会显示 "This run has no profile that names your <family>."(这次运行没有列出你的 <family> 的配置文件。)并附 Open Profiles。策略拒绝是确定性的,所以请修改调用,而不是重复它。

第 9 步:在 Zaru Web 中答复被挂起的调用

"Every tool that asks for approval waits at the person's approval gate, as a call from the chat does."(每个需要批准的工具都会在这个人的批准关口等待,就像来自聊天的调用一样。)调用会返回 {"status": "approval_pending", "approval_id", "summary", "message"},其中的消息是 "This waits for your answer in Zaru Web, under Approvals."(这在 Zaru Web 的 Approvals 下等待你的答复。)在 Approvals 页面答复它;aegis.approval.status 可以从客户端读取你的答复。

MCP Tools 页面列出了 myzaru.com 上默认会等待的调用。工具目录标记了 mail.send, mail.reply, mail.forward, mail.delete, mail.archive,以及四个日历写操作 calendar.create, calendar.update, calendar.delete, calendar.respond。部署配置标记了四个 GitHub 写操作 github.merge_pull_request, github.push_files, github.create_or_update_file, github.delete_file,以及 aegis.git.push 和 aegis.system.info。"No Carbon Forge tool waits: neither the catalogue nor the configuration marks one, so a Carbon Forge call the key's profile admits runs at once."(没有 Carbon Forge 工具会等待:目录和配置都没有标记任何一个,所以密钥的配置文件允许的 Carbon Forge 调用会立即运行。)配置文件表单会给每个会等待的工具标上 "Needs your approval"(需要你的批准)。一个长期有效的 "Always allow"(始终允许)选择会不经询问就答复它的调用,所以等待是默认行为,而不是承诺。