进阶 macro.com 2026-11-21 11:03:52 · 13 阅读

第1章 自带 Agent 连接指南

选择你的 agent Agent 连接方式 Cursor:使用你的 Cursor API key 连接 Cursor Cloud。 Claude:用 MacroD 运行 Claude Code,或在 Claude 对话中添加 Macro MCP。 ChatGPT:在 ChatGPT 中把 Macro MCP 添加为自定义应用。 Hermes:用 MacroD 运行 Hermes,或注册为一个拥有独立 Macro 账户和 SDK token 的 agent。

正在使用 MacroD?从 Desktop setup 或 Server setup 开始。

在 Macro 桌面应用上 MacroD 随桌面应用提供。先在这台电脑上安装并登录你的 agent。

打开 Settings → Machines,找到 This computer。 点击 Set up,然后确认 Macro 发现的 agent。可以用 Options 选择其他 agent 或工作区文件夹。 在 Macro 中 @mention 这个新 agent。它运行期间请保持应用打开。

连接你的机器 以下步骤适用于服务器,或没有安装 Macro 桌面应用的电脑。需要 macOS、Linux 或 Windows,以及一个已安装并登录的 agent。MacroD 能检测到 Claude Code、Codex、OpenCode、OpenClaw 和 Hermes。对于其他 Agent Client Protocol (ACP) agent,请选择 Custom command。

安装 MacroD。在下面选择你的操作系统,或从 Macro releases 下载对应系统的压缩包。 在 macOS 或 Linux 上安装:curl -fsSL https://raw.githubusercontent.com/macro-inc/macro/main/crates/coding_agent_worker/install/install.sh | sh 安装后请打开一个新终端。安装器会把 ~/.local/bin 加入你的 PATH。如果想保留 shell 启动文件的原始内容,可使用 --no-modify-path 或设置 MACROD_NO_MODIFY_PATH=1。 在 Windows 上安装:irm https://raw.githubusercontent.com/macro-inc/macro/main/crates/coding_agent_worker/install/install.ps1 | iex 安装器会把 %LOCALAPPDATA%\Programs\macrod 加入你的用户 PATH。安装后请打开一个新的 PowerShell 窗口。

启动 MacroD 并选择 agent。在终端运行 macrod。在 Quickstart 中选择你的 agent,设置它的 Workspace folder,然后点击 Create and pair。 在 macOS 和 Linux 上,你可以在 Herdr 内启动 macrod,Quickstart 还会提供 herdr 中的 Claude Code 和 herdr 中的 Codex 选项。这样每个会话都在 agent 自己的终端界面中运行,位于一个可以打开并输入的 Herdr 标签页里。

在 Macro 中批准配对。打开终端里显示的配对链接,或前往 Settings → Machines → New machine。输入设备码并点击 Look up。确认电脑及其权限信息后,点击 Approve。

使用专用的工作区文件夹。在启用权限绕过之前请先了解相关共享机制。使用 agent 时请保持 MacroD 运行、电脑不休眠。MacroD 主动向 Macro 发起连接,因此无需打开任何入站端口。

在云服务器上运行 agent 如果你希望在笔记本电脑关机时 agent 仍持续运行,可以在云服务器上运行 MacroD。通过 SSH 连接到服务器,安装并登录你的 agent,然后按「连接你的机器」操作。在自己的浏览器中打开配对链接即可,服务器不需要浏览器。 MacroD 主动连接 Macro,因此服务器不需要公网地址、开放端口、反向代理或隧道。断开连接后,请让 macrod 继续运行,例如放在 tmux 或 Herdr 中。

创建使用你这台机器的 agent 对于从终端配对的机器,打开 Settings → Agents → Add agent。给 agent 起一个名字和 @tag。在 Where it runs 中选择 On your machine,然后在 Machine 中选中那台机器。选择 Private(仅自己可见)或 Team(团队共享),保存后 @mention 这个 agent 即可。

更多 MacroD 帮助 观看配置流程演示 配对细节与 agent 前提条件 如果你回到终端概览页,按 p 打开配对,按 c 复制设备码。截图中的设备码仅为示例,请使用 MacroD 终端中显示的设备码。 MacroD 的配置和凭据保存在 ~/.macrod/macrod.toml(Windows 上为 %USERPROFILE%\.macrod\macrod.toml)。请妥善保管该文件,不要泄露,也不要提交到版本控制。 Claude Code 和 Codex 使用 ACP 适配器。它们的预设要求 agent 命令和 npm 与 macrod 处于同一个 shell 中。MacroD 会在你首次选择该 agent 时自动安装适配器。在 Windows 上,Claude Code 可通过其原生安装器或 npm install -g @anthropic-ai/claude-code 安装。

