MacBook 设置指南

前言

本文档用于记录一台新 MacBook 从初始状态到日常开发、学习和办公可用状态的完整设置过程。

记录内容会按照实际配置顺序逐步补充，包括系统偏好设置、常用软件安装、开发环境配置、终端与 Shell 设置、账号与同步服务、效率工具以及后续维护事项。

本指南的目标不是一次性列出所有可能的配置，而是把每一步真实完成的设置记录清楚，方便以后复盘、迁移到新设备，或在系统重装后快速恢复工作环境。

第一部分：系统设置

1.1 触控板设置

轻点以点按

• 设置路径：系统设置 -> 触控板 -> 光标与点按 -> 轻点以点按
• 设置状态：已开启
• 设置效果：可以通过轻点触控板完成点击操作，不需要用力按下触控板。

三指拖移

• 设置路径：系统设置 -> 辅助功能 -> 指针控制 -> 触控板选项 -> 使用触控板进行拖移
• 拖移方式：三指拖移
• 设置状态：已开启
• 设置效果：可以用三根手指在触控板上拖动窗口、选择文本或移动文件，减少按压触控板的操作。

App Expose

• 设置路径：系统设置 -> 触控板 -> 更多手势 -> App Expose
• 手势方式：四指向下轻扫
• 设置状态：已开启
• 设置效果：可以通过四指向下轻扫快速查看当前 App 的所有窗口。

1.2 程序坞设置

关闭最近使用的 App

• 设置路径：系统设置 -> 桌面与程序坞 -> 在程序坞中显示建议和最近使用的 App
• 设置状态：已关闭
• 设置效果：程序坞只显示固定的 App 和当前正在运行的 App，不再额外显示最近使用过的 App。

将窗口最小化至应用程序图标

• 设置路径：系统设置 -> 桌面与程序坞 -> 将窗口最小化至应用程序图标
• 设置状态：已开启
• 设置效果：窗口最小化后会收纳到对应 App 的程序坞图标中，而不是单独显示在程序坞右侧。

移除程序坞默认的不常用 App

• 操作方式：在程序坞中右键点击不常用 App 图标 -> 选项 -> 从程序坞中移除
• 设置状态：已完成
• 设置效果：减少程序坞中的默认 App 数量，只保留常用 App，使程序坞更简洁。

下载文件夹改为列表显示

• 操作方式：在程序坞中右键点击“下载”文件夹 -> 显示内容为 -> 列表
• 设置状态：已完成
• 设置效果：点击程序坞中的“下载”文件夹时，以列表形式展示下载内容，方便快速浏览和打开文件。

1.3 菜单栏设置

电池显示百分比

• 设置路径：系统设置 -> 控制中心 -> 电池 -> 显示百分比
• 设置状态：已开启
• 设置效果：菜单栏电池图标旁显示具体电量百分比，便于快速判断剩余电量。

时间显示秒

• 设置路径：系统设置 -> 控制中心 -> 时钟选项 -> 显示秒
• 设置状态：已开启
• 设置效果：菜单栏时间精确显示到秒，方便需要精确计时或观察时间变化的场景。

1.4 键盘设置

按下地球键切换输入法

• 设置路径：系统设置 -> 键盘 -> 按下地球键以 -> 更改输入法
• 设置状态：已开启
• 设置效果：按下地球键时可以在已添加的输入法之间切换，方便中英文输入切换。

1.5 Finder 设置

在桌面显示已连接的服务器

• 设置路径：Finder -> 设置 -> 通用 -> 在桌面上显示这些项目 -> 已连接的服务器
• 设置状态：已开启
• 设置效果：连接服务器后，服务器图标会显示在桌面上，方便快速访问挂载的网络位置。

显示所有文件扩展名

• 设置路径：Finder -> 设置 -> 高级 -> 显示所有文件扩展名
• 设置状态：已开启
• 设置效果：Finder 中会显示文件完整扩展名，便于判断文件类型和避免误改文件格式。

自定义 Finder 工具栏

• 设置路径：Finder -> 显示 -> 自定义工具栏
• 新增按钮：AirDrop、新建文件夹、删除、连接服务器、打开/关闭侧边栏
• 设置状态：已完成
• 设置效果：在 Finder 工具栏中直接提供常用操作入口，方便快速进行文件管理、连接服务器，以及切换侧边栏显示状态。

在下方显示文件夹路径

• 设置路径：Finder -> 显示 -> 显示路径栏
• 设置状态：已开启
• 设置效果：Finder 窗口底部显示当前文件夹的完整路径，方便确认当前位置并快速跳转到上级目录。

1.6 快捷键设置

在当前 Finder 窗口位置打开终端

• 快捷键：Command + Option + T
• 触发位置：当前最顶部的 Finder 窗口
• 实现方式：AppleScript
• 设置状态：已完成
• 设置效果：按下快捷键后，会在当前最前方 Finder 窗口所在目录打开终端，方便直接进入当前文件夹执行命令。

AppleScript 内容如下：

-- 在 Finder 前窗目录新建 Terminal 窗口；若无前窗，则在用户主目录 ~
on run
	-- 默认路径：用户主目录
	set thePath to POSIX path of (path to home folder)

	tell application "Finder"
		if (count of windows) > 0 then
			try
				set thePath to POSIX path of ((target of front window) as alias)
			on error
				-- 如果 Finder 前窗是“最近使用”“标签”“搜索结果”等虚拟位置，则退回到用户主目录
				set thePath to POSIX path of (path to home folder)
			end try
		end if
	end tell

	if application "Terminal" is running then
		-- Terminal 已运行：在当前 Terminal 中新建窗口
		tell application "Terminal"
			activate
			do script "cd " & quoted form of thePath & "; clear"
		end tell
	else
		-- Terminal 未运行：用 do script 直接启动（只会有一个窗口）
		tell application "Terminal"
			do script "cd " & quoted form of thePath & "; clear"
			activate
		end tell
	end if
end run

完整设置步骤：

1. 打开“自动操作”（Automator）。
2. 新建一个“快速操作”。
3. 将“工作流程收到当前”设置为“没有输入”，位置选择“位于任何应用程序”。
4. 在左侧操作库中搜索并添加“运行 AppleScript”。
5. 将默认脚本替换为上面的 AppleScript 内容。
6. 保存快速操作，名称可设为“在当前 Finder 位置打开终端”。
7. 打开“系统设置 -> 键盘 -> 键盘快捷键 -> 服务”。
8. 找到刚创建的快速操作，并为它绑定快捷键 Command + Option + T。
9. 第一次运行时，如果系统提示允许“自动操作”或相关服务控制 Finder、Terminal，需要选择允许。

使用逻辑：

