新 Mac 到手:自己做基础设置,软件交给 Agent 装

新 Mac 到手，有些事要自己看、自己试，比如验机和触控板手感；有些事适合交给 Agent，比如安装软件、配置终端和开发环境。

这份手册按这两类事来排。第一部分照着截图做，第二部分直接发给有本机终端权限的 Agent。 不需要的软件整项跳过。

先核对机器，再调整用起来不顺手的地方。应用放行和 Wi-Fi 排查只在遇到问题时看。

1. 验机：配置、电池和保修

先把「关于本机」里的机型、芯片、内存与订单对一遍，再打开「系统报告 → 电源」，查看电池循环次数、状态和最大容量。台式机跳过电池检查。

循环次数只能作为验机线索，不能仅凭「低于 10 次」判断新机合格。数值异常时，结合订单和销售方说明确认。苹果的循环计数说明^[1]可以用来核对查看方式和机型限制。

保修到苹果保修查询页^[2]核对。序列号在自己电脑上输入即可，不必贴进公开对话。

2. 触控板：先开三指拖移，再按手感调整

三指拖移的入口在「系统设置 → 辅助功能 → 指针控制 → 触控板选项」。

打开拖移，把「拖移样式」设为「三指拖移」，然后实际拖动一个窗口试试。

回到「触控板 → 光标与点按」，按手感调整跟踪速度，并选择习惯的辅助点按方式。下图使用「双指点按或轻点」。

最后到「更多手势」里看一遍页面切换、全屏应用切换和调度中心。不同手势可以自己分配，以设置页显示的方式为准。

图中页面切换为双指左右滚动，调度中心为四指向上轻扫。

3. Dock：觉得慢，再改动画和延迟

如果使用 Dock 自动隐藏，可以缩短显示延迟。先确认自动隐藏已经开启，再通过搜索打开「终端」，执行下面的命令。也可以明确让 Agent 代做这一项。

defaults write com.apple.dock autohide-time-modifier -float 0.5defaults write com.apple.dock autohide-delay -int 0killall Dock

第一项把动画设为 0.5 秒，第二项取消响应延迟。执行前记录这两个键的原值；原来不存在的键也要记下。想撤回时，有原值的写回原值，原来不存在的删除新增键，再重启 Dock。

改完实际试一下。效果可能随 macOS 版本变化，不生效就恢复原值。启动台的行列设置不列入这份通用流程。

4. 应用被拦截：先确认来源，再单独放行

遇到「无法验证开发者」或「已损坏」等提示，先确认是否来自官网，必要时重新下载。没有「仍要打开」按钮，也不能直接判断为签名损坏。

确认是可信应用后，按苹果当前说明^[3]，到「系统设置 → 隐私与安全性」查看拦截记录，再处理「仍要打开」。

入口示例，按钮和文案以本机提示为准。

收到明确的恶意软件警告时停止打开。重新下载仍失败，可以让 Agent 检查签名和错误信息；不要直接关闭 Gatekeeper、清除全部扩展属性或强制重签名。

5. Wi-Fi 有问题：先诊断，别急着删配置

先分清是连不上路由器、连上后无法上网，还是只有某个网站打不开，再看看其他设备是否正常。检查近期是否改过代理、VPN 或 DNS。

仍找不到原因时，按住 Option 点击菜单栏的 Wi-Fi 图标，打开「无线诊断」，参考苹果的操作说明^[4]。诊断文件留在本机，避免直接公开网络信息。

下面是 Wi-Fi 服务的操作菜单，红框标出了「删除服务」入口。它只供定位，不是默认排障步骤。

确需重建网络服务时，先记录配置和恢复方式，准备好断网后如何操作，再决定是否执行。远程 Agent 依赖当前网络连接时，这一步由自己接手。不要直接删除 /Library/Preferences/SystemConfiguration 下的文件。

第二部分：把软件安装交给 Agent

这一部分可以直接发给能操作本机终端的 Agent。它负责检查已有环境、补装缺失软件，并验证结果；密码、登录和必须由本人完成的授权由自己处理。

1. 先给 Agent 这段指令

帮我按下面的清单配置这台 Mac。先检查已装软件，能复用的就复用，缺的再装。

默认安装 Homebrew、Git、iTerm2；Command Line Tools 按需补装。开发工具只安装我点名的项目，没有点名就跳过。第一部分的系统设置保持原样，除非我另有要求。

修改 Shell 配置前先备份，避免重复追加初始化内容。不要覆盖已有软件、项目配置或默认语言版本，也不要全量升级和清理软件。版本、路径和镜像地址按本机与项目要求确定，不照抄占位符。

需要密码、登录、条款确认或权限操作时，遵守当前执行环境的要求，告诉我具体要做什么；其余能独立完成的继续。安装后检查版本和可用性，最后简要列出完成项、失败项和需要我接手的事。没有实际验证的部分要写清楚。

有额外需求，在末尾补一句即可，例如：

终端用 Ghostty；加装 Starship、OrbStack 和 Node。Python、Java、Conda 都不装。

