LLM 大模型邮报

Hermes Agent 安装最简流程：Linux、macOS、WSL2 与 Termux 四端一次说清

MISTY — Fri, 01 May 2026 16:44:52 +0000

Hermes Agent 是 Nous Research 推出的开源自学习个人 AI agent，GitHub 收获 118k+ stars，由 Hermes-3 模型团队同源开发。与 Claude Code、Codex、OpenCode 等编码专用工具不同，Hermes Agent 定位为”会成长的个人 agent”——它通过闭环学习循环自动从经验中创建可复用的技能（Skills），跨会话记忆用户偏好，通过 Telegram、Discord、Slack、WhatsApp、Signal 等多个通讯平台接入用户日常生活，并支持自然语言定时任务（cron）。

Hermes Agent 安装的最大特点是仅通过单一 install.sh 脚本分发——没有 npm、Homebrew、winget 包，所有平台共用同一条命令。支持 Linux、macOS、WSL2 与 Android Termux，不支持原生 Windows。本指南整理四端在不同设备上的最简安装流程，覆盖 Docker、SSH、Modal、Daytona 等六种执行后端的配置策略，以及从 OpenClaw 迁移的完整路径。

Hermes Agent 是什么：与编码 agent 的根本差异

理解 Hermes Agent 安装路径的设计选择，需要先搞清楚它的产品定位。Hermes 不是 Claude Code、Codex、OpenCode 那种”在终端里帮你写代码的 agent”，而是更接近”个人 AI 管家”——它的设计目标是持久运行、跨会话学习、跨平台触达：

自学习闭环：完成复杂任务后自动生成 Markdown 格式的 Skill 文档存入技能库，下次遇到类似任务先搜索已有技能而非从零推导。据 TokenMix.ai 的评测，积累 20+ 自创技能后，相似任务完成时间约缩短 40%
跨平台 gateway：通过单一 gateway 进程接入 Telegram、Discord、Slack、WhatsApp、Signal、Email 与 CLI，从手机给云端 VPS 上的 Hermes 发消息也能完成任务
三层持久记忆：FTS5 全文搜索 + LLM 摘要的会话历史检索、Honcho 用户建模、agentskills.io 标准的技能持久化
自然语言 cron：内置定时调度器，支持”每天早 8 点把昨日 GitHub 通知发到 Telegram”这类自然语言任务
六种 terminal backend：本地、Docker、SSH、Daytona、Singularity、Modal——agent 实际执行命令的环境与 Hermes 本体可分离

什么场景适合 Hermes：希望 7×24 运行在 VPS 或 home lab 上的个人 agent、需要从 Telegram 远程指挥的工作流、有跨会话用户记忆需求的研究工作、想要从 OpenClaw 迁移并保留所有技能与 API Key。

什么场景不适合：纯命令行编码、不想维护 Linux/Mac 环境的 Windows 原生用户、不希望 agent 自动生成”持久状态”的临时使用场景。

系统要求与前置检查

根据 Hermes Agent 官方文档：

操作系统：Linux、macOS、WSL2 或 Android（通过 Termux）
不支持原生 Windows：官方明确说明 Hermes 不支持 Windows 原生路径，Windows 用户必须先安装 WSL2
Python：要求 Python 3.11，由安装脚本通过 uv 自动管理，无需手动安装
Node.js：v22，由安装脚本自动安装（用于 WhatsApp bridge 与浏览器自动化）
Git：唯一需要预先安装的依赖
硬件：2 GB RAM 起步，本地跑模型时需更多。运行 Hermes 本体仅 ~1 GB 磁盘
账号：Hermes 本体免费开源（MIT 协议），使用成本取决于模型 provider——可使用 Nous Portal、OpenRouter、NVIDIA NIM、智谱 GLM、Kimi、MiniMax、本地 Ollama 或 OpenAI/Anthropic 等任意 provider
网络：托管模型 API 需稳定网络。本地模型通过 OpenAI 兼容端点可离线运行

检查当前是否已安装：

hermes --version

如果返回版本号（当前最新版 v0.11.0，发布于 2026 年 4 月 23 日），说明已安装。否则按下文方法安装。

安装方法

方法一：官方安装脚本（所有平台推荐）

Hermes Agent 官方仅通过 install.sh 脚本分发——没有 npm 包、没有 Homebrew cask、没有 winget。所有平台共用同一条命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

脚本自动处理：

使用 uv 安装 Python 3.11 与虚拟环境
安装 Node.js v22（用于 WhatsApp bridge）
安装 ripgrep、ffmpeg 等系统依赖
从 GitHub clone 仓库到 ~/.hermes/，建立 Python 虚拟环境
把 hermes 命令链接到 ~/.local/bin/hermes

完成后重载 shell：

source ~/.bashrc # 或 source ~/.zshrc

运行 hermes –version 验证，运行 hermes 启动 TUI。

检测平台自动选择 extras：脚本会根据运行环境选择不同的 Python extras。Linux/macOS/WSL2 安装 .[all]（包含全部依赖与语音模式），Termux 安装 .[termux]（移除 Android 不兼容的语音相关库）。

方法二：Linux 与 macOS 部署细节

最常见的部署场景，按顺序执行：

# 安装 git（如未安装）
sudo apt install git # Ubuntu / Debian
sudo dnf install git # Fedora / RHEL
brew install git # macOS
 
# 运行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# 重载 shell
source ~/.bashrc # bash
source ~/.zshrc # zsh
 
# 启动 setup 向导（一次性配置 model provider、tools、gateway）
hermes setup

setup 向导会按顺序问以下问题：

Model provider：从 Nous Portal、OpenRouter、Anthropic、OpenAI、本地 Ollama 等中选择
API Key：对应 provider 的 Key，存入 ~/.hermes/.env
Terminal backend：默认 local，后续可改 Docker / SSH / Modal 等
Gateway 平台：可选，如配 Telegram bot token、Discord 等
Tools 与 skills：选择启用哪些工具与初始技能

完成后执行 hermes 进入 TUI，或 hermes –tui 进入更现代的 TUI（推荐）。

方法三：Windows 用户必须使用 WSL2

Hermes Agent 不支持 Windows 原生路径，根据官方文档说明，Windows 用户必须先安装 WSL2：

# 在 PowerShell 管理员窗口执行
wsl --install -d Ubuntu
 
# 重启电脑后进入 WSL Ubuntu，执行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# 重载 shell
source ~/.bashrc

WSL2 安装注意事项：

所有依赖（Python、Node.js、git、ripgrep）必须在 WSL2 内安装，不要混用 Windows 原生侧的工具链
项目代码建议存储在 WSL2 文件系统（~/projects），不要放在 /mnt/c/ 下——后者跨文件系统访问性能差
Hermes 默认启动会监听 localhost 端口（如 8642 给 gateway 用），WSL2 与 Windows 主机端口共享，可在 Windows 浏览器直接访问

方法四：Android Termux 移动端部署

Hermes Agent 是少数支持 Android 部署的 AI agent之一，对希望在手机上运行个人 agent 的用户尤其友好：

第一步：安装 Termux

不要从 Google Play 安装 Termux（已停止更新）。从 F-Droid 下载安装最新版本。

第二步：在 Termux 中运行安装脚本

# 更新 Termux 包索引
pkg update && pkg upgrade
 
# 安装基础依赖
pkg install git python
 
# 运行官方安装脚本（脚本会自动检测 Termux 并切换到 Android 流程）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Termux 路径的限制：根据官方 README，Termux 上 Hermes 安装的是 .[termux] extras 而非 .[all]，移除了 Android 不兼容的语音相关依赖（如 faster-whisper 的语音转文本功能）。其他 40+ 工具与跨会话记忆全部可用。

典型 Termux 使用场景：在手机上跑一个轻量 Hermes 实例，配置 Telegram gateway，把手机 24 小时挂在桌面充电——一个零成本的”随身 AI 助手”。结合 Termux 的 SSH 服务器功能，还可以从笔记本通过 SSH 远程操作手机上的 Hermes。

方法五：Docker 部署（生产环境推荐）

Docker 部署的优势是隔离性、可复制部署、配合 docker-compose 实现服务级管理。Hermes 提供官方 Docker 镜像 nousresearch/hermes-agent。

首次运行（交互式 setup）：

# 创建数据目录
mkdir -p ~/.hermes
 
# 交互式运行 setup 向导
docker run -it --rm \
 -v ~/.hermes:/opt/data \
 nousresearch/hermes-agent setup

setup 向导会引导配置 model provider、API Key 等，所有配置写入挂载的 ~/.hermes/.env。

持久化运行 gateway（推荐生产部署方式）：

docker run -d \
 --name hermes \
 --restart unless-stopped \
 -v ~/.hermes:/opt/data \
 -p 8642:8642 \
 nousresearch/hermes-agent gateway run

端口 8642 暴露 gateway 的 OpenAI 兼容 API 与健康检查端点。如果只用 Telegram/Discord 等聊天平台触达，该端口可不映射。

升级 Docker 部署：

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
 --name hermes \
 --restart unless-stopped \
 -v ~/.hermes:/opt/data \
 nousresearch/hermes-agent gateway run

数据目录 ~/.hermes 不受重建容器影响，技能、记忆、会话历史全部保留。