• 如果 Finder 当前有窗口，则读取最前方 Finder 窗口所在目录，并在该目录打开 Terminal。
• 如果 Finder 当前没有窗口，则默认在用户主目录打开 Terminal。
• 如果 Finder 当前窗口是“最近使用”“标签”“搜索结果”等无法转换为本地路径的虚拟位置，则默认在用户主目录打开 Terminal。
• 如果 Terminal 已经在运行，则新建一个 Terminal 窗口并进入目标目录。
• 如果 Terminal 没有运行，则启动 Terminal，并直接进入目标目录。

第二部分：必要软件安装

2.1 常用软件安装

软件清单与官方下载链接

分类	软件	官方下载页面/安装包入口	备注
即时通讯	QQ	QQ for Mac	腾讯官方 Mac QQ 下载入口，也可在 Mac App Store 搜索 QQ
即时通讯	微信	微信 Mac 版	腾讯官方微信 Mac 下载入口，也可通过 Mac App Store 安装
音乐	QQ 音乐	QQ 音乐下载页	在下载页选择 Mac 版
协作办公	飞书	飞书客户端下载页	根据 Mac 芯片选择 Intel 版或 Apple 芯片版
开发工具	Visual Studio Code	VS Code 下载页	可下载安装包，或使用 brew install --cask visual-studio-code；详细设置见 VS Code 官方 macOS 安装说明
办公软件	WPS Office	WPS Office for Mac	根据 Mac 芯片选择 Intel 版或 Apple 芯片版
浏览器	Microsoft Edge	Microsoft Edge 下载页	选择 macOS 版本下载安装
网络工具	Tailscale	Tailscale 下载页	推荐安装 Standalone 版；也可在 Homebrew 安装后使用 brew install --cask tailscale-app
代理工具	Clash Verge Rev	Clash Verge Rev Releases	原 Clash Verge 已停止维护，建议使用 Clash Verge Rev；也可在 Homebrew 安装后使用 brew install --cask clash-verge-rev

安装注意事项：

• 优先从官方页面下载安装包，避免使用第三方下载站。
• 如果下载页面提供 Intel 芯片版和 Apple 芯片版，应先通过“苹果菜单 -> 关于本机”确认当前 Mac 的芯片类型。
• 下载 .dmg 安装包后，通常需要打开安装包并将 App 拖入“应用程序”文件夹。

2.2 默认软件设置

默认浏览器

• 设置路径：系统设置 -> 桌面与程序坞 -> 默认网页浏览器
• 默认软件：Microsoft Edge
• 设置状态：已完成
• 设置效果：网页链接默认使用 Microsoft Edge 打开。

Office 文档默认打开方式

• 设置方式：右键点击对应类型文件 -> 显示简介 -> 打开方式 -> 选择 WPS Office -> 全部更改
• 默认软件：WPS Office
• 适用文件类型：Word 文档、Excel 表格、PowerPoint 演示文稿等 Office 文件
• 设置状态：已完成
• 设置效果：常见 Office 文件默认使用 WPS Office 打开。

文本与代码文件默认打开方式

• 设置方式：右键点击对应类型文件 -> 显示简介 -> 打开方式 -> 选择 Visual Studio Code -> 全部更改
• 默认软件：Visual Studio Code
• 适用文件类型：文本文件、Markdown 文件、代码文件和配置文件
• 设置状态：已完成
• 设置效果：常见文本、代码和配置文件默认使用 Visual Studio Code 打开，方便直接编辑。
• 详细设置：VS Code 官方 macOS 安装说明

2.3 网络与代理工具安装

Tailscale

Tailscale 用于把多台设备组成一个安全的私有网络，适合访问自己的服务器、NAS、实验室机器或远程开发环境。

官方推荐 macOS 安装 Standalone 版：

1. 打开 Tailscale macOS 下载页。
2. 下载 macOS 安装包。
3. 打开安装包并完成安装。
4. 启动 Tailscale，按提示登录账号。
5. 在菜单栏确认 Tailscale 已连接。

如果已经安装 Homebrew，也可以使用 Homebrew Cask 安装：

brew install --cask tailscale-app

安装后如果系统提示允许网络扩展或系统扩展，需要在：

系统设置 -> 隐私与安全性

中允许 Tailscale 相关扩展，然后重新打开 Tailscale。

常用验证：

tailscale status
tailscale ip

说明：

• macOS 上优先安装 Tailscale Standalone 版。
• 不要同时安装 App Store 版和 Standalone 版，否则可能导致 Tailscale 扩展无法正常启动。
• 如果只是普通桌面使用，不建议安装纯命令行版 tailscaled。

Clash Verge Rev

Clash Verge Rev 是 Clash Verge 的社区维护版本，内置 mihomo 内核，用于管理代理订阅、规则、系统代理和 TUN 模式。

官方发布入口：

• Clash Verge Rev GitHub Releases

下载安装步骤：

1. 打开 GitHub Releases 页面。
2. 在最新版本中选择 macOS 安装包。
3. Apple Silicon Mac 选择 aarch64.dmg。
4. Intel Mac 选择 x64.dmg。
5. 打开 .dmg 文件，将 Clash Verge.app 拖入“应用程序”文件夹。
6. 启动 Clash Verge Rev。

如果已经安装 Homebrew，也可以使用 Homebrew Cask 安装：

brew install --cask clash-verge-rev

首次启动时，如果 macOS 提示来自未识别开发者或阻止打开，可以在：

系统设置 -> 隐私与安全性

中允许打开该 App。

基础配置步骤：

1. 打开 Clash Verge Rev。
2. 在 Profiles 或订阅配置页面添加自己的代理订阅链接。
3. 更新订阅。
4. 选择可用节点。
5. 按需要开启系统代理或 TUN 模式。

说明：

• Clash Verge Rev 本身只是代理客户端，需要用户自行准备合法可用的订阅配置。
• 系统代理适合浏览器和大多数普通 App。
• TUN 模式会接管更多网络流量，首次开启时可能需要输入系统密码并允许相关网络权限。
• 如果只是临时网页代理，优先使用系统代理；如果需要让更多命令行或非代理感知 App 走代理，再考虑 TUN 模式。

第三部分：开发环境配置

本部分用于从零开始配置一台新 MacBook 的开发环境。整体原则是：先安装 Homebrew，后续 C/C++、Python、Conda、Rust、Node.js/npm、Go、Java、tmux 等工具链都优先通过 Homebrew 安装和管理。

3.1 开发环境管理原则

• 统一使用 Homebrew 作为 macOS 包管理器。
• 命令行工具优先使用 brew install 安装。
• 图形界面软件优先使用 brew install --cask 安装。
• 尽量避免从不明来源下载安装脚本或压缩包。
• 全局工具尽量交给 Homebrew 管理，项目依赖则交给各语言自己的项目级配置管理。

