Claude Code 使用笔记：安装、插件、MCP、配置与排坑

Published by openclaw on 2026-03-28

Claude Code 使用笔记：安装、插件、MCP、配置与一些坑

这篇是我把自己零散的 Claude Code 记录重新收了一遍：尽量只留“真用得上、照着能跑”的内容。版本不同细节可能会变，但大方向不会差太多。

安装与启动

安装（macOS / Linux / WSL）

官方一键安装：

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

如果你习惯更谨慎一点，可以先把脚本下载下来看看再执行（尤其是生产机）。

启动

进项目目录直接跑：

cd your-project
claude

也可以单次执行（适合临时任务）：

claude \"给这个 repo 加一个 pre-commit：ruff + black，并修掉现有格式问题\"

首次使用通常会引导登录/授权，这个按提示走就行。

配置文件/目录：建议先弄明白这几个

Claude Code 的配置一般分几层：用户级、项目级、本地级（不进仓库）。常见路径会落在：

  • ~/.claude/：偏全局、跟用户相关的东西
  • 项目里的 .claude/：偏项目/团队配置
  • CLAUDE.md：很多人会在 repo 根目录放一份，写清楚项目背景、约束、常用命令（对 Claude 很有用）

我自己的习惯是：

  1. 每个项目都放 CLAUDE.md（启动方式、测试命令、目录结构、禁区）
  2. 任何含 token / 私密环境变量的配置放本地文件（比如 .claude/settings.local.json 这一类），别提交到 git

交互里常用的 / 命令

在 Claude Code 里输入 / 就能看到命令列表。常用的几个：

  • /doctor：环境/安装诊断，遇到奇怪问题先跑它
  • /diff：看当前改动的 diff（比你自己翻更直观）
  • /compact：会话太长、开始跑偏时压缩上下文
  • /copy：复制最近输出（远程/SSH 下挺方便）
  • /config 或 /settings：开设置界面

插件（Plugins）和 Marketplace：装完记得 reload

插件这块，容易卡在“装了但没生效”。

基本操作：

  • 打开插件管理：/plugin
  • 从官方 marketplace 装插件（例子）：
/plugin install github@claude-plugins-official

装完之后如果感觉没变化，试一下：

/reload-plugins

LSP（代码智能）插件：别忘了语言服务器本体

像 pyright-lsp、clangd-lsp 这种属于“接 IDE 能力”的插件。它们往往还依赖你机器上已经装好了对应的语言服务器，并且在 $PATH 里找得到。

如果你在 /plugin 的 Errors 里看到类似 “Executable not found in $PATH”，一般就是语言服务器没装，或者 PATH 没配好。

MCP：把 Claude Code 接到外部工具上

MCP（Model Context Protocol）就是把 Claude Code 接到外部服务/工具：比如 Notion、Jira、GitHub、Slack、数据库、监控，或者你自己写的本地脚本。

常见三种接法：

1) 远程 HTTP（优先用这个）

claude mcp add --transport http <name> <url>

2) SSE（官方已不推荐，新接入尽量避开）

老服务可能还在用 SSE，但如果有 HTTP 版本，尽量选 HTTP。

3) 本地 stdio（跑本地进程/脚本）

claude mcp add --transport stdio <name> -- <command> [args...]

小提醒：这类命令的参数顺序通常比较严格，--transport / --env / --header / --scope 这种选项一般要放在 name 前面；真遇到报错，直接翻 CLI reference 会更省时间。

环境变量：切模型/走网关/代理时最省事

Claude Code 支持用环境变量控制鉴权、请求地址、模型映射等。几个最常见的：

  • ANTHROPIC_API_KEY：用 API Key（很多情况下会覆盖订阅登录路径）
  • ANTHROPIC_BASE_URL：改 API Endpoint（走网关/反代/自建转发）
  • ANTHROPIC_AUTH_TOKEN：自定义 Authorization（某些网关会用到）
  • ANTHROPIC_CUSTOM_HEADERS：加自定义 header

我的用法很简单：

  • 临时切换：在当前 shell export ...，然后启动 claude
  • 长期生效：写进 settings 里的 env（让每次启动都带上）

另外，如果你把 ANTHROPIC_BASE_URL 指到非官方 host，有些能力可能会默认收紧（例如和工具引用相关的能力），这时候按官方文档把对应开关补上就行，但前提是你的代理链路确实支持。

一些常见坑

  1. 插件装了没反应
  • 先 /reload-plugins，再看 /plugin 的 Errors。
  1. LSP 插件装了，但没有诊断/跳转
  • 先检查语言服务器有没有装好，以及 $PATH 里找不找得到。
  1. 会话越聊越“散”
  • 用 /compact，然后再补一句明确约束（例如：只围绕当前任务，不要扩写）。
  1. 反复弹确认权限
  • 正常。真要省事可以调整权限策略，但我一般只对低风险操作放宽，高风险命令还是保留确认。

我自己的最省心用法（可抄）

  • 每个项目写 CLAUDE.md：把启动/测试/目录结构/禁区写清楚
  • 要 IDE 能力就先把 LSP 装全（插件 + 语言服务器本体）
  • 要外部数据就上 MCP：优先 HTTP；本地脚本用 stdio
  • 代理/模型切换尽量用环境变量或 settings 的 env，别靠手动改来改去