重要：UID 不匹配问题：容器内默认以 UID 10000 的 hermes 用户运行。若主机 ~/.hermes/ 归不同 UID 所有，会出现权限错误。解决方案是设置 HERMES_UID 与 HERMES_GID 环境变量匹配主机用户：

docker run -d \
 --name hermes \
 --restart unless-stopped \
 -v ~/.hermes:/opt/data \
 -e HERMES_UID=$(id -u) \
 -e HERMES_GID=$(id -g) \
 nousresearch/hermes-agent gateway run

方法六：克隆仓库手动安装（开发者）

适合想要修改源码、贡献 PR 或运行 dev 分支的开发者：

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
 
# 使用项目自带的 setup 脚本（自动安装 uv、创建虚拟环境）
./setup-hermes.sh
 
# 或手动等价步骤
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
 
# 运行测试
scripts/run_tests.sh
 
# 启动（项目目录下的 hermes 会自动检测 venv）
./hermes

setup-hermes.sh 与 install.sh 的区别：

install.sh（curl 安装）：面向最终用户，把仓库 clone 到 ~/.hermes/、链接全局 hermes 命令、启动 setup 向导
setup-hermes.sh（仓库内）：面向贡献者，在当前 clone 目录建立开发环境、安装 dev 依赖

认证与 model provider 配置

与 Claude Code、Codex 不同，Hermes 不内置任何模型订阅，安装后必须至少配置一个 provider 才能开始使用。Hermes 支持的 provider 列表非常长：

Nous Portal：Nous Research 自营服务，提供 Hermes-3 等开源模型，据 Decrypt 报道 v0.11.0 起 MiMo v2 Pro 对 Hermes 用户免费
OpenRouter：聚合 200+ 模型，单 Key 访问，国内开发者常用入口
NVIDIA NIM：Nemotron 模型族
Xiaomi MiMo：小米开源 MiMo 模型
z.ai / GLM：智谱 GLM 系列
Kimi / Moonshot：月之暗面 Kimi
MiniMax：MiniMax 模型
Hugging Face：HF Inference API
OpenAI / Anthropic：标准 GPT / Claude API
本地 Ollama：通过 OpenAI 兼容端点访问，零费用
自定义 OpenAI 兼容端点：任意第三方 OpenAI-compatible API

配置方法：

# 交互式选择 provider 与模型
hermes model
 
# 命令行设置默认模型
hermes config set model anthropic/claude-opus-4.6
 
# 设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

切换模型不需重启：在 TUI 内执行 /model 即可热切换，会话历史不丢失。

Terminal Backend 选择：agent 在哪里执行命令

Hermes 一个独特设计是把 agent 本体与 agent 实际执行 shell 命令的环境分离。安装在你笔记本的 Hermes 可以让 agent 在远程 VPS 上执行命令，或在 Modal 云沙箱中运行。共有六种 backend：

local：默认，在 Hermes 所在机器执行命令。适合个人开发与受信任环境
docker：在本机 Docker 容器内执行，提供隔离。需 docker version 验证可用
ssh：通过 SSH 在远程主机执行。需配置 TERMINAL_SSH_HOST 与 TERMINAL_SSH_USER
modal：Modal 云端 serverless 沙箱，idle 时几乎零成本，按需启动。需 MODAL_TOKEN_ID
daytona：Daytona 临时开发环境，类似 GitHub Codespaces。需 DAYTONA_API_KEY
singularity：HPC 集群常用的 Singularity/Apptainer 容器。需 apptainer 或 singularity 在 PATH 中

切换 backend：

# 切到 Docker 隔离
hermes config set terminal.backend docker
 
# 切到远程 SSH
hermes config set terminal.backend ssh
 
# 切回本地
hermes config set terminal.backend local

选哪个 backend：

个人开发与学习：local（默认）即可
对 agent 自主写代码、运行命令存疑：docker，提供隔离防止误操作
已有云端 VPS 想 agent 在那里跑：ssh
追求极致 idle 成本：modal，闲置时几乎零成本

从 OpenClaw 迁移：自动化导入完整流程

Hermes 内置 hermes claw migrate 命令，自动从 ~/.openclaw 迁移配置、记忆、技能与 API Key——这对从 OpenClaw 切换过来的用户是杀手级特性。

首次 setup 自动检测：执行 hermes setup 时，向导会检测 ~/.openclaw 目录存在，自动询问是否迁移。

安装后手动迁移：

# 交互式完整迁移（默认 preset）
hermes claw migrate
 
# 预览将要迁移哪些内容（不实际执行）
hermes claw migrate --dry-run
 
# 仅迁移用户数据，不带 API Key 等敏感信息
hermes claw migrate --preset user-data
 
# 强制覆盖已存在的同名配置
hermes claw migrate --overwrite

迁移涵盖内容：

SOUL.md：persona 定义文件
Memories：MEMORY.md 与 USER.md 条目
Skills：用户自创技能 → ~/.hermes/skills/openclaw-imports/
命令允许列表：approval patterns
Messaging 配置：平台 token、允许用户列表、工作目录
API Key 白名单：Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs 等
TTS 资源：工作区音频文件
AGENTS.md：通过 –workspace-target 指定项目级工作区指令

并行运行策略：迁移过程中可同时保留 OpenClaw 与 Hermes 在不同账号上运行——比如 OpenClaw 接 WeChat、Hermes 接 Telegram，等 Hermes 在 cron 与路由行为上完全匹配后再切换。社区项目 HermesClaw 提供 WeChat bridge，让两者可以在同一个微信账号上并存。

Gateway 配置：让 Hermes 出现在你的聊天软件

Hermes 的核心卖点之一是通过单一 gateway 进程接入多个聊天平台。安装后启用 gateway：

# 交互式 gateway setup 向导
hermes gateway setup
 
# 启动 gateway
hermes gateway start
 
# 安装为系统服务（systemd）以实现 7×24 运行
hermes gateway install

支持的聊天平台：

Telegram：通过 BotFather 创建 bot 获取 token，配置到 gateway
Discord：创建 Discord application bot 并邀请到服务器
Slack：创建 Slack App 并安装到 workspace
WhatsApp：通过 baileys 库（基于 Node.js）连接 WhatsApp Web
Signal：通过 signal-cli 桥接
Email：IMAP/SMTP 接收发送邮件

典型部署模式：在 5 美元/月的 VPS 上跑 gateway，配置 Telegram bot——出门在外通过手机 Telegram 给 bot 发”帮我把昨天的 GitHub 通知整理成日报”，VPS 上的 Hermes 处理后回复结果。这是 Hermes 与传统编码 agent 最大的体验差异。

更新方式

Hermes 提供内置升级命令：

# 升级到最新版本
hermes update

由于 Hermes 通过 git clone 安装而非包管理器分发，升级实际是：

git pull 最新 main 分支代码
uv pip install 更新依赖
迁移配置文件（如有 schema 变更）

Docker 部署的升级：拉取最新镜像后重建容器（前面方法五已说明）。

Termux 上的升级：执行 hermes update，注意 Termux 内升级时间较长，可能需要 5-10 分钟。

常见问题排查

问题 1：安装脚本失败 – Python 3.11 找不到

原因：安装脚本用 uv 自动安装 Python 3.11，但某些受限环境（如学校机房、企业 NAT）可能阻断 uv 的下载。

解决方案：先手动安装 uv，再执行 install.sh：

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

或参考方法六手动 clone 仓库的路径，所有依赖都通过本地 uv 处理。

问题 2：hermes 命令安装后找不到

原因：PATH 中未包含 ~/.local/bin。

解决方案：

# 检查 PATH
echo $PATH | tr ':' '\n' | grep local/bin
 
# 加入 PATH（bash）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题 3：hermes doctor 报错

解决方案：hermes doctor 是诊断工具，报错通常会指出具体哪个组件出问题——Python 版本、Node 版本、缺失的系统依赖（ripgrep/ffmpeg）、Docker 不可用等。按提示逐一修复，必要时重新执行 install.sh。

问题 4：Termux 上 voice 相关功能失败

原因：Termux 上 Hermes 默认装 .[termux] extras，不包含语音转文本与语音合成依赖（faster-whisper 等库不兼容 Android）。

解决方案：这是预期限制，不要尝试在 Termux 上启用语音模式。其他 40+ 工具与跨会话记忆全部可用。

问题 5：Docker 部署 UID 权限错误

原因：容器内 hermes 用户 UID=10000，与主机 ~/.hermes/ 目录所有者 UID 不匹配。

解决方案：通过环境变量传递主机 UID：

docker run -d \
 --name hermes \
 -v ~/.hermes:/opt/data \
 -e HERMES_UID=$(id -u) \
 -e HERMES_GID=$(id -g) \
 nousresearch/hermes-agent gateway run

问题 6：从 OpenClaw 迁移后某些技能不工作

原因：OpenClaw 与 Hermes 的技能格式略有差异，自动迁移会处理大部分情况但不保证 100% 兼容。

解决方案：

先用 hermes claw migrate –dry-run 预览将迁移的内容
迁移后在 ~/.hermes/skills/openclaw-imports/ 检查导入的 skill 文档
不工作的技能可手动调整或在 Skills Hub 找替代版本

问题 7：gateway 接 Telegram 但收不到消息

解决方案：