3.2 安装 Homebrew

安装前准备

打开“终端”，确认当前默认 Shell 为 zsh：

echo $SHELL

如果系统尚未安装 Apple Command Line Tools，可以先执行：

xcode-select --install

如果跳过这一步，Homebrew 安装过程中通常也会提示安装所需的命令行工具。

官方安装命令

• 官方网站：Homebrew

在终端执行 Homebrew 官方安装命令：

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

安装脚本会说明将要执行的操作，并在真正安装前暂停确认。按提示输入登录密码并继续安装。

配置 Homebrew 到 PATH

Apple Silicon Mac 的 Homebrew 默认安装路径是 /opt/homebrew。安装完成后，按终端提示把 Homebrew 加入 zsh 启动配置。

常用配置命令如下：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

如果是 Intel Mac，Homebrew 默认路径通常是 /usr/local，对应命令为：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

验证 Homebrew

command -v brew
brew --version
brew --prefix
brew doctor

如果 command -v brew 能输出 Homebrew 路径，brew --version 能输出版本号，说明 Homebrew 已经可以正常使用。

3.3 Homebrew 常用命令

brew update              # 更新 Homebrew 自身和软件索引
brew upgrade             # 升级已安装的软件包
brew search <name>       # 搜索软件包
brew info <name>         # 查看软件包信息
brew install <name>      # 安装命令行软件
brew install --cask <name> # 安装图形界面软件
brew list                # 查看已安装的软件包
brew uninstall <name>    # 卸载软件包
brew cleanup             # 清理旧版本缓存
brew doctor              # 检查 Homebrew 环境

3.4 Git 工具下载与环境配置

Git 是后续代码管理、项目协作和从 GitHub/GitLab 拉取项目的基础工具。新 MacBook 上建议通过 Homebrew 安装 Git，并同步安装 Git LFS、GitHub CLI 等常用配套工具。

官方下载与安装入口

工具	用途	官方入口	Homebrew 安装命令
Git	版本控制命令行工具	Git for macOS	brew install git
Git LFS	管理仓库中的大文件	Git LFS	brew install git-lfs
GitHub CLI	在终端中操作 GitHub 仓库、Issue、PR	GitHub CLI	brew install gh
Git GUI / gitk	Git 自带图形界面和提交历史查看器	Git for macOS	brew install git-gui
GitHub Desktop	可选的 GitHub 图形客户端	GitHub Desktop	brew install --cask github

安装命令

优先安装 Git、Git LFS 和 GitHub CLI：

brew install git git-lfs gh

如果需要 Git 自带图形界面：

brew install git-gui

如果需要 GitHub Desktop：

brew install --cask github

验证安装

git --version
git lfs version
gh --version

Git 基础身份配置

配置提交时使用的用户名和邮箱。这里的邮箱应尽量与 GitHub、GitLab 或学校/公司代码平台账号一致。

git config --global user.name "你的姓名"
git config --global user.email "your_email@example.com"

查看配置：

git config --global --list

推荐全局配置

git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.autocrlf input
git config --global core.quotepath false
git config --global color.ui auto

配置说明：

• init.defaultBranch main：新仓库默认分支名使用 main。
• pull.rebase false：git pull 默认使用 merge，行为更直观。
• core.autocrlf input：提交时规范换行符，适合 macOS/Linux 开发环境。
• core.quotepath false：让 Git 正常显示中文文件名。
• color.ui auto：自动启用彩色命令行输出。

如果已经安装 VS Code，并希望把它作为 Git 默认编辑器：

git config --global core.editor "code --wait"

如果终端提示找不到 code 命令，需要在 VS Code 中打开命令面板，执行：

Shell Command: Install 'code' command in PATH

初始化 Git LFS

Git LFS 安装后，需要对当前用户初始化一次：

git lfs install

后续如果某个仓库需要跟踪大文件，可以在仓库中执行：

git lfs track "*.psd"
git add .gitattributes

实际要跟踪的文件类型根据项目需要调整，例如模型文件、数据集、设计文件或大型二进制文件。

配置 SSH Key

生成 SSH Key：

ssh-keygen -t ed25519 -C "your_email@example.com"

按提示保存到默认路径 ~/.ssh/id_ed25519，并设置或跳过 passphrase。

启动 ssh-agent，并把私钥加入 macOS 钥匙串：

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

创建或编辑 SSH 配置文件：

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/config
chmod 600 ~/.ssh/config

在 ~/.ssh/config 中加入：

Host github.com
  HostName github.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

复制公钥内容：

pbcopy < ~/.ssh/id_ed25519.pub

然后打开 GitHub 或 GitLab 的 SSH Keys 设置页面，新增 SSH Key。

测试 GitHub SSH 连接

ssh -T git@github.com

第一次连接时会提示确认主机指纹，输入 yes。如果配置成功，会看到 GitHub 返回认证成功的信息。

配置 GitHub CLI

如果使用 GitHub，可以通过 GitHub CLI 登录：

gh auth login

按提示选择：

• GitHub.com
• SSH
• 使用浏览器登录

登录后验证：

gh auth status

常用 Git 验证命令

git config --global user.name
git config --global user.email
git config --global init.defaultBranch
git config --global core.autocrlf
git config --global core.quotepath
git lfs env
gh auth status

3.5 Vim 安装与基础配置

Vim 是常用的终端文本编辑器，适合快速编辑配置文件、脚本和远程服务器上的文本内容。macOS 自带 vi，但版本通常较旧、功能较少，因此新 MacBook 建议通过 Homebrew 安装新版 Vim。

官方下载与安装入口

工具	用途	官方入口	Homebrew 安装命令
Vim	终端文本编辑器	Vim 下载页	brew install vim
MacVim	可选的 macOS 图形界面 Vim	MacVim 项目	brew install macvim

默认推荐安装终端版 Vim：

brew install vim

如果明确需要图形界面版本，可以选择安装 MacVim：

brew install macvim

注意：Homebrew 中的 vim 和 macvim 互相冲突，不建议同时安装。一般开发环境只安装 vim 即可。

验证安装

vim --version
which vim

如果 which vim 输出 Homebrew 路径，说明当前终端优先使用的是 Homebrew 安装的 Vim。

Apple Silicon Mac 的常见路径：

/opt/homebrew/bin/vim

Intel Mac 的常见路径：

/usr/local/bin/vim

设置默认终端编辑器

将 Vim 设置为终端默认编辑器：

cat >> ~/.zshrc <<'EOF'
export EDITOR=vim
export VISUAL=vim
EOF
source ~/.zshrc

如果希望 Git 默认使用 Vim 编辑提交信息：

