# macOS 0.2.1 安装方式

0.2.1 下载改用 macOS 系统 `/usr/bin/curl`，保持证书校验，避免依赖 Python 自带的独立证书链。原 `URLError` 的具体根因尚未取得 Mac 实机证据，不能仅凭错误名称判定已确诊。

失败信息现在包含阶段：`channel`、`manifest`、`wheel`、`usage-guides`、`dependencies-pypi`、`mcp-offline-doctor` 或配置阶段。curl 6为DNS、7为连接、22为HTTP错误、28为超时、35为TLS握手、60为证书校验。依赖安装失败应检查 Python 证书与 PyPI 连通性，不使用关闭TLS校验的办法。不会打印服务器响应或代理凭据。

`compdef` 错误来自 zsh/OpenClaw 补全初始化，应单独处理。本安装器不会更改 OpenClaw 或 shell 启动文件。

引导 skill 经哈希验证后放在安装目录 `current/guidance/8xai-design-guide`；支持 skill 的客户端可导入整个文件夹，其余客户端使用内置 `usage_guide` / `intent_guide`。升级省略素材、数据和客户端选项时保留上次设置。下面命令使用子 shell 和退出清理，安装失败不会被最后的删除命令掩盖退出码。

Apple Silicon 与 Intel 均使用平台无关 wheel，在当前用户目录建立独立虚拟环境；需要先安装 python.org 的 Python 3.11 或以上版本，并能访问下载站、PyPI 和 8XAI API。无需 Windows exe、管理员权限或 Docker。

以下命令需在服务商部署 **0.2.1 新包之后**执行；当前本地完成封版不等于公网下载站已经更新：

```bash
(u='https://plugin.8xai.cn'; p=$(mktemp) || exit; trap 'rm -f "$p"' EXIT; /usr/bin/curl -q -fsSL --connect-timeout 20 --max-time 180 --proto '=https' --proto-redir '=https' "$u/install.sh" -o "$p" && bash "$p" "$u" --clients all)
```

退出客户端后安装，完成再重启。默认安装到 `~/Library/Application Support/8XAI-MCP`，素材目录 `~/Pictures/8XAI/素材`，数据目录 `~/.8xai-mcp`。可追加 `--asset-root '/绝对路径/素材'`、`--data-root '/绝对路径/数据'`。`XAI_PYTHON` 可指定 Python 解释器路径。

- Claude Desktop：`~/Library/Application Support/Claude/claude_desktop_config.json`。
- Codex：`$CODEX_HOME/config.toml` 或 `~/.codex/config.toml`；启动超时60秒、工具超时900秒。
- Cursor：`~/.cursor/mcp.json`。
- Cherry Studio：在 MCP 设置中导入安装目录 `client-configs/cherry.json`，再给助手启用。
- 其他本地 stdio 客户端：参考 `client-configs/mcp.json`。仅提供远程 MCP URL 的应用暂不适用。

安装器验证 channel→manifest→wheel 的 SHA256 与字节数，HTTPS 跳转也限制为 HTTPS。依赖通过 PyPI 安装，仅应用 wheel 是本包固定的不可变产物；不是包含全部依赖的离线安装包。安装失败保留原配置、当前版本和用户数据，重复安装创建新的版本目录并切换稳定入口；配置只修改本服务，先备份，无效配置或同名非管理条目会阻断。

首次登录后，令牌和选择记住的密码写入系统登录钥匙串；磁盘 `credentials.json` 只保存保护方式标记。钥匙串锁定或拒绝访问时明确失败，不降级成明文保存；系统可能提示钥匙串授权。可在终端运行当前版本的 `bin/8xai-auth-login` 隐藏输入密码，避免把密码发进聊天。聊天和工具调用记录由客户端管理，钥匙串不清除聊天记录。

重新下载脚本后，支持 `--action doctor`、`--action rollback`、`--action uninstall --clients all`。doctor 只在临时目录验证 MCP 初始化、工具列表与本地预演，新增分析／生成0次。rollback 切回本机保留的上一版。uninstall 只移除接入，保留版本、备份、图片和账号数据；需要退出登录先调用 `auth_logout` 删除钥匙串对应项。

验收边界：Windows 环境已验证配置合并、哈希拒绝、钥匙串成功/拒绝的模拟契约和实际 MCP 离线自检；没有 Mac 实机，因此不声称 macOS 原生安装、钥匙串弹窗、Apple Silicon/Intel 依赖安装和各客户端界面已经实测。未提供签名/公证的原生 Mach-O 独立应用。wheel 含可读 Python 源码，不能用于隐藏商业算法。

本轮核对官方依据：Claude 本地配置路径与 Codex 配置/超时字段来自各自官方文档；应用界面验收另计。2026-11-09 网页读取代理拒绝匿名访问后，直接从官方站点只读获取并内部留存。

- https://modelcontextprotocol.io/docs/develop/connect-local-servers
- https://developers.openai.com/codex/mcp