检查 BotFather 给的 token 是否正确写入 ~/.hermes/.env
确保 bot 已启动（hermes gateway start）且日志无错误
在 BotFather 设置 bot 的 /setprivacy 为 Disable，否则 bot 在群聊中收不到消息
初次发消息前需先在 Telegram 中搜索 bot 用户名并点击 Start

问题 8：国内网络无法访问 Anthropic / OpenAI / Nous Portal

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port 后重启 hermes
使用 OpenRouter（部分国内可达）或国内 provider（智谱 GLM、Kimi、MiniMax 等）
本地 Ollama + 开源模型，完全离线运行

问题 9：Modal backend 提示认证失败

解决方案：

# 安装 modal SDK
pip install modal
 
# 通过浏览器授权
modal token new
 
# 验证
hermes doctor

成功后 ~/.modal.toml 会写入 token，Hermes 自动读取。

问题 10：自学习闭环没看到效果

原因：Hermes 的 skill 创建是在完成复杂任务后触发，简单的单步对话不会生成新 skill。

解决方案：

给 Hermes 一些有完整流程的复杂任务（如”帮我配置一个 GitHub Actions 工作流并提交 PR”）
检查 ~/.hermes/skills/ 是否有自创 skill 文档生成
在 TUI 内执行 /skills 浏览已有技能库

验证安装与基础使用

# 检查版本
hermes --version
 
# 完整诊断
hermes doctor
 
# 启动 TUI（推荐）
hermes --tui
 
# 经典 CLI 模式
hermes

进入 Hermes 后可使用以下内置命令：

# 切换 model 与 provider
/model [provider:model]
 
# 设置 personality
/personality [name]
 
# 重新开始会话
/new
/reset
 
# 浏览 skills
/skills
 
# 触发特定 skill
/
 
# 压缩对话历史
/compress
 
# 查看 token 用量
/usage
 
# 撤销 / 重做
/undo
/retry

装完之后的关键三步：

用一个具体的小任务验证基础对话能跑通——官方建议先确认普通聊天工作，再加 gateway、cron、skills、voice 等高级功能
配置一个聊天平台 gateway（推荐先 Telegram，最简单），让 Hermes 跨设备触达
给一个完整的工作流任务（如”分析这个项目并生成开发文档”），观察 ~/.hermes/skills/ 是否生成自创 skill——这是 Hermes 与其他 agent 的核心差异

卸载方式

Hermes 安装通过 git clone + venv，没有包管理器分发，卸载需手动清理：

# 删除 hermes 命令链接
rm -f ~/.local/bin/hermes
 
# 删除主目录（包含代码、虚拟环境、配置、数据、技能、记忆）
rm -rf ~/.hermes
 
# Docker 部署的卸载
docker rm -f hermes
docker rmi nousresearch/hermes-agent
rm -rf ~/.hermes
 
# 项目克隆方式安装的卸载
rm -rf /path/to/hermes-agent

注意安全：~/.hermes/.env 包含所有 provider 的 API Key 明文，Telegram bot token 等敏感信息。卸载前如不打算重装，建议先撤销相关 Key。

~/.hermes 目录结构：

~/.hermes/.env：API Key 与配置
~/.hermes/skills/：技能库（含自创技能）
~/.hermes/sessions/：会话历史（FTS5 全文搜索数据库）
~/.hermes/memory/：跨会话持久记忆
~/.hermes/cache/：远程同步缓存（SSH/Modal/Daytona backend 用）

获取方式

GitHub 仓库：NousResearch/hermes-agent

官方文档：Hermes Agent Docs

快速开始：Quickstart Guide

Termux 详细指南：Termux Guide

CLI 命令参考：CLI Reference

环境变量参考：Environment Variables

Skills Hub：agentskills.io

社区 Discord：Nous Research Discord

精选资源列表：awesome-hermes-agent

Hermes Agent 与 Claude Code、Codex、OpenCode 的产品定位完全不同——它不是编码工具，而是面向”个人 AI 管家”场景的自学习 agent，覆盖跨平台触达、跨会话记忆、自然语言定时任务等编码 agent 不涉及的能力。但安装本身只是入口，真正决定 Hermes 价值的是后续SOUL.md persona 设计、技能库的持续积累、gateway 多平台路由配置以及 backend 选择策略。对中文开发者而言，Hermes 与 Claude Code 等编码 agent 是互补关系——Claude Code 解决”如何更好地写代码”，Hermes 解决”如何让 AI 在你的日常生活与工作流中持续提供价值”。

本文首发于 LLM 大模型邮报。

OpenCode 安装最简流程：终端、桌面应用与 IDE 扩展三端一次说清

MISTY — Fri, 01 May 2026 16:30:46 +0000

OpenCode 是当前最受关注的开源 AI 编码 agent 之一，GitHub 收获 153k+ stars、月活开发者 6.5M+，由 Anomaly 团队（前 SST）维护，anomalyco/opencode 仓库采用 MIT 协议开源。OpenCode 安装最大的卖点是 provider 中立——不绑定任何模型厂商，可同时使用 Claude、GPT、Gemini、Grok、本地 Ollama 模型甚至 GitHub Copilot 订阅，对中文开发者尤其友好。

OpenCode 当前提供四个表面：终端 CLI（核心）、桌面应用 Beta、VS Code / Cursor / Zed / Windsurf 扩展、GitHub Actions 集成。本指南整理三端在 macOS、Windows、Linux 上的最简安装命令，并解决 opencode-ai 老仓库（已改名 Crush）与当前 anomalyco 主流版本的消歧义问题。

仓库消歧义：你要装的是 anomalyco/opencode

OpenCode 在 2025 年经历了一次分裂，导致 GitHub 上同时存在两个 “opencode” 仓库，初学者很容易装错版本：

opencode-ai/opencode（旧仓库，已不再维护）：2024 年由 Kujtim Hoxha 主导用 Go 创建的原始版本，2025 年与 Charm 合作后改名为 Crush，已停止以 OpenCode 名义发布新版本
anomalyco/opencode（当前主流版本）：2025 年由 Dax Raad、Adam Doty 等贡献者从原始版本 fork，用 TypeScript + Bun 完全重写，并采用自研 OpenTUI 框架（Zig + SolidJS）。SST 公司 2026 年改名为 Anomaly，仓库随之迁移

判断标准：

访问 opencode.ai 与 github.com/anomalyco/opencode，这是当前活跃维护的主流版本
npm 包名应是 opencode-ai（Anomaly 沿用了原 npm 包名继续发布）
Homebrew tap 应是 anomalyco/tap/opencode

本文所有命令均针对 anomalyco/opencode 当前主流版本。

系统要求与前置检查

OpenCode 由 TypeScript + Bun 构建，发布为自包含原生二进制：

操作系统：macOS、Windows 10/11、Linux 主流发行版（Ubuntu、Debian、Fedora、RHEL、Arch、Alpine 等）
系统架构：x64 或 ARM64
Node.js：仅 npm 安装路径需要 18+；其他路径无依赖
账号：OpenCode 本体免费开源，使用成本取决于你接入的模型 provider——可使用 Anthropic、OpenAI、Google、Groq、OpenRouter 等付费 API，或免费的本地 Ollama 模型，也可用 OpenCode Zen 订阅（10 美元/月，提供官方测试过的模型集）
终端：建议使用现代终端模拟器（iTerm2、Windows Terminal、Alacritty、Kitty、Ghostty 等）以获得最佳 TUI 体验

关于 provider 中立：OpenCode 不直接消耗任何订阅额度。你需要至少一个 LLM 入口才能使用——最低成本路径是 本地 Ollama + 开源模型（零费用），最高质量路径是 Claude Sonnet/Opus 或 GPT 系列 API。

检查当前是否已安装：

opencode --version

如果返回版本号（如 v1.1.x），说明已安装。否则按下文方法安装。

安装方法

方法一：官方安装脚本（跨平台推荐）

最简单的安装路径，零依赖、自动检测平台架构、自动配置 PATH：

macOS、Linux、WSL：

curl -fsSL https://opencode.ai/install | bash

Windows PowerShell：脚本同样兼容 Windows 子系统，建议在 WSL2 内执行。原生 PowerShell 用户改用方法三的 Scoop 或 Chocolatey 路径。

可通过环境变量自定义安装目录：

# 安装到自定义目录
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
 
# 使用 XDG 标准目录
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

完成后运行 opencode –version 验证。

方法二：Homebrew（macOS / Linux）

OpenCode 提供两个 Homebrew 入口，选择哪个对更新及时性有显著影响：

# 推荐：Anomaly 自维护 tap，更新最及时
brew install anomalyco/tap/opencode
 
# 备选：Homebrew 官方 formula，更新较慢
brew install opencode

差异说明：anomalyco/tap 由 OpenCode 团队自己维护，新版本发布后即时同步；而 Homebrew 官方 formula 走社区审核流程，存在 1-2 个版本的滞后。对于活跃迭代的工具优先选 anomalyco/tap。

升级用：

brew upgrade opencode

**桌面应用（Beta）**同样通过 Homebrew cask 安装：

brew install --cask opencode-desktop

方法三：Windows 包管理器（Scoop / Chocolatey / WinGet）

Windows 用户原生路径有三种包管理器选择，无需 WSL 即可获得完整功能。