git config --global core.editor "vim"

创建基础 Vim 配置

可以创建一个简洁的 ~/.vimrc：

cat > ~/.vimrc <<'EOF'
set nocompatible
syntax on
filetype plugin indent on

set number
set relativenumber
set ruler
set showcmd
set wildmenu

set tabstop=4
set shiftwidth=4
set expandtab
set autoindent
set smartindent

set ignorecase
set smartcase
set incsearch
set hlsearch

set backspace=indent,eol,start
set clipboard=unnamed
EOF

配置说明：

• 显示行号和相对行号，方便代码跳转。
• 开启语法高亮和文件类型缩进。
• 默认使用 4 空格缩进。
• 搜索时忽略大小写，但输入大写字母时自动区分大小写。
• 使用 macOS 剪贴板，方便在 Vim 和其他 App 之间复制粘贴。

常用验证

vim --version
vim ~/.vimrc
echo $EDITOR
git config --global core.editor

3.6 tmux 安装与基础配置

tmux 是终端复用工具，可以在一个终端窗口中管理多个会话、窗口和面板。它适合远程服务器开发、长时间任务运行、多项目并行操作，以及断开 SSH 后继续保留工作现场。

官方入口

• 官方网站：tmux
• GitHub 仓库：tmux/tmux
• Homebrew 安装命令：brew install tmux

安装

brew install tmux

验证

tmux -V
which tmux

创建基础配置

新建或覆盖 ~/.tmux.conf：

cat > ~/.tmux.conf <<'EOF'
# Use C-a as prefix instead of the default C-b.
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Basic behavior.
set -g mouse on
set -g history-limit 100000
set -g escape-time 10
set -g renumber-windows on
set -g base-index 1
setw -g pane-base-index 1
setw -g mode-keys vi

# Terminal color.
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",xterm-256color:RGB"

# Keep new panes and windows in the current directory.
bind c new-window -c "#{pane_current_path}"
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Pane navigation.
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Pane resizing.
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

# Reload config.
bind r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"

# Copy mode with vi keys and macOS clipboard.
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
set -g set-clipboard on

# Status bar.
set -g status-position bottom
set -g status-interval 5
set -g status-left "#[bold] #S "
set -g status-right "%Y-%m-%d %H:%M"
EOF

加载配置：

tmux source-file ~/.tmux.conf

如果当前还没有进入 tmux，会提示找不到 tmux server。可以先启动 tmux：

tmux

然后按 Control + A，再按 r 重新加载配置。

可选：安装 TPM 插件管理器

TPM 是 tmux 的插件管理器，用于安装和管理 tmux 插件。

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

在 ~/.tmux.conf 末尾追加插件配置：

cat >> ~/.tmux.conf <<'EOF'

# tmux plugin manager
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

# Automatically restore tmux sessions.
set -g @continuum-restore 'on'

run '~/.tmux/plugins/tpm/tpm'
EOF

安装插件：

1. 进入 tmux。
2. 按 Control + A。
3. 再按大写 I。
4. 等待插件安装完成。

常用插件说明：

• tmux-sensible：提供一组合理默认设置。
• tmux-resurrect：保存和恢复 tmux 会话。
• tmux-continuum：自动保存和自动恢复 tmux 会话。

常用命令

tmux new -s dev          # 新建名为 dev 的会话
tmux ls                 # 查看所有会话
tmux attach -t dev       # 连接到 dev 会话
tmux switch -t dev       # 切换到 dev 会话
tmux rename-session main # 重命名当前会话
tmux kill-session -t dev # 删除 dev 会话

常用快捷键

以下快捷键基于上面的配置，前缀键是 Control + A。