在同一台电脑上运行多台机器 每台机器都有自己的配置。第一台使用 ~/.macrod/macrod.toml。其他每台机器请指定一个 profile 名称: macrod --profile work 每个 profile 的配置保存在 ~/.macrod/profiles/work.toml,并配对为一台以「电脑名 + profile」命名的新机器,例如 my-laptop · work。可以在 Settings → Machines 中重命名。要重新连接,再次运行 macrod --profile work。 如果在默认配置的 macrod 已在运行时又启动一个 macrod,它会提示创建 profile 并给出建议名称。按 Enter 接受或输入其他名称,然后在 Quickstart 中完成新机器的配置。 要查看电脑上的所有机器,运行: macrod profiles 它会列出每个 profile 及其配置文件、配对的机器,以及当前是否有 macrod 正在运行。profile 名称只能包含小写字母、数字、- 和 _。

项目文件夹中的配置 旧版本的 macrod 会读取启动时所在文件夹中的 macrod.toml。当你在仍存在该文件的文件夹中运行 macrod 时,macrod 会把它移到 ~/.macrod 并继续运行这台机器。如果还没有默认配置,它就成为 ~/.macrod/macrod.toml;否则会变成一个以该文件夹命名的 profile。macrod 会打印文件的去向以及今后应使用的命令,例如 macrod --profile my-project。

更新与发布版本 macrod 会自动更新。运行期间每小时检查一次新版本,下载并校验 checksum 和启动是否正常。你的 macrod.toml 和配对信息会被保留。如果更新失败,macrod 会继续运行当前版本,并在其 Logs 标签页中显示错误。 macOS 和 Linux:macrod 会在当前没有 agent turn 运行时原地自我替换。更新过程中你的 agent 持续运行,其会话和启动的进程都保持活跃。 Windows:新版本安装在正在运行版本的旁边,页脚显示 Update … ready —— 重启 macrod 即可使用。退出 macrod 再重新启动即可。macrod 命令始终启动最新安装的版本,并清理旧版本。 想了解更新器的操作记录,可查看 ~/.macrod/logs/update.log(Windows 上为 %USERPROFILE%\.macrod\logs\update.log)。每行是一个 JSON 事件:check(记录发现的版本)、download(记录大小和 checksum 是否匹配)、apply(记录版本以及新版本的启动方式),以及每次 macrod 启动(包括更新后)的一条 startup 日志。日志中不会包含 token 或提示词。文件达到约 1 MB 时会滚动到 update.log.1。 要立即更新,重新运行安装命令并重启 macrod。 要安装特定版本,在运行安装命令前把 MACROD_VERSION 环境变量设为对应的 tag,例如 v2026.10.18.0。正在运行的 macrod 仍会自动更新到最新版本。 要关闭自动更新,在 macrod.toml 中添加: [update] auto = false 或设置 MACROD_NO_UPDATE=1 启动 macrod。此后只有重新运行安装命令才会更新。

故障排查 在 Settings → Machines 中查看机器状态,在 MacroD 终端的 Logs 中查看错误。要重新连接,再次运行 macrod 即可。如果你已从 Macro 中移除该机器,需要重新配对。 Quickstart 中找不到你的 agent:确认它已安装,且其命令在你启动 macrod 的终端中可用。对于其他 ACP agent,请使用 Custom command。 设备码无效或已过期:从终端重新发起配对并输入新设备码。截图中的码只是示例。 你的机器处于离线状态:确认电脑没有休眠、macrod 正在运行、且能访问 Macro。查看终端的 Logs 标签页中的错误。 macrod 提示你的配置中包含 [identity] 或 [credentials] 中的 scope:从 ~/.macrod/macrod.toml 中删除这些行。机器的名称、访问权限和权限绕过都在 Settings → Machines 中设置。 更新后 macrod 要求重新配对:从最初启动它的项目文件夹中运行 macrod。它会把该文件夹的 macrod.toml 移入 ~/.macrod,并告知今后应使用的命令。运行 macrod profiles 可查看电脑上的所有机器。 你的 macrod.toml 中有 allow_permission_bypass = false:该设置已移除,你的电脑不再拥有本地否决权。机器能否绕过权限请求,由机器的管理者在 Settings → Machines 的 Allow bypassing permission requests 中设置。

更多在 Macro 工作区中使用 agent 的方法,参见 Agents。

评论 (0)