Scoop（推荐）：

# OpenCode CLI
scoop install opencode
 
# OpenCode 桌面应用
scoop bucket add extras
scoop install extras/opencode-desktop

Chocolatey：

choco install opencode

WinGet：

winget install --id SST.opencode -e

关于 winget 包名为 SST.opencode 的历史：包 ID 仍以 SST 命名空间发布，是因为该包在 SST 公司更名为 Anomaly 之前就已提交到 winget 仓库——一旦确定的 winget 包 ID 通常不会变更，避免破坏现有用户的更新链路。但包内部的安装源（InstallerUrl）已经指向 github.com/anomalyco/opencode/releases/，所以装的就是当前主流版本。

WinGet 路径已知问题：根据 OpenCode GitHub Issue 5121，winget 包审核流程比 GitHub Releases 慢 1-2 个版本，且 winget 路径未在 OpenCode 官方文档中显式列出。对追新版本的用户，建议使用方法一的官方安装脚本或 Scoop；对企业受控环境强制使用 winget 的用户，该路径仍可用，仅需接受版本滞后。

升级：

# Scoop
scoop update opencode
 
# Chocolatey
choco upgrade opencode
 
# WinGet
winget upgrade --id SST.opencode

方法四：npm 安装（跨平台）

适合 CI/CD 中需要固定版本、团队工作流以 npm 为标准的场景：

# npm
npm install -g opencode-ai@latest
 
# 或 bun（OpenCode 自身使用 Bun 构建，bun 路径性能略好）
bun add -g opencode-ai
 
# pnpm / yarn
pnpm add -g opencode-ai
yarn global add opencode-ai

注意 npm 包名：是 opencode-ai，不是 opencode。npm 上无关同名包同样存在，安装前确认完整命令。

要求 Node.js 18+。禁止使用 sudo npm install -g，遇到 EACCES 错误改用用户级 npm prefix 或 nvm。

方法五：Linux 包管理器（Arch / Nix）

Arch Linux 用户：

# 稳定通道（pacman）
sudo pacman -S opencode
 
# AUR 最新版本（paru / yay）
paru -S opencode-bin
yay -S opencode-bin

Nix 用户：

# 从 nixpkgs 运行
nix run nixpkgs#opencode
 
# 使用 dev 分支最新版本
nix run github:anomalyco/opencode

Mise / asdf 用户：

mise use -g opencode

方法六：桌面应用（Beta）

OpenCode 桌面应用目前处于 Beta 阶段，提供图形化的项目管理界面：

macOS Homebrew：

brew install --cask opencode-desktop

Windows Scoop：

scoop bucket add extras
scoop install extras/opencode-desktop

直接下载：访问 opencode.ai/download 下载对应平台安装包：

macOS Apple Silicon / Intel
Windows x64
Linux .deb / .rpm

桌面应用与 CLI 共享同一个数据目录与认证，在任一表面登录后另一表面无需再次认证。

方法七：IDE 扩展（VS Code / Cursor / Zed / Windsurf）

OpenCode 提供官方 IDE 扩展，把 agent 集成到编辑器内：

VS Code：扩展市场搜索 “OpenCode”
Cursor：扩展市场搜索 “OpenCode”（Cursor 是 VS Code fork，扩展兼容）
Zed：从 Zed Extensions 安装
Windsurf：扩展市场搜索 “OpenCode”
VSCodium：从 OpenVSX 安装

或访问 opencode.ai/download 跳转到各 IDE 的对应安装链接。

认证与模型配置：你必须连一个 provider 才能用

与 Claude Code、Codex 不同，OpenCode 不内置任何模型订阅——这是它最大的灵活性，也是初次配置的主要门槛。安装后必须至少连接一个 provider 才能开始使用。

OpenCode 使用 Models.dev 维护的 provider 列表，启动后执行：

opencode auth login

会列出所有支持的 provider，选择后输入对应 API Key 即可。常见 provider 配置：

Anthropic（Claude）：在 console.anthropic.com 创建 API Key
OpenAI（GPT）：在 platform.openai.com 创建 API Key
OpenRouter：聚合多家 provider，单 Key 访问 100+ 模型，国内开发者常用
本地 Ollama：执行 opencode auth login 选 Ollama，无需 Key，仅需本地 Ollama 服务运行
GitHub Copilot：复用已有 Copilot 订阅，登录 GitHub 账号即可
OpenCode Zen：OpenCode 团队自营订阅服务，10 美元/月提供官方测试过的精选模型集

凭证存储在 ~/.local/share/opencode/auth.json（Linux/macOS）或 %LOCALAPPDATA%\opencode\auth.json（Windows），需视为密码保护。

切换默认模型：在 OpenCode TUI 内执行 /connect 选择 provider 与模型，或编辑 opencode.json 配置文件。

模型选择建议：从零开始如何配第一个 provider

对完全新手而言，OpenCode 的 provider 中立性反而是部署门槛。三种典型场景的最小配置：

场景 1：完全免费体验：先装 Ollama → ollama pull qwen2.5-coder:7b → 在 OpenCode 中选 Ollama provider。零费用但模型能力受本地硬件限制。

场景 2：质量优先：使用 Anthropic Claude Sonnet/Opus API，按 token 计费但当前是公认编码能力最强的模型。月度预算 20-50 美元可覆盖日常使用。

场景 3：性价比优先：使用 OpenRouter 单 Key 访问 GLM、DeepSeek、Kimi 等中国开源模型，单价显著低于 Claude/GPT。中文项目编码场景对中文开源模型友好度较高。

不推荐做法：在第一次安装时跳过 provider 配置直接进 TUI——OpenCode 会显示 /connect 提示但无法处理任何请求，体验上像是工具坏了。

更新方式：每个安装路径不同

不同安装路径对应不同更新机制：

官方安装脚本：重新执行 curl -fsSL https://opencode.ai/install | bash，或使用内置 opencode upgrade 命令
Homebrew：brew upgrade opencode
npm：npm install -g opencode-ai@latest
Scoop：scoop update opencode
Chocolatey：choco upgrade opencode
WinGet：winget upgrade –id SST.opencode
pacman：sudo pacman -Syu opencode
桌面应用：通过包管理器更新或在应用内检查更新

OpenCode 内置升级命令支持指定版本：

# 升级到最新版本
opencode upgrade
 
# 升级到特定版本
opencode upgrade --version 1.1.20

常见问题排查

问题 1：装错了仓库（opencode-ai 而非 anomalyco）

原因：在 GitHub 搜索 opencode 时排在前面的可能是已停止维护的旧仓库。

解决方案：确认 npm 包名 opencode-ai、Homebrew tap anomalyco/tap、官方网站 opencode.ai、当前主仓库 github.com/anomalyco/opencode。如果已装错版本：

# 卸载旧的 opencode-ai/opencode（如有）
which opencode # 确认当前 opencode 路径
rm -f $(which opencode)
 
# 重新装当前主流版本
curl -fsSL https://opencode.ai/install | bash

问题 2：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 18+。

解决方案：执行 node –version 检查。低于 18 时通过 nvm install –lts 升级，或改用方法一的官方安装脚本（不需要 Node.js）。

问题 3：opencode –version 提示 command not found

解决方案：

关闭终端开新窗口
macOS/Linux 执行 source ~/.zshrc 或 source ~/.bashrc
检查官方安装脚本默认目录是否在 PATH 中（通常是 ~/.opencode/bin 或 ~/.local/bin）

问题 4：TUI 显示乱码或字符错位

原因：OpenCode 使用自研 OpenTUI 框架（Zig + SolidJS），对终端模拟器的现代特性有依赖。某些老终端（默认 cmd.exe、低版本 Terminal.app）渲染异常。

解决方案：

切换到现代终端：iTerm2、Windows Terminal、Alacritty、Kitty、Ghostty
确认终端 Locale 设为 UTF-8：echo $LANG 应输出 en_US.UTF-8 或 zh_CN.UTF-8
确认终端字体支持 Powerline / Nerd Font 图标

原因：OpenCode 从 Models.dev 拉取 provider 列表，如果该数据未更新或网络不通会缺失部分选项。

解决方案：

升级 OpenCode 到最新版本
检查能否访问 models.dev
对于尚未在 Models.dev 列出的 provider，可在 opencode.json 中手动配置 OpenAI 兼容端点

问题 6：本地 Ollama 模型连不上

原因：OpenCode 默认期望 Ollama 监听 127.0.0.1:11434，自定义部署或远程 Ollama 需显式配置。

解决方案：在 shell 中设置：

export LOCAL_ENDPOINT=http://your-ollama-host:11434

或在 opencode.json 中配置自托管 provider。

问题 7：国内网络无法访问 Anthropic / OpenAI API

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port
使用 OpenRouter 等聚合服务（部分国内可达）
使用国内可达的中国开源模型 API（智谱 GLM、深度求索 DeepSeek、月之暗面 Kimi 等），通过 opencode.json 配置 OpenAI 兼容端点

问题 8：plan 模式与 build 模式如何切换

解决方案：在 TUI 内按 Tab 键即可切换。Build 是默认全权限 agent，Plan 是只读分析模式适合先做方案再改代码。OpenCode 支持自定义 agent，配置文件位于 ~/.opencode/agents/ 或项目级 .opencode/agents/。

