在 Mac 上使用 Claude Code，安装 VS Code 扩展只是第一步。账户额度、API 令牌、CCSwitch 渠道、扩展登录状态、工作区信任和 macOS 文件权限分别属于不同环节。把这些环节混在一起，最常见的结果就是聊天能回复但工具不能用，或者 CCSwitch 已切换而扩展仍要求旧账号登录。
**一、准备一个干净的测试环境。**先安装或更新 VS Code，打开一个新建的普通文件夹，不要直接进入包含客户代码、生产密钥和大量自动化脚本的仓库。确认 VS Code 的集成终端可以正常启动，再从扩展市场核对 Claude Code 扩展的名称与发布者，避免安装名称相似的非官方扩展。
服务账户方面，先完成邮箱验证，查看套餐、余额和可用模型，再到密钥管理页面单独创建测试令牌。令牌名称可以写成 mac-claude-vscode-test，并限制额度或有效期。登录密码、邀请码和订单编号都不能代替 API Key；页面若只展示一次令牌，应立即放入安全凭据工具，而不是普通备忘录。
**二、安装 CCSwitch 并确认运行身份。**将适合当前芯片的版本放入"应用程序"，首次打开时根据系统提示确认来源。进入设置记录数据目录和版本号。不要一会儿用普通用户运行、一会儿又使用管理员方式运行，否则渠道可能保存在不同目录，后面很难判断 Claude Code 实际读取哪一份配置。
**三、新建 Claude Code 渠道。**填写容易辨认的渠道名称、服务方提供的 Base URL、刚创建的 API Key 和正确模型 ID，目标应用选择 Claude Code。若文档说明使用 Anthropic 风格认证，就按对应模板配置，不能把给 Codex 使用的 OpenAI 兼容字段原样复制过来。
密钥字段通常只需要令牌本体。如果把"Bearer "前缀一起放进本来会自动添加认证头的字段，最终请求可能出现重复前缀；反过来，模板要求完整 Authorization 值时又不能缺失。遇到 401 时应先确认渠道模板和服务方说明一致，而不是立刻更换模型。
**四、让新配置真正生效。**保存渠道后执行切换，关闭全部 VS Code 窗口、终端和旧 Claude Code 会话，再重新打开测试文件夹。扩展的旧登录状态或终端环境变量可能比新配置更早被读取。若界面仍显示旧账户，先查看当前认证来源，再决定退出登录或清理旧变量。
**五、按权限递进测试。**第一步只让 Claude Code 解释一个测试文件；第二步让它提出修改方案但不写入；第三步查看 diff 后允许它创建一个无敏感信息的小文件。这样可以分别验证对话、读取、审批和写入。聊天正常但写入失败，多半属于工作区信任、文件权限或 Claude Code 的权限规则。
macOS 可能限制 VS Code 访问"桌面""文稿"或外接磁盘。遇到文件不可见时，先把测试项目放在用户目录下的普通开发文件夹，再检查系统设置。不要为了修复一个目录问题就开放完整磁盘访问，更不要启用跳过所有权限的模式来处理来源不明的仓库。
如果需要对照注册、创建令牌、填写渠道和切换客户端的完整步骤，可以查看 CCSwitch 快速接入教程。文档教程：https://my.feishu.cn/wiki/Qv2GwNLuIiCAVqkRFfoc5kZ4njc
验证扩展是否读取新渠道时，可以观察服务控制台的用量时间，而不要依赖回答风格。发送一条短问题后刷新用量记录，确认请求落到新令牌。若 CCSwitch 已切换但新令牌没有流量，说明请求仍由旧登录、旧变量或另一配置来源处理。
VS Code 工作区设置也值得检查。某些项目会保存扩展启用状态、终端环境和任务配置，导致同一台 Mac 在空目录可用、进入特定仓库就异常。先比较空目录和目标项目，再审查项目设置；不要删除整个用户配置来修一个仓库的局部问题。
首次允许写入前，先阅读 Claude Code 给出的计划和目标文件。它准备修改依赖锁文件、构建产物或工作区外路径时，应暂停并缩小任务。教程的目标不是让每次确认都消失，而是让确认出现在真正需要判断的动作之前。
扩展升级后若出现登录循环，记录升级前后版本，先退出会话再重启 VS Code，并在测试目录验证。不要同时降级扩展、换 API Key、改 Base URL 和清缓存。只改一个条件，才能判断是扩展状态、认证来源还是网关兼容性发生变化。
团队使用时，项目共享文档只写渠道命名、模型选择和排错流程，个人令牌保存在各自凭据系统。Mac 被送修、转交或远程协助前，撤销测试令牌并退出账户。完成后重新创建令牌，比试图确认维修过程是否看过旧密钥更可靠。
常见错误可以按层判断：401 看密钥、认证头和账户授权；404 看地址与模型；429 看额度和调用频率；timeout 看代理、DNS 和证书；对话可用但工具不可用，则看权限和网关的工具兼容性。每次修改后都从新会话开始，避免缓存干扰判断。
正式接入真实项目之前，给 Codex、Claude Code 和自动化脚本分别创建令牌，不要共用一枚长期密钥。渠道名称加入项目和环境，截图时遮住邮箱、余额与令牌。Mac 丢失、成员离职或密钥进入公开记录时，应立即撤销对应令牌，而不是只删除 CCSwitch 中的渠道。
一套可靠的验收结果应包括：账户可用、渠道能保存、切换后扩展读取新配置、短对话能返回、测试目录可读、写入需要预期中的确认，并且日志里没有暴露密钥。达到这些条件后，再逐步增加 MCP、Hooks 或更大的项目任务，排错会轻松得多。