下面是 Agent 执行时需要的清单和命令。Shell 初始化示例使用 zsh；实际使用 bash 或 fish 时，按对应工具的官方说明配置，不改用户默认 Shell。

2. 安装前检查

sw_versuname -mprintf '%s\n' "$SHELL"sysctl -n hw.optional.arm64sysctl -in sysctl.proc_translatedcommand -v brewxcode-select -p

部分 sysctl 查询可能不适用，分别记录结果即可。如果 Apple 芯片上的终端正通过 Rosetta 运行，先改用原生终端再安装，避免误装 Intel 版环境。

检查 Homebrew 的实际位置，以及 /opt/homebrew/bin/brew、/usr/local/bin/brew 是否存在。有两套时先确认用途，复用符合本次需求的一套，不删除另一套。

再检查目标命令和 /Applications、~/Applications 下的应用。/usr/bin/git 等系统入口可能触发工具链安装，先完成下一步的检查，再查询它的版本。

3. 准备 Command Line Tools 和 Homebrew

Command Line Tools：已有就跳过。

xcode-select -pxcrun --find clang

两项成功且路径有效，复用现有工具。缺失时发起安装：

xcode-select --install

安装弹窗出现不代表安装完成。等用户完成必要操作，再运行前两条命令确认；如果报路径或许可错误，按具体错误处理，不反复触发安装。

Homebrew：先查，再装。 已有可用版本时，用 brew --version 和 brew --prefix 确认后复用。没有时，核对官方安装要求^[5]，使用官网^[6]安装入口：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

按安装器提示配置 PATH。zsh 常见的两种写法如下，只用与本机实际安装路径匹配的一种，检查已有配置后再写入 ~/.zprofile：

# Apple 芯片的常见路径eval "$(/opt/homebrew/bin/brew shellenv zsh)"

# Intel 的常见路径eval "$(/usr/local/bin/brew shellenv zsh)"

当前会话也要加载对应环境；独立启动的后续命令进程需要重新加载，或使用工具绝对路径。最后检查：

brew --versionbrew --prefixbrew config

新开终端也能找到正确的 brew，才算配置完成。网络失败时先查错误、代理和连接；需要镜像时使用用户认可的可信来源，按官方说明配置，不运行不明脚本或套用旧版手动克隆 homebrew/core 的流程。

4. 安装常用软件

安装前用 brew info --formula 名称 或 brew info --cask 名称 核对包名、来源和系统要求。已有其他来源的同名软件且可用时，直接复用。

把本次选中且缺失的软件写入单独的 Brewfile。完整基础清单如下，执行时按实际选择删减，不覆盖已有文件：

brew "git"cask "iterm2"cask "iina"cask "obsidian"cask "keka"

在该文件所在目录执行：

brew bundle install --file=./Brewfile --no-upgradebrew bundle check --file=./Brewfile --no-upgrade

--no-upgrade 跳过常规升级，安装依赖仍可能引发升级；它不能锁定版本。用户有版本限制时先检查影响，详见 Homebrew Bundle 文档^[7]。某项失败只处理该项，其他独立安装继续。

iTerm2提供分屏、搜索、热键和 Profile。选择 Ghostty 时，核对其官方安装渠道并替换终端项。

Obsidian的官方演示。首次启动停在欢迎页或库选择页即可，不打开已有私有笔记库。

iShot 按需安装，先核对官方或 App Store 入口；涉及账号、授权或付款时交给用户。

5. 按需安装开发工具

只执行用户选中的项目。已有可用版本管理器时优先复用，下面的工具不必全部安装。

Starship：终端提示符

brew install starshipstarship --version

检查已有提示符主题，确认不会冲突后，在 ~/.zshrc 合适位置加入一次：

eval "$(starship init zsh)"

新开终端看实际效果。字体缺字时参考 Starship 官方说明^[8]，保留原主题配置，方便撤回。

容器：OrbStack 和 Docker Desktop 选一个

已有可用容器环境时复用。新装按用户选择执行其中一项：

# 选择 OrbStack 时brew install --cask orbstack

# 选择 Docker Desktop 时brew install --cask docker-desktop

Docker Desktop 的 cask 名称是 docker-desktop^[9]，执行时核对当前包信息。单独 brew install docker 只安装客户端，不能提供本机容器运行环境。

OrbStack的安装和初次使用见官方快速开始。

启动所选应用，完成必要的用户操作后检查：

docker versiondocker context lsdocker context show

客户端和服务端都可连接，才算运行环境可用。需要指定 context 时，使用列表中的实际名称；优先只对本次命令指定，不改用户默认值。

可以用来源明确的一次性测试容器进一步验证，提前记录下载的镜像，运行时用 --rm。拉取失败先查网络，不套用旧镜像列表，不清理已有容器、镜像和卷。

Node：Volta

先检查已有的 Node 管理方式，避免与 nvm、fnm 等重复安装。新装 Volta 使用官方入口^[10]：

curl -fsSL https://get.volta.sh | bash

安装器会处理常见 Shell 初始化，检查改动后再决定是否补充。当前会话需要立即使用时，确认目录后加载：

export VOLTA_HOME="$HOME/.volta"export PATH="$VOLTA_HOME/bin:$PATH"volta --version