问题 9：Copilot 订阅认证失败

原因：OpenCode 通过读取系统中已有的 GitHub Copilot 凭证文件实现 Copilot 复用，需要先在 VS Code 或其他 Copilot 客户端登录。

解决方案：

在 VS Code Copilot 扩展或 GitHub CLI（gh auth login）中先登录
OpenCode 会自动从标准位置读取 token
仍失败时手动设置 GITHUB_TOKEN 环境变量，或在 opencode.json 的 providers.copilot.apiKey 中配置

验证安装与基础使用

安装完成后，建议执行以下命令验证：

# 检查版本
opencode --version
 
# 配置第一个 provider
opencode auth login
 
# 在项目目录启动 TUI
cd /path/to/your/project
opencode

进入 OpenCode 后可使用以下内置命令：

# 切换 provider 与模型
/connect
 
# 分析仓库结构并生成 AGENTS.md
/init
 
# 显示帮助与快捷键
/help
 
# 撤销 / 重做最近一次变更
/undo
/redo
 
# 分享当前会话（可选功能）
/share

关键快捷键：

Tab：在 Build 与 Plan 模式之间切换
@：模糊搜索项目文件，把文件加入上下文
拖拽图片到终端：把图片加入上下文，OpenCode 支持视觉模型
Ctrl+X：默认 leader key（避免与终端快捷键冲突），后接 Leader+key 触发各种命令

装完之后的关键三步：

在项目根目录运行 /init，让 OpenCode 分析代码库并生成 AGENTS.md 作为持久上下文。该文件兼容 Claude Code 的 CLAUDE.md 与 Codex 的 AGENTS.md 约定
使用 Plan 模式（按 Tab 切换）让 OpenCode 先生成实施方案，确认后切回 Build 模式执行——这种”先规划后执行”的工作流是 OpenCode 相比其他工具的差异化设计
通过 opencode mcp add 接入 MCP 服务器，把 OpenCode 扩展为可调用 GitHub、数据库、内部 API 的完整 agent

非交互模式与 API 服务器

OpenCode 除 TUI 外还支持脚本调用与 HTTP 服务器模式，适合自动化集成：

# 单次提示 + 输出（适合 CI/CD）
opencode -p "Explain the use of context in Go"
 
# JSON 格式输出
opencode -p "List all TODO comments in this project" -f json
 
# 静默模式（脚本调用，禁用 spinner）
opencode -p "..." -q
 
# 启动 HTTP 服务器（多客户端并行连接）
opencode serve

opencode serve 启动后会暴露带 OpenAPI 文档（/doc）的 HTTP 端点，配合官方 @opencode-ai/sdk JS/TS SDK 可在自有应用内嵌入 OpenCode 能力。这是 OpenCode 的客户端/服务器架构带来的独特能力——TUI 只是众多前端之一。

卸载方式：不同安装路径对应不同清理步骤

OpenCode 提供内置卸载命令一键清理所有相关文件：

opencode uninstall

也可按安装方式分别处理：

官方安装脚本：删除二进制（通常在 ~/.opencode/bin/opencode）
Homebrew：brew uninstall opencode 与 brew uninstall –cask opencode-desktop
npm：npm uninstall -g opencode-ai
Scoop：scoop uninstall opencode
Chocolatey：choco uninstall opencode
WinGet：winget uninstall –id SST.opencode
pacman：sudo pacman -R opencode

仅删除二进制并不能完全清理。配置目录与会话历史保留在以下位置：

# Linux / macOS
~/.local/share/opencode/ # 会话历史与认证
~/.config/opencode/ # 配置文件
~/.opencode/ # 用户级 agents 与命令
 
# Windows
%LOCALAPPDATA%\opencode\
%APPDATA%\opencode\

彻底清理执行：

# Linux / macOS
rm -rf ~/.local/share/opencode ~/.config/opencode ~/.opencode
 
# Windows PowerShell
Remove-Item -Path "$env:LOCALAPPDATA\opencode" -Recurse -Force
Remove-Item -Path "$env:APPDATA\opencode" -Recurse -Force

安全提示：auth.json 存储 API Key 明文。卸载前如不打算重装，建议先 opencode auth logout 显式撤销凭证。项目级配置 .opencode/ 与 opencode.json 需在每个项目目录下单独删除。

获取方式

官方网站：opencode.ai

下载页（覆盖所有表面）：opencode.ai/download

官方文档：OpenCode Docs

CLI 命令参考：CLI Reference

GitHub 主仓库：anomalyco/opencode

支持的模型与 provider：Models.dev

JS/TS SDK：@opencode-ai/sdk

OpenCode 通过 provider 中立、客户端/服务器架构与开源协议，提供了与 Claude Code、Codex 完全不同的产品定位——它不绑定任何模型厂商，把选择权完全交给开发者。但安装本身只是入口，真正决定生产力的是后续 provider 选型、AGENTS.md 上下文设计、自定义 agent 体系搭建以及 MCP 服务器集成。对中文开发者而言，OpenCode 与 Claude Code、Codex 并存往往比单一选择更实用——OpenCode 可对接国内开源模型 API 与本地 Ollama，覆盖 Claude/Codex 难以触达的场景。

本文首发于 LLM 大模型邮报。

Codex 安装最简流程：桌面应用、CLI 与 IDE 扩展三条路径一次说清

MISTY — Fri, 01 May 2026 14:24:32 +0000

OpenAI Codex 已经从最初的单一命令行工具演变为完整产品矩阵，覆盖桌面应用（Codex app）、命令行（Codex CLI）、IDE 扩展、云端 Web 与 GitHub 集成五个表面。所有 Codex 表面共享同一个 ChatGPT 账号认证体系，包含在 ChatGPT Plus、Pro、Business、Edu、Enterprise 订阅中无需额外付费。Codex 安装路径取决于你想在哪种环境下使用——终端、桌面、IDE 还是云端，本指南整理三大本地安装路径在 macOS、Windows、Linux 上的最简命令。

根据 OpenAI 官方公告，Codex 桌面应用于 2026 年 2 月在 macOS 首发，3 月 4 日上线 Windows，限时活动期间向 ChatGPT Free 与 Go 用户开放。本文按”产品矩阵—系统要求—安装方法—问题排查—验证使用—获取方式”六段，详细说明 Codex 在不同设备上的部署流程。

Codex 产品矩阵：先搞清装哪个

很多教程把”安装 Codex”等同于”安装 Codex CLI”，但实际上当前 Codex 包含五个独立但互通的表面：

Codex 桌面应用（Codex app）：macOS 与 Windows 原生应用，定位为 “command center for agents”，支持并行 agent 线程、worktree、in-app 浏览器、computer use（macOS）等
Codex CLI：开源命令行 agent，基于 Rust 构建，运行在本地终端，openai/codex GitHub 仓库已收获 75k+ stars
Codex IDE 扩展：VS Code、Cursor、Windsurf 等编辑器内的 Codex agent
Codex Cloud / Codex Web：云端异步任务模式，访问 chatgpt.com/codex 提交任务
Codex GitHub 集成：在 PR 评论中通过 @codex 触发云端任务

选哪个：

偏好图形界面、需要并行管理多个 agent、做前端 / 游戏开发需要 in-app 浏览器 → 桌面应用
终端工作流、CI/CD、SSH 远程开发、headless 环境 → CLI
已有 IDE 习惯、希望 agent 直接读取打开的文件 → IDE 扩展
长任务后台运行、不想占用本地资源 → Cloud / Web

三个本地表面共享配置：桌面应用、CLI、IDE 扩展共用 ~/.codex/config.toml（Windows 为 %USERPROFILE%.codex\config.toml），认证、MCP 服务器配置、自定义模型 provider 等设置在三者间自动同步。这意味着在一个表面登录后，其他两个表面无需再次认证。

系统要求与前置检查

根据 Codex 官方安装文档：

桌面应用：macOS（Apple Silicon 优先，Intel 也有对应构建）；Windows 10/11，通过 Microsoft Store 分发
Codex CLI：macOS、Windows 10/11、Linux 主流发行版（Ubuntu、Debian、Fedora、RHEL、Alpine 等）
系统架构：x64 或 ARM64
Node.js：仅 npm 安装路径需要 22+；Homebrew 与 GitHub Release 路径无依赖
账号：ChatGPT Plus（20 美元/月）、Pro（200 美元/月）、Business、Edu、Enterprise 之一，或一个有可用额度的 OpenAI API Key
限时活动：据 OpenAI 2026 年 2 月公告，Codex 桌面应用限时向 ChatGPT Free 与 Go 用户开放，截止时间以官方为准
网络：稳定连接到 OpenAI 服务端点，国内用户需配置代理

检查当前 Codex CLI 是否已安装：

codex --version

如果返回版本号（如 codex-cli 0.121），说明已安装。否则按下文方法安装。

安装方法

方法一：Codex 桌面应用（macOS / Windows 推荐）

适合大多数开发者的最简路径，提供并行 agent 线程、in-app 浏览器、worktree 管理、skills 与 plugins 等图形化能力。

macOS 安装：

访问 chatgpt.com/codex 下载 .dmg 文件（Apple Silicon 与 Intel 各有对应构建），双击挂载后将 Codex.app 拖入 Applications 目录。