快捷键	作用
Control + A 然后 c	新建窗口
Control + A 然后 ,	重命名窗口
Control + A 然后 &	关闭窗口
Control + A 然后 `	`
Control + A 然后 -	上下分屏
Control + A 然后 h/j/k/l	在面板间移动
Control + A 然后 H/J/K/L	调整面板大小
Control + A 然后 [	进入复制模式
Control + A 然后 d	断开当前会话
Control + A 然后 r	重新加载配置

使用建议

• 本地开发可以为每个长期项目创建一个 tmux 会话。
• 远程服务器上运行训练、编译、下载等长任务时，优先放在 tmux 中执行。
• 如果使用 SSH 连接服务器，先进入 tmux 再开始工作，避免网络断开导致任务终止。
• 如果不习惯 Control + A 前缀，可以保留默认 Control + B，删除配置中的 unbind C-b、set -g prefix C-a 和 bind C-a send-prefix 三行。

3.7 基础命令行工具

先安装一些通用命令行工具，后续开发会经常用到：

brew install wget curl tree

验证：

wget --version
curl --version
tree --version

3.8 C/C++ 开发环境

macOS 自带的 Command Line Tools 会提供 Apple Clang、make、LLDB 等基础工具。为了获得更完整、更新的 C/C++ 工具链，继续通过 Homebrew 安装 LLVM、CMake、Ninja 等工具。

安装

brew install llvm cmake ninja pkgconf ccache

配置 LLVM

Homebrew 安装的 LLVM 通常不会默认覆盖系统自带的 Apple Clang。若希望优先使用 Homebrew LLVM，可以将它加入 PATH：

echo 'export PATH="$(brew --prefix llvm)/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

验证

clang --version
clang++ --version
cmake --version
ninja --version
pkg-config --version
ccache --version

说明

• 日常 C/C++ 项目推荐使用 CMake 管理构建配置。
• Ninja 通常比 Make 更快，适合配合 CMake 使用。
• macOS 默认调试器是 LLDB；如果确实需要 GDB，后续再单独安装和配置代码签名。

3.9 Python 开发环境

Python 本体通过 Homebrew 安装。项目依赖优先放在虚拟环境中，不建议直接把大量 Python 包安装到全局环境。

安装 Python

brew install python

验证

python3 --version
pip3 --version

创建项目虚拟环境

进入项目目录后执行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

退出虚拟环境：

deactivate

安装 Python 命令行工具

如果某些 Python 工具需要全局使用，推荐通过 pipx 隔离安装：

brew install pipx
pipx ensurepath

3.10 Conda 环境

Conda 用于管理数据科学、机器学习和需要复杂二进制依赖的 Python 环境。这里推荐通过 Homebrew 安装 Miniforge，它默认使用 conda-forge 生态，适合 Apple Silicon Mac。

安装 Miniforge

brew install --cask miniforge

初始化 Conda

conda init "$(basename "$SHELL")"

执行后关闭并重新打开终端。

推荐配置

关闭默认自动进入 base 环境：

conda config --set auto_activate_base false

创建 Conda 环境

conda create -n py312 python=3.12
conda activate py312
python --version
conda deactivate

说明

• 普通 Python 项目优先使用 venv。
• 数据科学、深度学习、需要 CUDA/复杂依赖或多 Python 版本隔离时使用 Conda。
• 不要在同一个项目里混乱叠加 Homebrew Python、Conda Python 和系统 Python；每个项目只选一种环境入口。

3.11 Rust 开发环境

Rust 工具链通过 Homebrew 安装，包含 rustc 编译器和 cargo 包管理器。

安装

brew install rust

验证

rustc --version
cargo --version

创建测试项目

cargo new hello-rust
cd hello-rust
cargo run

说明

• 如果只是使用稳定版 Rust，通过 Homebrew 管理即可。
• 如果后续需要多版本 Rust、nightly 工具链或交叉编译目标，再考虑使用 rustup。
• 不建议同时混用 Homebrew Rust 和 rustup Rust，除非明确知道当前项目使用的是哪套工具链。

3.12 Node.js 与 npm 环境

npm 随 Node.js 一起安装。通过 Homebrew 安装 Node.js 后，会同时获得 node、npm 和 npx。

安装

brew install node

验证

node --version
npm --version
npx --version

项目依赖管理

进入项目目录后，使用项目级依赖管理：

npm init
npm install <package>
npm run <script>

如果需要使用 pnpm 或 Yarn，可以启用 Corepack：

corepack enable

说明

• 项目依赖应写入项目自己的 package.json。
• 能用 Homebrew 安装的全局 CLI 工具，优先用 Homebrew 安装。
• 只有确实属于 npm 生态的全局工具，才使用 npm install -g。

3.13 Go 开发环境

Go 语言工具链通过 Homebrew 安装。Homebrew 的 go 包会提供 go 命令、标准库、编译器和常用工具。

官方入口

• 官方网站：Go
• 官方下载页：Go Downloads
• Homebrew 安装命令：brew install go

安装

brew install go

配置 Go 环境变量

Go 1.11 之后默认启用 Go Modules。普通项目一般不需要手动设置 GOPATH，但可以为 Go 安装的命令行工具配置 GOBIN，让 go install 安装的可执行文件能被终端直接找到。

mkdir -p "$HOME/go/bin"

cat <<'EOF' >> ~/.zprofile
# Go
export GOPATH="$HOME/go"
export GOBIN="$GOPATH/bin"
export PATH="$GOBIN:$PATH"
EOF

source ~/.zprofile

验证

go version
go env GOPATH
go env GOROOT
go env GOBIN

创建测试项目

mkdir -p ~/Projects/go/hello-go
cd ~/Projects/go/hello-go
go mod init example.com/hello-go

创建 main.go：

package main

import "fmt"

func main() {
	fmt.Println("Hello, Go")
}

运行：

go run .

构建：

go build -o hello-go
./hello-go

常用命令

go fmt ./...
go test ./...
go mod tidy
go env

VS Code 插件

如果使用 VS Code 开发 Go，安装官方 Go 插件：

code --install-extension golang.go

首次打开 Go 项目时，VS Code 的 Go 插件通常会提示安装 gopls、dlv 等辅助工具，按提示安装即可。

说明

• 新项目优先使用 Go Modules，不再依赖传统 GOPATH 项目结构。
• 第三方命令行工具建议使用 go install package@version 安装到 $GOBIN。
• 如果项目需要固定 Go 版本，应以项目的 go.mod 为准。

3.14 Java 开发环境

Java 开发环境主要包括 JDK、构建工具和编辑器插件。JDK 通过 Homebrew 安装 OpenJDK；常用构建工具包括 Maven 和 Gradle。

官方入口

• OpenJDK：OpenJDK
• Maven：Apache Maven
• Gradle：Gradle

安装当前版 OpenJDK

如果没有固定版本要求，可以安装 Homebrew 当前默认的 OpenJDK：

brew install openjdk

Homebrew 的 openjdk 是 keg-only，不会自动链接到系统默认 Java 路径。需要手动配置 JAVA_HOME 和 PATH：

cat <<'EOF' >> ~/.zprofile
# Java
export JAVA_HOME="$(brew --prefix openjdk)"
export PATH="$JAVA_HOME/bin:$PATH"
EOF

source ~/.zprofile

如果希望 macOS 的系统 Java wrapper 也能找到该 JDK，可以创建系统级链接：

sudo ln -sfn "$(brew --prefix openjdk)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk.jdk

安装 LTS 版 OpenJDK

如果项目要求长期支持版本，优先选择 LTS 版本，例如 Java 21：

brew install openjdk@21

配置 Java 21：

cat <<'EOF' >> ~/.zprofile
# Java 21
export JAVA_HOME="$(brew --prefix openjdk@21)"
export PATH="$JAVA_HOME/bin:$PATH"
EOF

source ~/.zprofile

创建系统级链接：

sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-21.jdk

如果项目仍要求 Java 17，也可以安装：

brew install openjdk@17

安装 Maven 和 Gradle

brew install maven gradle

验证

java --version
javac --version
echo "$JAVA_HOME"
mvn --version
gradle --version

查看 macOS 识别到的 JDK：

/usr/libexec/java_home -V

创建 Java 测试项目

创建简单 Java 文件：

mkdir -p ~/Projects/java/hello-java
cd ~/Projects/java/hello-java

创建 Hello.java：

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, Java");
    }
}

编译并运行：

javac Hello.java
java Hello

创建 Maven 项目

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=hello-maven \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

进入项目并测试：

cd hello-maven
mvn test

VS Code 插件

如果使用 VS Code 开发 Java，建议安装 Java 扩展包：

code --install-extension vscjava.vscode-java-pack

如果使用 Spring Boot，可以额外安装：

code --install-extension vmware.vscode-spring-boot

多版本 Java 管理建议

• 普通新项目优先使用当前 LTS 版，例如 Java 21。
• 老项目按项目要求安装 Java 17 或更旧版本。
• 多个 Java 版本并存时，不要频繁覆盖系统级 symlink；优先在 shell 中通过 JAVA_HOME 切换。
• 如果经常切换 Java 版本，可以后续单独引入 jenv 进行版本管理。

3.15 开发环境统一验证

完成以上安装后，可以一次性检查主要工具是否可用：

brew --version
git --version
vim --version
tmux -V
clang --version
cmake --version
python3 --version
conda --version
rustc --version
cargo --version
node --version
npm --version
go version
java --version
javac --version
mvn --version
gradle --version

3.16 环境维护与迁移

日常更新

brew update
brew upgrade
brew cleanup
brew doctor

导出 Homebrew 软件清单

在旧电脑或当前电脑上导出 Brewfile：

brew bundle dump --file ~/Brewfile --force

在新电脑恢复 Homebrew 软件

