几步之后，
进入你的工作空间。

先确认你的 Mac

系统

macOS 14 Sonoma 或更高版本

芯片

Apple 芯片（M 系列），当前发布包为 arm64

安装包

DMG 磁盘映像

安装位置

/Applications/1Agent.app

可在苹果菜单的“关于本机”中查看芯片和系统版本。目前没有面向 Windows、Linux 或 Intel Mac 的正式安装包。

下载，拖入应用程序

下载最新 DMG ↓

如果无法直接下载，打开 GitHub 最新正式版，在 Assets 中选择 1Agent-版本号-mac-arm64.dmg。

1. 打开下载好的 DMG 文件。
2. 将 1Agent 拖入映像窗口中的 Applications（应用程序）。
3. 如已安装旧版，先退出 1Agent，再确认替换。
4. 在 Finder 的“应用程序”中打开 1Agent。安装完成后可推出磁盘映像。

第一次打开时

当前 GitHub 分发版本未经过 Apple 公证。macOS 可能提示“无法验证开发者”或无法确认应用是否包含恶意软件。

1. 先从“应用程序”中尝试打开 1Agent，关闭出现的系统提示。
2. 进入 系统设置 → 隐私与安全性，向下找到与 1Agent 对应的拦截信息。
3. 点击 仍要打开，按系统提示确认，再打开应用。

如果提示“应用已损坏”

先确认 DMG 下载完整，并已将应用拖入“应用程序”。核对来源后，可在系统“终端”中执行下方命令，仅移除这个应用的下载隔离标记，再重新打开。

xattr -dr com.apple.quarantine "/Applications/1Agent.app"

这条命令只针对 /Applications/1Agent.app。如果依然无法打开，请重新下载最新安装包，并向项目提交具体系统提示。

从一个本机终端开始

打开应用后，新建本机会话即可使用。用侧栏切换会话，用分屏并排处理任务；快捷键以应用菜单和设置中的当前绑定为准。

连接远程主机

1Agent 读取 Mac 上的 ~/.ssh/config，也支持其中的 Include。已经配置好的密钥、端口和跳板机会继续使用。以下是一个示例，请替换成自己的信息：

Host studio-demo
    HostName demo.example.com
    User your-user
    Port 22
    IdentityFile ~/.ssh/id_ed25519

先在系统终端确认 ssh studio-demo 能正常连接，再在 1Agent 中打开对应主机。首次连接时核对主机指纹，按提示完成认证。

搭配 1Panel

在同一台 Mac 上，1Panel 可以通过 oneagent://open 将对应主机交给 1Agent。两个应用也可以单独使用，无需为 1Agent 另外安装 Ghostty。

恢复工作空间

正常退出时会保存终端输出与会话布局，下次启动时恢复。退出应用会结束运行中的命令；历史输出的恢复不代表远程连接或进程一直在后台运行。

保持更新

在 1Agent 菜单中选择 检查更新…，按应用提示下载并安装新版本。也可以从 GitHub 下载最新 DMG，退出旧版后重新拖入“应用程序”进行替换。

更新前先完成或保存正在进行的任务；替换应用需要重启，会中断运行中的命令。更新记录可在 GitHub Releases 查看。

也可以从源码构建

需要 macOS 14 或更高版本、完整 Xcode（项目配置为 Xcode 16）和 XcodeGen。先打开 Xcode 完成首次初始化并接受许可；如已安装 Homebrew，可使用 brew install xcodegen 安装 XcodeGen。

git clone https://github.com/itjun/1Agent.git
cd 1Agent
make build

make build 会编译、本地签名，将应用安装到 /Applications/1Agent.app，然后启动。如果已有运行中的 1Agent，安装脚本会退出并替换它，执行前请先保存工作。

应用身份为 com.itjun.1agent，URL 协议为 oneagent://。更多构建与终端自动化说明见 项目 README 和 终端窗口与自动化文档。

还想确认一些事？