或通过 Homebrew cask 安装：

brew install --cask codex

Windows 安装：

通过 Microsoft Store 安装是最简单的路径，Codex 在 Microsoft Store 的应用页支持一键安装，并通过 Store 自动更新。

或使用 winget：

winget install --id 9PLM9XGG6VKS --source msstore

从 CLI 启动桌面应用：如果已经安装了 Codex CLI，执行 codex app 会自动下载并安装桌面应用，省去手动下载步骤。

桌面应用首次启动时会引导完成 ChatGPT 账号 OAuth 登录，认证完成后即可创建项目。

方法二：Codex CLI 通过 npm 安装（跨平台）

最广泛的 CLI 安装方式，命令统一：

npm install -g @openai/codex

包名陷阱必须注意：完整包名是 @openai/codex（含 @openai 命名空间），不是 codex。npm 上存在另一个完全无关的 codex 包（2012 年发布、与 OpenAI 无关），OpenAI 官方 README 明确标注误装该包是常见错误来源。安装前确认命令包含 @openai/ 前缀。

要求 Node.js 22 或更高版本。npm 路径下的 codex 命令是个 JavaScript shim，运行时检测平台架构，加载对应的 optional dependency（如 @openai/codex-darwin-arm64），spawn 实际的原生 Rust 二进制执行。本身不参与运行时计算。

禁止使用 sudo npm install -g。遇到 EACCES 权限错误时配置用户级 npm prefix：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

升级 Codex CLI：

npm install -g @openai/codex@latest

方法三：Codex CLI 通过 Homebrew（macOS 推荐）

不需要 Node.js，直接安装 Rust 原生二进制：

brew install --cask codex

注意是 cask 而非 formula。brew install codex（不带 –cask）会失败或装到错误的包。Homebrew cask 同时安装 Codex CLI 与桌面应用——这是 2026 年初 Homebrew 包结构调整后的统一入口。

升级用：

brew upgrade --cask codex

如果之前用旧的 formula 路径安装过，需先卸载再装 cask：

brew uninstall codex
brew install --cask codex

方法四：Codex CLI 通过 GitHub Release 直接下载（零依赖）

适合不想引入 Node.js 或 Homebrew 的最小化部署场景，包括服务器、CI 环境、Docker 镜像等。访问 openai/codex GitHub Releases 页面下载对应平台归档：

macOS Apple Silicon：codex-aarch64-apple-darwin.tar.gz
macOS Intel：codex-x86_64-apple-darwin.tar.gz
Linux x86_64：codex-x86_64-unknown-linux-musl.tar.gz（musl 静态链接，最大兼容性）
Linux ARM64：codex-aarch64-unknown-linux-musl.tar.gz

每个归档解压后包含一个二进制文件，名字带平台标识，需重命名为 codex 并放到 PATH 中：

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex
chmod +x ~/.local/bin/codex

Linux 二进制使用 musl 静态链接而非 glibc，同一个二进制可在 Alpine、Ubuntu、Debian、CentOS 等不同发行版直接运行。

方法五：Codex IDE 扩展（VS Code / Cursor / Windsurf）

Codex IDE 扩展把 agent 直接集成到编辑器内，支持读取打开的文件与选中代码作为上下文。

VS Code 安装：

打开 VS Code 扩展面板（Cmd+Shift+X on Mac，Ctrl+Shift+X on Windows/Linux），搜索 “Codex” 选择官方 OpenAI Codex 扩展安装。

Cursor / Windsurf 安装：

在各自的扩展市场搜索 “Codex” 安装。Cursor 与 Windsurf 是 VS Code 的 fork，扩展生态兼容。

IDE 扩展与 CLI、桌面应用共用 ~/.codex/config.toml，认证状态自动同步——在任一表面登录后，IDE 扩展无需再次认证。

方法六：Windows 上的 WSL2 路径

如果项目托管在 WSL2 内、或需要 Linux 原生工具链，可在 WSL 内安装 Codex CLI：

# 在 PowerShell 管理员窗口安装 WSL（如未安装）
wsl --install -d Ubuntu
 
# 进入 WSL 后安装 Node.js 22 与 Codex CLI
nvm install 22
npm install -g @openai/codex

WSL1 已停止支持。Codex 0.115 起 Linux 沙盒迁移到 bubblewrap，仅 WSL2 可用。

Windows 原生与 WSL 配置同步：Windows 原生 Codex 使用 %USERPROFILE%.codex，WSL 内 Codex 默认使用 Linux ~/.codex。共享认证与会话历史在 WSL 中设置：

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex
echo 'export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex' >> ~/.bashrc

认证方式：ChatGPT 订阅与 API Key 的差异

Codex 所有本地表面（桌面应用、CLI、IDE 扩展）共享同一套认证体系，提供两种登录方式：

ChatGPT OAuth（推荐个人开发者）：自动打开浏览器，在 localhost:1455 启动 OAuth 回调服务器，登录 ChatGPT 账号后令牌存储到 ~/.codex/auth.json 或操作系统密钥库。直接绑定 ChatGPT 订阅额度，无需手动管理 Key。远程 SSH 或浏览器回调被阻断时使用设备码流程：

codex login --device-code

API Key（推荐 CI/CD 与自动化）：

export OPENAI_API_KEY=sk-...
codex

或通过 stdin 传入：

printenv OPENAI_API_KEY | codex login --with-api-key

关键差异：fast mode 等依赖 ChatGPT credits 的功能仅 OAuth 登录可用，API Key 路径走标准 API 计费。这意味着相同任务两种认证方式费用结构不同——OAuth 走订阅额度（消耗 ChatGPT 计划内的本地消息配额），API Key 按 token 计费。Codex 官方认证文档建议个人开发者使用 OAuth、CI/CD 流水线使用 API Key。

凭证存储位置可通过 ~/.codex/config.toml 中的 cli_auth_credentials_store 配置：

file：存储在 ~/.codex/auth.json（明文，需视为密码保护）
keyring：存储在操作系统密钥库（macOS Keychain、Windows Credential Manager、Linux Secret Service）
auto：优先使用密钥库，不可用时回落到 file

模型选择：GPT-5.5、GPT-5.4 与 GPT-5-Codex

Codex 当前可用的模型：

GPT-5.5：最新通用模型，复杂规划与多步推理首选
GPT-5.4：稳定可用的前一代，支持 1M 上下文窗口（实验性）与 native computer use
GPT-5.4 mini：轻量模型，适合代码库探索、大文件审查、subagent 工作
GPT-5-Codex：基于 GPT-5 进一步针对 agentic coding 优化的版本，OpenAI 建议仅在 Codex 或类 Codex 环境中使用

在 CLI 中切换模型：

# 启动新会话时指定
codex --model gpt-5.5
 
# 会话内切换
/model

或在 ~/.codex/config.toml 中持久化默认模型：

model = "gpt-5.5"

注意：如果账号尚未开放 GPT-5.5 访问，回退到 gpt-5.4 即可。模型可见性按账号逐步开放，更新 CLI、IDE 扩展或桌面应用到最新版本可能解锁新模型选项。

常见问题排查

问题 1：误装了无关的 codex 包

原因：执行 npm install -g codex 装到的是 2012 年发布的同名无关包。

解决方案：

npm uninstall -g codex
npm install -g @openai/codex

问题 2：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 22+。

解决方案：执行 node –version 检查。低于 22 时通过 nvm install 22 升级，或改用 Homebrew / GitHub Release 路径。

问题 3：codex –version 提示 command not found

解决方案：关闭终端开新窗口；macOS/Linux 执行 source ~/.zshrc 或 ~/.bashrc；Windows 关闭并重开 PowerShell。仍找不到检查 npm config get prefix 输出对应 bin 目录是否在 PATH 中。

问题 4：npm 安装报 EACCES 权限错误

解决方案：不要使用 sudo。按方法二末尾配置用户级 npm prefix，或改用 Homebrew 路径。

问题 5：macOS 提示 “无法打开 codex，因为开发者无法验证”

解决方案：

系统设置 → 隐私与安全性 → 找到被阻断的 codex 条目，点击”仍要打开”
或在 Terminal 中：xattr -d com.apple.quarantine $(which codex)

问题 6：Codex 桌面应用 macOS 仅支持 Apple Silicon？

原因：早期版本仅 Apple Silicon 构建。

解决方案：当前 Codex 桌面应用同时提供 Apple Silicon 与 Intel 构建。在 Codex 桌面应用下载页选择 Intel 构建即可。

问题 7：OAuth 浏览器回调失败

原因：远程 SSH、devcontainer、严格防火墙环境下 localhost:1455 回调被阻断。

解决方案：使用设备码流程 codex login –device-code，或直接设置 OPENAI_API_KEY 环境变量。

问题 8：Windows 原生沙盒初始化失败

解决方案：在 ~/.codex/config.toml 切换到 unelevated 沙盒模式：

[windows]
sandbox = "unelevated"

问题 9：API Key 已设置但 Codex 仍要求登录

解决方案：检查当前 shell：echo $OPENAI_API_KEY；添加到 shell profile 持久化；首次运行按 onboarding 流程批准该 Key。

问题 10：国内网络无法完成 OAuth 或 API 调用

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port
或在 ~/.codex/config.toml 配置 custom model provider 指向第三方兼容端点（注意非官方端点不消耗 ChatGPT 订阅额度，按第三方 provider 计费）