Node 版本按项目要求选择。全新环境没有版本约束时，安装 LTS 并验证：

volta install nodevolta list nodenode --versionnpm --version

已有默认版本时保留；只有用户要求修改指定项目时才执行 volta pin。npm 源也保留现状，需要换源再记录原地址并修改。

Python：pyenv

先看项目要求和已有环境。已经用 Conda 管理该项目时，直接看下一项。

brew install pyenvpyenv --version

zsh 初始化内容写入 ~/.zshrc，已有等效配置就跳过：

export PYENV_ROOT="$HOME/.pyenv"[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"eval "$(pyenv init - zsh)"

pyenv install --list

按项目要求确定完整版本号，并核对 Python 构建依赖^[11]。Agent 把实际版本赋给 MAC_SETUP_PYTHON_VERSION 后执行：

: "${MAC_SETUP_PYTHON_VERSION:?先设置已确定的完整 Python 版本号}"pyenv install -s "$MAC_SETUP_PYTHON_VERSION"PYENV_VERSION="$MAC_SETUP_PYTHON_VERSION" pyenv exec python --versionPYENV_VERSION="$MAC_SETUP_PYTHON_VERSION" pyenv exec python -m pip --version

先验证指定版本，不自动修改全局默认值；只有用户要求配置指定项目时，才在那个目录写入 .python-version。

Conda：按项目建环境

已有 Conda 时复用。新装按官方 macOS 说明^[12]，选择匹配芯片和系统的 Miniconda 安装器，校验官方 SHA-256，确认安装目录没有被占用，再运行。条款确认交给用户。

需要 Shell 集成时，备份后运行 conda init zsh。重新加载环境，再检查：

conda --versionconda info --envsconda config --show

新装且不需要启动时自动进入 base，可以设置：

conda config --set auto_activate_base false

按用户或项目要求确定环境名与 Python 版本，检查同名环境后再创建。用 conda run -n 实际环境名 python --version 验证。没有明确需要时，不更换源或 solver；与 pyenv 共存时先理清 PATH 和初始化顺序。

Java：先装 JDK，再用 jEnv 切换

先看已有 JDK：

/usr/libexec/java_home -V

按项目要求选择 JDK 发行版和主版本，能复用就复用。缺失时核对官方渠道或当前 Homebrew cask，再安装；不要沿用旧教程里的固定版本和路径。

需要 jEnv^[13] 管理多个 JDK 时：

brew install jenvjenv --version

zsh 初始化内容：

export PATH="$HOME/.jenv/bin:$PATH"eval "$(jenv init -)"

需要 jEnv 管理 JAVA_HOME 时再启用：

jenv enable-plugin export

从本机输出取得 JDK Home，用 jenv add 注册，再用 jenv versions 检查。验证 java -version、javac -version 和 JAVA_HOME 是否一致。项目或全局版本只在用户要求时修改。

AI 编程工具：按习惯选

Cursor、Pi Agent、Codex 按需选择。先核对所选产品的当前官方安装渠道；同名工具无法区分时，向用户确认官网或仓库，不猜包名。

安装后先验证能否启动。登录、API Key、模型和付费设置按用户授权处理；缺少凭据就写「已安装，待配置」，不把安装成功当作连接成功，也不把密钥写进报告。

6. 装完后，告诉我哪些能用了

命令行工具检查版本和实际路径；容器要检查服务端连接；有 GUI 能力时启动图形应用。只能确认应用包存在的，写「已安装，启动未验证」。官网截图不能作为本机安装证据。

最后简要汇报四件事即可：

• • 完成了什么：包括复用的已有软件，以及实际版本和验证结果。
• • 改了什么：配置文件、备份位置和必要的撤回方式。撤回时保留后续编辑，不直接整份覆盖。
• • 还有什么没完成：失败原因、影响范围、需要用户操作的入口。
• • 哪些跳过了：未选中的开发工具、系统设置或不适用项。

保留实际使用的 Brewfile，方便以后补装；它记录清单，不锁定精确版本。有失败或待处理项，就把剩余事项写清楚，不宣称整台 Mac 已全部配置完成。

引用链接

[1] 苹果的循环计数说明: https://support.apple.com/en-us/102888[2] 苹果保修查询页: https://checkcoverage.apple.com/[3] 苹果当前说明: https://support.apple.com/en-us/102445[4] 苹果的操作说明: https://support.apple.com/en-ie/guide/mac-help/mchlf4de377f/27/mac/27[5] 官方安装要求: https://docs.brew.sh/Installation[6] 官网: https://brew.sh/[7] Homebrew Bundle 文档: https://docs.brew.sh/Brew-Bundle-and-Brewfile[8] Starship 官方说明: https://starship.rs/guide/[9] `docker-desktop`: https://formulae.brew.sh/cask/docker-desktop[10] 官方入口: https://docs.volta.sh/guide/getting-started[11] Python 构建依赖: https://github.com/pyenv/pyenv#installation[12] 官方 macOS 说明: https://docs.conda.io/projects/conda/en/stable/user-guide/install/macos.html[13] jEnv: https://www.jenv.be/