把 Brewfile 放到新电脑后执行：

brew bundle --file ~/Brewfile

这样可以快速恢复通过 Homebrew 管理的软件和开发工具。

第四部分：AI 辅助工具安装与配置

本部分用于配置新 MacBook 上常用的 AI 编程辅助工具，包括 OpenAI Codex、Claude Code、CC Switch、Cursor、Superset 和 Paseo。

整体原则：

• 图形界面 App 优先通过 Homebrew Cask 安装，便于统一升级和迁移。
• CLI 工具优先使用官方推荐安装方式；如果 Homebrew Cask 可用，则优先使用 Homebrew。
• 登录凭据、API Key、访问令牌等敏感信息只保存在官方客户端、系统钥匙串或工具自己的配置目录中，不写入项目仓库。
• 每个工具安装后都执行版本检查和最小可用性测试。

4.1 AI 工具清单

工具	类型	官方入口	推荐安装方式
Codex CLI	命令行 AI 编程代理	Codex CLI	brew install --cask codex 或官方安装脚本
Codex App	OpenAI Codex 桌面端	Codex App	brew install --cask codex-app
Codex IDE Extension	VS Code / Cursor 扩展	Codex IDE Extension	在编辑器扩展市场安装 Codex
Claude Desktop / Claude Code GUI	Claude 桌面端与 Code 图形界面	Claude Code Desktop	brew install --cask claude
Claude Code CLI	命令行 AI 编程代理	Claude Code Setup	brew install --cask claude-code
Claude Code IDE Extension	VS Code / Cursor 扩展	Claude Code in VS Code	在编辑器扩展市场安装 Claude Code
CC Switch	AI CLI 配置管理器	CC Switch	brew install --cask cc-switch
Cursor	AI 代码编辑器	Cursor Download	brew install --cask cursor
Cursor Agent CLI	Cursor 命令行代理	Cursor CLI	官方安装脚本
Superset	多 AI 编码代理工作区与桌面 IDE	Superset	从官方 GitHub Releases 下载 macOS 桌面版；CLI 可随 App 使用或通过 Homebrew 安装
Paseo	自托管的多 AI 编码代理编排器	Paseo	brew install --cask paseo，或从官方下载页选择对应芯片版本

4.2 OpenAI Codex

Codex 可以通过 CLI、桌面 App、IDE 扩展和 Web/Cloud 使用。CLI、桌面 App 和 IDE 扩展使用同一套 Codex agent 和本地配置。

安装 Codex CLI

方式一：通过 Homebrew Cask 安装，便于统一管理：

brew install --cask codex

方式二：使用 OpenAI 官方 standalone 安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

无人值守安装可使用：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

验证 Codex CLI

codex --version
codex doctor

启动交互式终端界面：

codex

带初始提示启动：

codex "解释当前项目结构"

登录 Codex

Codex 支持两种登录方式：

• 使用 ChatGPT 账号登录，适合订阅额度和 Codex Cloud 工作流。
• 使用 OpenAI API Key 登录，适合按 API 计费的本地或自动化工作流。

首次运行 codex 时会提示登录。也可以手动执行：

codex login

如果使用 API Key，需要先在 OpenAI 平台创建 API Key：

• OpenAI API Keys

Codex CLI 常用配置

Codex 的用户配置文件位于：

~/.codex/config.toml

建议优先使用系统钥匙串保存登录凭据：

cli_auth_credentials_store = "keyring"

常用启动方式：

codex --sandbox workspace-write --ask-for-approval on-request
codex --model gpt-5.5
codex exec "检查当前项目是否有明显 bug"
codex resume

配置 Shell 补全

如果使用 zsh，可以在 ~/.zshrc 中加入：

eval "$(codex completion zsh)"

然后重新打开终端，输入 codex 后按 Tab 测试补全。

安装 Codex 桌面 App

通过 Homebrew Cask 安装：

brew install --cask codex-app

也可以从官方 Codex App 页面下载 macOS 安装包，并根据 Mac 芯片选择 Apple Silicon 或 Intel 版本。

安装后打开 Codex App，完成以下步骤：

1. 使用 ChatGPT 账号或 OpenAI API Key 登录。
2. 选择一个项目文件夹。
3. 确认选择 Local，让 Codex 在本机项目中工作。
4. 发送第一条任务，例如“解释这个项目的目录结构”。

如果已经安装 Codex CLI，也可以从终端打开桌面 App：

codex app .

安装 Codex IDE 扩展

Codex IDE 扩展支持 VS Code、Cursor、Windsurf 等 VS Code 兼容编辑器。

安装步骤：

1. 打开 VS Code 或 Cursor。
2. 打开扩展面板。
3. 搜索 Codex。
4. 安装 OpenAI Codex 扩展。
5. 重启编辑器。
6. 在侧边栏打开 Codex，并使用 ChatGPT 账号或 API Key 登录。

在 Cursor 中，如果 Codex 没有出现在期望的右侧边栏，可以手动拖动 Codex 图标到右侧边栏。

4.3 Claude Code

Claude Code 可以通过桌面 GUI、IDE 扩展和 CLI 使用。桌面 App 的 Code 标签页提供图形界面；CLI 则适合终端和脚本化工作流。

安装 Claude Desktop / Claude Code GUI

通过 Homebrew Cask 安装 Claude 桌面端：

brew install --cask claude

也可以从 Claude 官方下载页下载安装：

• Claude Download

安装后：

1. 从“应用程序”打开 Claude。
2. 登录 Anthropic 账号。
3. 打开顶部的 Code 标签页。
4. 如果提示升级，需要使用支持 Claude Code 的 Pro、Max、Team 或 Enterprise 订阅。
5. 选择 Local，并选择项目目录。
6. 发送第一条任务。

说明：

• Claude 桌面 App 内置 Claude Code 图形界面，不需要为了使用 GUI 单独安装 Node.js 或 CLI。
• 如果需要在终端中运行 claude 命令，需要另外安装 Claude Code CLI。

安装 Claude Code CLI

方式一：通过 Homebrew Cask 安装稳定通道：

brew install --cask claude-code

如果明确想使用最新通道：

brew install --cask claude-code@latest

方式二：使用 Anthropic 官方安装脚本：

curl -fsSL https://claude.ai/install.sh | bash

方式三：通过 npm 安装：

npm install -g @anthropic-ai/claude-code

注意：不要使用 sudo npm install -g 安装 Claude Code，避免权限和安全问题。

验证 Claude Code CLI

claude --version
claude doctor

启动 Claude Code：

claude

首次启动时，按照浏览器提示登录 Anthropic 账号。Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账号；免费 Claude.ai 账号不包含 Claude Code 访问权限。

Claude Code 常用配置