验证安装与基础使用

CLI 验证：

# 检查版本
codex --version
 
# 验证认证状态
codex login status
 
# 查看 MCP 服务器配置
codex mcp list
 
# 启动交互式 TUI
codex

桌面应用验证：启动后看到主界面 + 可创建新项目即说明安装成功。

进入 Codex CLI 后可使用以下内置命令：

# 切换模型
/model
 
# 会话状态与 token 用量
/status
 
# 查看当前生效配置
/config
 
# 压缩对话历史
/compact

装完之后的关键三步：

在项目目录运行 codex（CLI）或在桌面应用中创建项目，让 Codex 探索代码库结构。Codex 会自动读取项目根目录的 AGENTS.md 作为持久上下文，类似 Claude Code 的 CLAUDE.md 机制
设置 approval mode 适配工作风格——–sandbox workspace-write 适合无人值守的局部任务，–ask-for-approval never 让 Codex 自主完成
通过 codex mcp add 接入 MCP 服务器，把 Codex 扩展为可调用 GitHub、数据库、内部 API 的完整 agent

卸载方式：不同安装路径对应不同清理步骤

npm：npm uninstall -g @openai/codex
Homebrew cask：brew uninstall –cask codex
GitHub Release 手动安装：删除二进制所在路径（如 ~/.local/bin/codex）
桌面应用（macOS）：从 Applications 拖到废纸篓
桌面应用（Windows）：通过 Microsoft Store 卸载，或 winget uninstall 对应包

仅删除二进制并不能完全清理。配置目录 ~/.codex/（Windows 为 %USERPROFILE%.codex）包含认证令牌、MCP 服务器配置、会话历史与执行规则，会被保留以便重装。彻底清理：

# macOS / Linux / WSL
rm -rf ~/.codex
 
# 或仅清除认证（保留其他配置）
codex logout

注意安全：~/.codex/auth.json 存储 OAuth 令牌或 API Key 明文。卸载前如不打算重装，建议先 codex logout 显式撤销凭证。

OpenAI Codex 已经从单一 CLI 演化为覆盖终端、桌面、IDE、云端、GitHub 的完整 agent 矩阵，包含在 ChatGPT 订阅中的策略大幅降低了使用成本。但安装本身只是入口——真正决定生产力的是后续 AGENTS.md 上下文设计、approval mode 调优、skills 与 plugins 体系搭建以及 MCP 服务器集成。Codex 与 Claude Code 在 agent 工作流上互有取舍——Codex 矩阵更广（覆盖到桌面与 GitHub），Claude Code 更聚焦于命令行——对中文开发者而言两者并存往往比二选一更实用。

本文首发于 LLM 大模型邮报。

Claude Code 安装最简流程：三端命令、自动更新与彻底卸载一次说清

MISTY — Fri, 01 May 2026 21:21:00 +0800

传统的 AI 编码工具往往需要手动配置 Node.js 环境、解决 npm 权限错误、维护 PATH 变量，整个流程对初学者并不友好。Claude Code 作为 Anthropic 推出的命令行 AI 编码助手，2025 年 10 月起官方将原生安装器（native installer）确立为推荐安装方式，零依赖、自动配置 PATH、后台自动更新，把 Claude Code 安装流程压缩到一行命令。

Claude Code 支持 macOS 13.0+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+，覆盖 x64 与 ARM64 主流架构。本指南按”使用价值—系统要求—安装方法—问题排查—验证使用—获取方式”六段，详细说明在不同设备上完成 Claude Code 安装的最简流程，覆盖标准账号、企业部署、第三方推理服务等多种场景。

为什么要使用原生安装器

原生安装器作为 Anthropic 当前的官方推荐方式，相比 npm 等传统路径有几项实际价值：

零依赖部署：不需要 Node.js 运行时，不需要 npm 全局权限配置。一行 curl 或 irm 命令完成下载、PATH 配置与首次启动准备，整个过程通常在 30 秒内结束。

后台自动更新：原生安装是唯一获得 Claude Code 内置更新机制的安装方式。启动时与运行中后台检查新版本，下次启动生效，无需手动维护。Anthropic 官方文档明确指出 Homebrew、WinGet、apt、dnf、apk 与 npm 安装均不参与该机制，这是选择安装路径时最容易被忽略却最关键的差异。

跨平台一致：macOS、Linux、WSL 共用同一条 install.sh 脚本，Windows PowerShell 与 CMD 各有对应版本但安装结果一致，二进制本身在所有平台行为相同。

发布通道可控：通过 autoUpdatesChannel 设置在 latest（即时收到新版本）与 stable（约滞后一周、跳过有重大回退的版本）之间切换。企业部署可追加 minimumVersion 字段防止版本回滚。

统一卸载路径：所有原生安装的二进制都位于 ~/.local/bin/claude（Windows 为 %USERPROFILE%.local\bin\claude.exe），卸载只需删除两个目录，无包管理器残留。

系统要求与前置检查

根据 Claude Code 官方安装文档，运行 Claude Code 需满足以下条件：

操作系统：macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
系统架构：x64 或 ARM64
硬件：4 GB 以上内存
Shell：Bash、Zsh、PowerShell 或 CMD（原生 Windows 推荐安装 Git for Windows 以便调用 Bash 工具）
账号：Claude Pro、Max、Team、Enterprise 或 Anthropic Console（API 计费）账号之一，免费版 Claude.ai 不包含 Claude Code 访问权限
网络：稳定连接到 Anthropic 服务端点，国内用户可能需要配置代理

也可通过 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 接入第三方推理服务，适合企业自有云资源或合规要求场景。

检查是否已安装 Claude Code 的方法：打开终端执行：

claude --version

如果返回版本号（如 2.1.xxx），说明已安装。如果提示 command not found，按下文方法安装。

安装方法

方法一：原生安装器（推荐）

最简单且官方推荐的方式，零依赖、自动 PATH 配置、后台自动更新，覆盖三大平台。

macOS、Linux、WSL，打开终端执行：

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

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

二进制将安装到 ~/.local/bin/claude（Windows 为 %USERPROFILE%.local\bin\claude.exe），PATH 由安装脚本自动配置。完成后运行 claude –version 验证。

区分 PowerShell 与 CMD 的小技巧：提示符为 PS C:\ 是 PowerShell，仅 C:\ 是 CMD。若执行 irm 命令报 ‘irm’ is not recognized，说明当前是 CMD；若执行 CMD 命令报 The token ‘&&’ is not a valid statement separator，说明当前是 PowerShell。

首次启动 claude 时浏览器会自动打开 OAuth 授权页面，登录 Anthropic 账号后令牌本地存储。无浏览器环境（服务器、容器、CI Pipeline）改用环境变量：

export ANTHROPIC_API_KEY=sk-ant-...

方法二：Homebrew（仅 macOS）

适合习惯 Homebrew 工作流的 macOS 用户。Homebrew 提供两个 cask，对应不同发布通道：

# 稳定通道（约滞后一周，跳过有重大回退的版本）
brew install --cask claude-code
 
# 最新通道（新版本发布时立即收到）
brew install --cask claude-code@latest

注意 Homebrew 安装不参与 Claude Code 的后台自动更新，需手动执行 brew upgrade claude-code 或 brew upgrade claude-code@latest。两个 cask 不能同时安装，重新选择通道前需先卸载现有 cask。

方法三：WinGet（仅 Windows）

通过 Windows Package Manager 安装：

winget install Anthropic.ClaudeCode

WinGet 路径有两个已确认的已知问题，部署前需了解：

问题 1：永久”Update available”提示。GitHub Issue 33155 显示 Claude Code 的更新检查比对的是 npm 注册表版本，而 winget 包审核流程比 npm 慢 1-2 个版本，导致 winget 用户长期看到黄色更新横幅但 winget upgrade 报 No applicable update found。当前没有官方修复。

问题 2：升级可能破坏 PATH。GitHub Issue 27867 显示执行 winget upgrade Anthropic.ClaudeCode 后二进制被移到 C:\Users.local\bin\claude.exe 但 PATH 未自动更新，claude 命令找不到。修复方式是在 PowerShell profile 中追加：

$env:PATH += ";$env:USERPROFILE\.local\bin"
. $PROFILE

鉴于这两个问题，Windows 用户除非有强烈包管理器统一偏好，否则建议直接用方法一的 PowerShell 原生安装器。

方法四：Linux 包管理器（apt / dnf / apk）

适合团队规范要求所有软件经包管理器分发的场景。Anthropic 提供官方签名仓库，密钥指纹为 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE，建议在信任前手动校验。

Debian / Ubuntu（apt）：

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
 -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
 | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora / RHEL（dnf）：

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine Linux（apk）：

wget -O /etc/apk/keys/claude-code.rsa.pub \
 https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

将 URL 中的 stable 替换为 latest 即切换到最新通道。这些路径同样不参与 Claude Code 后台自动更新，依赖系统包管理器升级流程。

Alpine 与其他 musl 发行版的额外步骤：原生安装器需先安装 libgcc、libstdc++、ripgrep，并在 ~/.claude/settings.json 中配置：

{
 "env": {
 "USE_BUILTIN_RIPGREP": "0"
 }
}

否则会因 musl 与 glibc 链接器差异导致搜索功能失效。

方法五：npm 安装（仅特定场景适用）

npm 不再是默认推荐方式，仅在 CI/CD 中需要固定版本、团队工作流以 npm 为标准、或与 Node.js 项目共用版本管理时使用：

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

要求 Node.js 18 或更高。该 npm 包安装的与原生安装器是同一个二进制——通过 @anthropic-ai/claude-code-darwin-arm64 等 optional dependency 拉取对应平台 binary，postinstall 阶段链接到 PATH。已安装的 claude 二进制本身不调用 Node.js 运行时。

禁止使用 sudo npm install -g，会导致权限污染与安全风险。遇到 EACCES 错误的正确处理方式是配置用户级 npm prefix：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

或改用 nvm 管理 Node.js 版本。

方法六：Windows 用户的 WSL 路径

WSL 适合需要 Linux 工具链或**沙盒（sandboxing）**命令执行的开发场景。WSL 2 支持沙盒，WSL 1 不支持。原生 Windows 路径与 WSL 路径的选择标准：

原生 Windows：Windows 原生项目与工具链，不支持 sandboxing
WSL 2：Linux 工具链或需要沙盒命令执行，推荐
WSL 1：仅在 WSL 2 不可用时使用

在 WSL 终端内执行方法一的 Linux 安装命令即可。注意所有依赖必须在 WSL 环境内安装而非 Windows 侧——一个常见误区是 Windows 已装 Node.js 但 WSL 内没装，npm 路径会因此报 command not found。

更新方式：每个平台不同，搞错会一直收到提醒

这是 Claude Code 安装中最容易踩坑的环节，不同安装路径的更新机制完全不同：

原生安装器：启动时与运行中后台自动检查，下次启动生效，零干预；可执行 claude update 立即触发
Homebrew：brew upgrade claude-code 或 brew upgrade claude-code@latest（取决于安装的 cask）
WinGet：winget upgrade Anthropic.ClaudeCode
apt：sudo apt update && sudo apt upgrade claude-code
dnf：sudo dnf upgrade claude-code
apk：apk update && apk upgrade claude-code
npm：重新执行 npm install -g @anthropic-ai/claude-code

切换发布通道编辑 ~/.claude/settings.json：

{
 "autoUpdatesChannel": "stable"
}

完全禁用自动更新设置 DISABLE_AUTOUPDATER=1；需彻底封锁包括 claude update 在内所有更新路径时设置 DISABLE_UPDATES，适用于企业自有分发场景。

常见问题排查

问题 1：claude –version 提示 command not found

原因：PATH 未自动更新，或终端会话未重载。

解决方案：

关闭当前终端，开新终端窗口
macOS/Linux 执行 source ~/.zshrc 或 source ~/.bashrc
Windows 关闭并重开 PowerShell 窗口
仍找不到执行 which claude（Linux/macOS）或 where claude（Windows）确认实际路径

问题 2：npm 安装报 EACCES 权限错误

原因：npm 全局目录归 root 所有，或之前用过 sudo 安装。

解决方案：不要使用 sudo。改用方法一的原生安装器，或按方法五配置用户级 npm prefix。

问题 3：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 18+。

解决方案：执行 node –version 检查。低于 18 时通过 nvm install –lts 升级，或改用原生安装器（不需要 Node.js）。

问题 4：Git Bash 报 “Raw mode is not supported”

原因：Git Bash 不完整支持 Claude Code 交互式 CLI 所需的 TTY 功能。

解决方案：在 Windows PowerShell 或 Windows Terminal 中启动 claude。Git for Windows 仅作为 Bash 工具的执行后端，启动 Claude Code 本身应使用 PowerShell。

问题 5：WinGet 永久显示 “Update available”

原因：Claude Code 的更新检查比对的是 npm 注册表版本，与 winget 包注册表存在 1-2 个版本的滞后。

解决方案：当前无官方修复。可忽略提示等待 winget 包追上，或卸载 winget 安装改用方法一的原生安装器。

问题 6：WinGet 升级后 claude 命令找不到

原因：升级后二进制被移动但 PATH 未更新。

解决方案：在 PowerShell profile 中追加 $env:PATH += “;$env:USERPROFILE.local\bin”，执行 . $PROFILE 重载。

问题 7：asdf 用户从 npm 迁移后仍调用旧版本

原因：asdf shim 优先级高于原生安装路径，which claude 仍指向 ~/.asdf/shims/claude。

解决方案：对 asdf 管理过的每个 Node.js 版本逐一卸载：

for version in $(asdf list nodejs | tr -d ' *'); do
 echo "Uninstalling from nodejs $version..."
 ASDF_NODEJS_VERSION=$version npm uninstall -g @anthropic-ai/claude-code 2>/dev/null
done

如果 shim 仍残留，手动删除 ~/.asdf/shims/claude。

问题 8：OAuth 浏览器回调失败

原因：远程 SSH、devcontainer 或严格防火墙环境下 localhost 回调被阻断。

解决方案：使用手动流程——复制终端打印的 URL，在任意浏览器完成登录，将返回码粘贴回终端。或在无浏览器环境直接设置 ANTHROPIC_API_KEY 环境变量。

问题 9：企业网络下载失败或证书错误

原因：下载主机被代理拦截，或公司注入了自己的 CA 证书。

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port 后重新执行安装命令
指向公司 CA 包：export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem
将以上变量加入 shell profile 持久化

问题 10：搜索功能失效或 @file 引用找不到文件

原因：内置 ripgrep 二进制在当前系统不兼容，常见于 Alpine、musl 发行版与部分 ARM 设备。

解决方案：通过包管理器安装 ripgrep（如 apk add ripgrep、apt install ripgrep），并在 ~/.claude/settings.json 设置 USE_BUILTIN_RIPGREP=0。

验证安装与基础使用

安装完成后，建议执行以下命令验证 Claude Code 是否正常工作：

# 检查版本
claude --version
 
# 详细环境检查（PATH、认证状态、MCP 服务器、文件权限）
claude doctor
 
# 启动 Claude Code（首次启动会触发 OAuth 授权）
claude

进入 Claude Code 后可使用以下内置命令：

# 完整健康检查
/doctor
 
# 查看所有 slash 命令
/help
 
# 生成项目级 CLAUDE.md（持久上下文）
/init
 
# 压缩对话历史（释放 context window）
/compact
 
# 清空当前会话
/clear
 
# 查看会话状态与上下文使用量
/status

装完之后的关键三步：

在项目根目录运行 /init 生成 CLAUDE.md，让 Claude Code 持久理解项目结构、技术栈与团队规范——后续每次会话质量都依赖这个文件
在终端内输入 /help 浏览内置 slash 命令清单，了解 /compact、**/clear**、**/status** 等常用工具
通过 ~/.claude/settings.json 配置 **MCP（Model Context Protocol）**服务器，把 Claude Code 从命令行助手扩展为可调用 GitHub、数据库、内部工具的完整 agent 平台

卸载方式：不同安装路径对应不同清理步骤

卸载按安装方式分别处理：

原生安装器（macOS、Linux、WSL）：rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude
原生安装器（Windows PowerShell）：Remove-Item -Path “$env:USERPROFILE.local\bin\claude.exe” -Force 与 Remove-Item -Path “$env:USERPROFILE.local\share\claude” -Recurse -Force
Homebrew：brew uninstall –cask claude-code（或 claude-code@latest）
WinGet：winget uninstall Anthropic.ClaudeCode
apt：sudo apt remove claude-code，删除 /etc/apt/sources.list.d/claude-code.list 与 /etc/apt/keyrings/claude-code.asc
dnf：sudo dnf remove claude-code，删除 /etc/yum.repos.d/claude-code.repo
apk：apk del claude-code，删除仓库行与 /etc/apk/keys/claude-code.rsa.pub
npm：npm uninstall -g @anthropic-ai/claude-code

仅删除二进制并不能完全清理 Claude Code。配置目录 ~/.claude/ 与 ~/.claude.json 包含设置、MCP 服务器配置、会话历史与已授权工具列表，会被保留以便重装。彻底清理执行：

# macOS / Linux / WSL
rm -rf ~/.claude
rm ~/.claude.json
 
# 项目级配置（在每个项目目录下）
rm -rf .claude
rm -f .mcp.json

Windows 对应 %USERPROFILE%.claude 与 %USERPROFILE%.claude.json。

容易被忽略的陷阱：VS Code 扩展、JetBrains 插件与 Claude Desktop 应用都会写入 **~/.claude/**。若它们仍然安装，删除该目录后会被立即重建。彻底清理前必须先卸载所有相关 IDE 集成。

获取方式

官方文档：Claude Code 官方文档

安装与配置参考：Advanced setup

npm 包：@anthropic-ai/claude-code

故障排查中心：Claude Help Center

GitHub Issues：anthropics/claude-code

Claude Code 通过原生安装器把命令行 AI 编码工具的部署门槛压到了一行命令，但安装本身只是入口。对中文开发者而言，真正决定生产力的是后续 CLAUDE.md 上下文设计、MCP 服务器集成与 agent 工作流配置——掌握这些才是 Claude Code 实际价值所在。

本文首发于 LLM 大模型邮报。