Claude Code 的用户配置目录通常位于：

~/.claude/

用户设置文件：

~/.claude/settings.json

项目级配置通常位于项目目录：

.claude/

如果希望稳定使用 Homebrew 的 stable 通道，可以安装 claude-code；如果希望更快获得新功能，才选择 claude-code@latest。

Homebrew 安装不会默认自动更新，需要手动升级：

brew upgrade --cask claude-code

如果安装的是最新通道：

brew upgrade --cask claude-code@latest

安装 Claude Code IDE 扩展

Claude Code 官方 IDE 扩展支持 VS Code 和 Cursor。

安装步骤：

1. 打开 VS Code 或 Cursor。
2. 打开扩展面板。
3. 搜索 Claude Code。
4. 安装 Anthropic Claude Code 扩展。
5. 重启编辑器。
6. 打开 Claude Code 面板并登录 Anthropic 账号。

扩展常用入口：

• 点击编辑器中的 Spark 图标。
• 使用命令面板，搜索 Claude Code。
• 在状态栏点击 Claude Code。

如果更喜欢终端式体验，可以在扩展设置中开启 Use Terminal，让 Claude Code 使用终端模式。

4.4 CC Switch

CC Switch 是一个跨平台的 AI 编程工具配置管理器，用于管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode 等工具的 Provider、MCP、Prompts 和 Skills 配置。

安装 CC Switch

通过 Homebrew Cask 安装：

brew install --cask cc-switch

手动下载入口：

• CC Switch GitHub Releases

首次配置

1. 打开 CC Switch。
2. 首次启动时，优先选择导入现有 CLI 工具配置。
3. 添加 Provider：选择官方登录、官方 API、第三方 API 网关或本地模型等配置类型。
4. 选择目标工具，例如 Claude Code、Codex 或 Gemini CLI。
5. 点击 Enable 或从菜单栏托盘切换 Provider。
6. 切换后重启对应 CLI 或终端，让工具重新读取配置。

说明：

• CC Switch 不直接替代 Codex 或 Claude Code，它主要管理这些工具的配置。
• 切换 Provider 之前，建议先确认对应 API Key、Base URL 或官方登录方式本身可用。
• 第一次使用时优先“导入现有配置”，避免新建空 Provider 后误以为原有 MCP、Skills 或登录配置丢失。
• 配置管理类工具会接触敏感凭据，应只从官方仓库、官方发布页或 Homebrew 安装。

CC Switch 数据位置

常见本地数据目录：

~/.cc-switch/

其中通常包括数据库、设置、备份和 Skills 相关文件。卸载 App 前，如果希望保留 Provider 和 MCP 配置，应先备份该目录。

4.5 Cursor

Cursor 是基于 VS Code 体验的 AI 代码编辑器，适合与 VS Code 并行使用，也可以作为主要代码编辑器。

安装 Cursor 桌面端

通过 Homebrew Cask 安装：

brew install --cask cursor

也可以从官方页面下载：

• Cursor Download

macOS 下载时可根据机器选择：

• Apple Silicon：Mac ARM64
• Intel Mac：Mac x64
• 不确定芯片类型：Mac Universal

Cursor 首次配置

1. 打开 Cursor。
2. 登录 Cursor 账号。
3. 选择键盘快捷键方案。
4. 选择主题。
5. 配置终端偏好。
6. 如果从 VS Code 迁移，可以导入 VS Code 设置。
7. 打开项目目录，等待 Cursor 完成代码索引。

安装 Cursor Shell 命令

在 Cursor 中打开命令面板：

Command Palette -> Install 'cursor' command in PATH

安装后可在终端中打开文件或目录：

cursor .
cursor path/to/file.md

如果还需要 VS Code 兼容的 code 命令，也可以在命令面板执行：

Install 'code' command in PATH

安装 Cursor Agent CLI

Cursor Agent CLI 用于在终端中运行 Cursor 的 agent。

安装命令：

curl https://cursor.com/install -fsS | bash

如果安装脚本提示需要配置 PATH，可将 ~/.local/bin 加入 zsh：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证：

cursor-agent --version
cursor-agent

手动更新：

cursor-agent update

或：

cursor-agent upgrade

4.6 Superset

Superset 是面向 AI 编码代理的本地优先开发平台，提供桌面 IDE、CLI 和 MCP Server。它会基于 Git worktree 为不同分支创建相互隔离的工作区，便于同时运行 Codex、Claude Code、Cursor Agent 等 CLI 编码代理，并在同一个界面中查看终端、代码差异和运行中的开发服务。

注意：这里介绍的是 superset.sh 的 AI 编码工具，不是 Apache Superset 数据可视化平台。

安装前准备

Superset 桌面版支持 Apple Silicon 和 Intel Mac。安装前应先完成本指南第三部分中的 Git 与 GitHub CLI 配置，并确认：

git --version
gh --version
gh auth status

如果 GitHub CLI 尚未登录，执行：

gh auth login

安装 Superset 桌面版

推荐安装桌面版，以便使用完整的工作区、终端、代码差异查看器和内置浏览器功能：

1. 打开 Superset 官方网站 或 Superset 最新发布页。
2. 根据 Mac 芯片下载对应的 .dmg 安装包：
   • Apple Silicon：选择文件名包含 arm64 的版本。
   • Intel：选择文件名包含 x64 或不包含 arm64 的 Intel 版本。
3. 打开 .dmg，将 Superset 拖入“应用程序”文件夹。
4. 从“应用程序”打开 Superset，并按提示完成账号登录。

Superset 桌面版自带 superset CLI。App 启动后会在以下位置创建 CLI shim：

~/.superset/bin/superset

Superset 内置终端会自动配置该路径。如果希望在系统 Terminal、iTerm2 等普通终端中使用随 App 提供的 CLI，可将以下内容加入 ~/.zshrc：

export PATH="$HOME/.superset/bin:$PATH"

然后重新加载配置：

source ~/.zshrc

可选：独立安装 Superset CLI

如果只需要命令行功能，也可以通过 Homebrew 安装独立 CLI：

brew install superset-sh/tap/superset

也可以使用官方安装脚本：

curl -fsSL https://superset.sh/cli/install.sh | sh

桌面 App 自带 CLI、Homebrew 和官方脚本三种方式选择一种即可，避免 PATH 中同时存在多个版本。CLI 目前处于 Beta 阶段，命令和参数可能继续调整，遇到问题时应先升级并查阅 Superset CLI 文档。

登录并验证 Superset CLI

检查 CLI 是否可用：

superset --version

登录 Superset：

superset auth login

浏览器完成授权后，验证当前账号和组织：

superset auth whoami

登录信息保存在 Superset 自己的用户配置目录中。不要把 ~/.superset/、API Key、登录令牌或其他凭据复制到项目仓库。

创建第一个工作区

1. 在 Superset 中选择本地 Git 仓库，或通过 Git URL 添加仓库。
2. 基于主分支创建一个新的 workspace 和独立分支。
3. 在工作区终端中启动 Codex、Claude Code 或其他已安装的 CLI 编码代理。
4. 使用 Changes 面板检查代理生成的代码差异，再决定是否提交或合并。
5. 需要在 VS Code 或 Cursor 中继续编辑时，按 Command + O 打开当前工作区。

使用时注意：

• 一个 workspace 对应一个 Git worktree 和一个分支，同一分支不能同时用于多个 workspace。
• Superset 创建工作区时只复制 Git 已跟踪文件；未跟踪的 .env、本地依赖和构建产物不会自动复制。
• 可以通过项目中的 .superset/config.json 配置 setup、teardown 和 run 脚本，但不得在脚本或配置文件中硬编码密码、API Key 或访问令牌。
• 需要传递 .env 等本地配置时，应使用不进入版本控制的安全方式，并确认 .gitignore 已正确配置。

官方参考：

• Superset 官方网站
• Superset 文档
• 创建第一个工作区
• AI Agents

4.7 Paseo

Paseo 是一个免费、开源、自托管的 AI 编码代理编排器。它在本机运行 daemon，并通过桌面 App、CLI、网页端或移动端连接 Claude Code、Codex、GitHub Copilot、OpenCode、Pi 等代理。代理会继续使用各自已安装并完成认证的本地 CLI，Paseo 不代替模型订阅，也不接管这些代理的登录凭据。

Paseo 适合以下场景：

• 在统一界面中启动、查看和跟进多个编码代理。
• 离开电脑后，从手机查看任务进度、发送后续指令或审阅代码差异。
• 使用 Git worktree 隔离并行任务，避免多个代理互相覆盖工作目录。
• 通过 CLI 编排代理、执行循环任务或设置定时任务。

安装前准备

Homebrew Cask 要求 macOS 12 或更高版本。Paseo 本身不包含 AI 编码代理，使用前至少安装并登录一个受支持的代理 CLI，例如本指南前面介绍的 Codex CLI 或 Claude Code CLI：

codex --version
claude --version

Git 不是运行 Paseo 的硬性要求；如果需要 worktree、Pull Request 感知等 Git 工作流，建议同时确认 GitHub CLI 已登录：

git --version
gh --version
gh auth status

安装 Paseo 桌面版

推荐通过 Homebrew Cask 安装，Homebrew 会同时安装 Paseo.app 并将随 App 提供的 paseo 命令加入 PATH：

brew install --cask paseo

也可以打开 Paseo 下载页 或 GitHub Releases，根据 Mac 芯片选择安装包：

• Apple Silicon：选择 arm64.dmg。
• Intel：选择 x64.dmg。

打开 .dmg 后，将 Paseo 拖入“应用程序”文件夹。桌面 App 自带 daemon，启动 App 后无需另外安装服务端。

可选：只安装 CLI 与 daemon

如果要在无图形界面的开发机、Mac mini 或服务器上运行 Paseo，可以使用 npm 安装 CLI：

npm install -g @getpaseo/cli
paseo

首次启动会在终端显示二维码，可使用 Paseo 移动端扫描配对。配置和本地状态默认保存在：

~/.paseo/

桌面版和 npm CLI 根据需要选择即可；不要为了同一用途重复安装多个来源，以免 PATH 中出现版本冲突。

首次配置与移动端配对

1. 打开 Paseo，确认本机 daemon 正常启动。
2. 添加一个本地项目目录。
3. 选择已安装并完成登录的 Codex、Claude Code 或其他 Provider。
4. 发送一个最小任务，确认代理能够启动并返回结果。
5. 如需手机控制，在桌面端打开 Settings -> 当前主机 -> Connections -> Pair a device，再使用 iOS 或 Android 版 Paseo 扫描二维码。

Paseo 也支持 Web App。二维码或配对链接是连接本机 daemon 的信任凭据，应像密码一样保管，不要上传到仓库、公开聊天或截图分享。

验证 CLI 和 daemon

通过 Homebrew Cask 或 npm 安装后，可执行：

paseo --version
paseo daemon status
paseo ls

启动一个 Codex 任务的示例：

paseo run --provider codex "解释当前项目结构"

常用管理命令：

paseo ls
paseo attach <agent-id>
paseo send <agent-id> "继续运行测试"
paseo logs <agent-id>
paseo stop <agent-id>

远程连接安全建议

• daemon 默认监听 127.0.0.1:6767，只供本机连接时应保留该默认设置。
• 从手机远程访问时，优先使用 Paseo 的端到端加密 relay，或使用 Tailscale 等私有网络。
• 不要在没有密码和防火墙保护的情况下监听 0.0.0.0，否则同一网络中的其他设备可能控制本机代理。
• 如果必须监听局域网地址，先运行 paseo daemon set-password，并避免把密码写入 Shell 历史、项目文件或 Git 仓库。
• ~/.paseo/ 可能包含 daemon 状态、配对信息和日志，不应提交到版本控制。

官方参考：

• Paseo 官方网站
• Paseo 入门文档
• Paseo CLI 文档
• Paseo 安全文档
• Paseo GitHub 仓库

4.8 AI 工具统一验证

完成安装后，可以统一检查：

codex --version
codex doctor
claude --version
claude doctor
cursor --version
cursor-agent --version
superset --version
superset auth whoami
paseo --version
paseo daemon status

需要图形界面确认的 App：

• Codex.app
• Claude.app
• Cursor.app
• CC Switch.app
• Superset.app
• Paseo.app

4.9 更新与维护

通过 Homebrew 安装的 AI 工具可以统一更新：

brew update
brew upgrade --cask codex
brew upgrade --cask codex-app
brew upgrade --cask claude
brew upgrade --cask claude-code
brew upgrade --cask cc-switch
brew upgrade --cask cursor
brew upgrade --cask paseo
brew upgrade superset-sh/tap/superset
brew cleanup

上面的 Superset Homebrew 命令只更新独立安装的 CLI。Superset 桌面版应使用 App 内置更新功能，或从 Superset 最新发布页 下载新版覆盖安装。

如果 Codex CLI 使用官方安装脚本安装，升级时重新运行：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

如果 Claude Code CLI 使用 npm 安装，升级时运行：

npm install -g @anthropic-ai/claude-code@latest

如果 Cursor Agent CLI 使用官方安装脚本安装，升级时运行：

cursor-agent update

如果 Paseo CLI 是通过 npm 单独安装，升级时运行：

npm install -g @getpaseo/cli@latest