首页 › tutorials › 三端打通Claude Code入门

三端打通 Claude Code 入门：终端 + IDE + Web 联动配置全流程

概述

本教程面向第一次接触 Claude Code 的开发者，目标是用一节课的时间打通 Claude Code 的三个工作面：终端 CLI、IDE 插件（VS Code/JetBrains）、Web 端（claude.ai/code）。学完你将掌握：在一台机器上完成安装与认证、搭好"配置三层"（settings.json / 权限 / CLAUDE.md）、让三个界面共享同一份配置与会话，并用一个真实可运行的小项目——Git 历史日报生成器——跑通完整闭环。适合零基础、但希望一开始就建立"工程化配置习惯"的人。

前置条件

一台 macOS / Windows / Linux 电脑，能联网
Node.js 18 及以上（终端 CLI 走 npm 安装时需要）
一个 Anthropic 账号（可用 Claude 订阅或 API Key 登录）
已安装 VS Code（用于演示 IDE 插件联动；JetBrains 系同理）
一个终端模拟器（macOS 自带 Terminal/iTerm，Windows 推荐 WSL 或 PowerShell，Linux 任意）
不需要先懂 Git 进阶命令，但最好有一个带几次提交的本地 Git 仓库用于最后的实战案例

正文：六步打通三端

第 1 步：先认清 Claude Code 的"三个工作面"

很多人以为 Claude Code 只是"一个命令行工具"，这是最大的认知偏差。到 2026 年，它已经是一套多前端、单内核的产品。内核是同一个 Agent 引擎，前端有三个入口：

工作面	形态	典型场景
终端 CLI	`claude` 命令	脚本化、CI/CD、服务器、SSH 远程
IDE 插件	VS Code / JetBrains 扩展	日常写代码、看 diff、跳转
Web 端	claude.ai/code	浏览器里直接开环境、跨设备接力

关键认知：三端共享同一套配置文件、同一套权限规则、同一个登录态。你在终端里写好的 CLAUDE.md 和 settings.json，VS Code 插件会自动读取；Web 端连接到本地环境后也沿用同一份。理解这一点，后面所有的配置动作才不会重复造轮子。

常见问题：三端要分别装、分别登录吗？解答：终端 CLI 和 IDE 插件共用本机登录态，装一次登录一次即可；Web 端是独立的浏览器会话，但可通过"连接本地环境"复用你的项目。

第 2 步：安装终端 CLI（核心入口）

打开终端，执行一条命令完成全局安装：

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

安装完成后，验证版本：

claude --version

预期结果：终端打印出形如 2.x.x 的版本号，表示 CLI 已就绪。

如果你所在网络对 npm 官方源较慢，可临时切换镜像，或使用官方提供的原生安装脚本（无需 Node.js）：

# 原生安装（不依赖 npm，适合服务器/精简环境）
curl -fsSL https://claude.ai/install.sh | bash

常见问题 1：npm: command not found 解答：先安装 Node.js 18+（推荐用 nvm 管理），再重试。

常见问题 2：权限报错 EACCES 解答：不要用 sudo。推荐配置 npm 全局目录到用户家目录，或直接改用原生安装脚本。

常见问题 3：Windows 上 claude 命令找不到解答：确认 npm 全局 bin 目录在 PATH 中；或在 PowerShell 里用 where.exe claude 定位。

第 3 步：首次认证与启动

进入任意目录（建议新建一个练习目录），启动：

mkdir claude-lab && cd claude-lab
claude

首次启动会要求登录。两种方式二选一：

浏览器 OAuth 登录（推荐）：终端给出一个链接，浏览器打开后授权，回终端即登录成功。
API Key 方式：设置环境变量后启动，适合无图形界面的服务器。

# API Key 方式（无头环境）
export ANTHROPIC_API_KEY="sk-ant-xxxxxx"
claude

启动后进入交互式 REPL，提示符变为 >。先认识几个"保命命令"：

/help        # 查看所有命令
/config      # 打开图形化设置面板（标签式）
/init        # 让 Claude 扫描当前项目并生成 CLAUDE.md
/clear       # 清空当前会话上下文
/compact     # 压缩上下文（长会话省钱利器）
/cost        # 查看本次会话 token 消耗
/model       # 切换模型

预期结果：在 REPL 里输入一句"介绍一下你自己能做什么"，能正常得到回复，说明认证与会话链路全通。

常见问题：登录后仍提示未授权解答：检查系统时间是否正常（OAuth 对时间敏感）；企业网络代理可能拦截回调，尝试切换网络或配置 HTTPS_PROXY。

第 4 步：搭好"配置三层"——Claude Code 的灵魂

这一步是把 Claude Code 从"玩具"变成"工程化工具"的关键。配置分三层，优先级从高到低：

用户级 ~/.claude/settings.json——所有项目通用的全局偏好
项目级（共享） <项目>/.claude/settings.json——随仓库提交、团队共享
项目级（本地） <项目>/.claude/settings.local.json——个人私有，应加入 .gitignore

加上两个"记忆体"：

CLAUDE.md——自然语言写成的项目说明书，放在项目根目录，Claude 每次启动自动读取
会话内 # 快速记忆——输入以 # 开头的一句话，会被写入记忆

下面给一份可直接复用的最小配置。先用 /config 面板看一眼，再手动编辑文件更可控。

<项目>/.claude/settings.json（团队共享，提交到 Git）：

{
  "permissions": {
    "allow": [
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git status:*)",
      "Bash(npm test:*)",
      "Read(**)",
      "Edit(src/**)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm install:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/*.key)"
      ]
  }
}

<项目>/.claude/settings.local.json（个人私有，不提交）：

{
  "permissions": {
    "allow": ["Bash(open:*)", "Bash(code:*)"]
  }
}

权限语义解读：

allow：命中即自动放行，不再弹确认
ask：命中即弹确认，你来决定
deny：命中即硬拒绝，连问都不问

权限语法是 工具名(匹配规则)，支持通配符 *。例如 Bash(git log:*) 表示允许任何 git log 开头的命令；Read(.env) 表示禁止读取 .env。

权限模式（permissionMode）四档，可在 settings.json 或运行时指定：

模式	行为	适用
`default`	命中 allow 放行，其余询问	日常开发
`acceptEdits`	自动接受文件编辑	批量重构
`plan`	只规划不执行	方案评审
`bypassPermissions`	全部放行（危险）	仅信任的沙箱

常见问题：每次都弹一堆确认，烦死了解答：把高频只读/安全命令加进 allow；把危险命令加进 deny。目标是把"确认疲劳"降到接近零，又不裸奔。

再写一个最小 CLAUDE.md（项目根目录）：

# 项目说明

本项目是练习 Claude Code 三端联动的沙箱。

## 约定
- 所有脚本放在 `scripts/` 目录
- 输出报告统一写为 Markdown，放 `reports/`
- 命令必须幂等，重复运行不报错
- 不要提交 .env 和 *.key

执行 /init 可让 Claude 自动扫描代码库生成一份更完整的 CLAUDE.md，再手动微调即可。

第 5 步：装 IDE 插件并联动

打开 VS Code，进入扩展商店，搜索 "Claude Code"（Anthropic 官方），安装。

安装后两种唤起方式：

快捷键：Ctrl+Esc（macOS 为 Cmd+Esc）从编辑器内唤出 Claude 面板
命令面板：Ctrl+Shift+P 输入 Claude Code: Open

预期结果：面板内出现与终端一致的交互界面，且自动读取了第 4 步写好的 settings.json 与 CLAUDE.md——无需重新配置。选中编辑器里的一段代码，让 Claude"解释这段代码"或"加注释"，它会带着当前文件上下文作答。

常见问题 1：插件提示找不到 claude 命令解答：插件依赖本机已安装的 CLI。确认 claude --version 在终端能跑通，且 PATH 对 GUI 应用可见（macOS GUI 应用的 PATH 可能与终端不同，重启 VS Code 通常解决）。

常见问题 2：插件和终端的会话是同一个吗？解答：不是同一个会话实例，但共享配置。你可以在终端开长任务、在 IDE 里做小修改，互不干扰。

第 6 步：用 claude.ai/code Web 端接力

浏览器访问 claude.ai/code，登录同一账号。Web 端的价值在于"跨设备接力"和"零安装体验"：你可以在公司电脑的 VS Code 里改了一半的代码，回家用浏览器打开 Web 端继续。

让 Web 端连到你本地项目的典型路径：在 VS Code 插件或 CLI 中触发"连接到 claude.ai"，浏览器扫码确认后，Web 端即可看到该会话。

预期结果：Web 端能看到本地会话历史，配置与权限规则与本机一致。

常见问题：Web 端能直接改我电脑上的文件吗？解答：需要通过连接本地环境（CLI/插件作为桥梁）才可操作本机文件；纯 Web 沙箱环境则是隔离的云端空间。

实战案例：Git 历史日报生成器

现在用一个完整项目串起三端。目标：读取当前 Git 仓库的提交历史，自动生成一份 Markdown 每日开发报告。这个项目天然适合 Claude Code——它需要读文件、跑命令、写报告，三端都能驱动。

0. 准备仓库

mkdir git-daily && cd git-daily
git init
echo "# Git Daily Report" > README.md
git add . && git commit -m "init: 项目初始化"
# 再随便造几条提交
echo "v1" >> README.md && git commit -am "docs: 更新 README"

1. 启动 Claude Code

claude

2. 一句话下需求

在 REPL 里输入（可直接复制）：

请帮我写一个 Python 脚本 scripts/git_daily.py：
1. 调用 git log 获取"今天"的所有提交（按作者分组）
2. 统计每个作者的提交数、改动文件数
3. 输出为 reports/REPORT-<日期>.md，使用 Markdown 表格
4. 运行后自动用默认编辑器打开报告
要求幂等：reports 目录不存在时自动创建。

3. 预期产出

Claude 会创建 scripts/git_daily.py，内容大致如下（它会按你的 CLAUDE.md 约定放对目录）：

#!/usr/bin/env python3
"""生成每日 Git 开发报告。幂等：目录不存在自动创建。"""
import subprocess, datetime, os, pathlib

REPO = pathlib.Path(__file__).resolve().parent.parent
REPORTS = REPO / "reports"
TODAY = datetime.date.today().isoformat()

def run(cmd):
    return subprocess.run(cmd, cwd=REPO, capture_output=True, text=True).stdout

def main():
    REPORTS.mkdir(exist_ok=True)  # 幂等
    # 取今日提交：作者|提交hash|标题
    raw = run(["git", "log", "--since=midnight",
               "--pretty=format:%an|%h|%s"])
    from collections import defaultdict
    by_author = defaultdict(list)
    for line in raw.strip().splitlines():
        if "|" in line:
            author, h, title = line.split("|", 2)
            by_author[author].append((h, title))

    files = run(["git", "log", "--since=midnight",
                 "--name-only", "--pretty=format:"]).split()

    lines = [f"# 每日开发报告 {TODAY}", "",
             f"- 提交作者数：{len(by_author)}",
             f"- 改动文件数：{len(set(files))}", "",
             "## 提交明细", "",
             "| 作者 | 提交数 | 提交列表 |",
             "|------|--------|----------|"]
    for author, commits in by_author.items():
        titles = ", ".join(f"`{h}` {t}" for h, t in commits)
        lines.append(f"| {author} | {len(commits)} | {titles} |")

    out = REPORTS / f"REPORT-{TODAY}.md"
    out.write_text("\n".join(lines), encoding="utf-8")
    print(f"✅ 报告已生成：{out}")
    # 自动打开（macOS=open / Windows=默认 / Linux 可按需调整）
    opener = "open" if os.name != "nt" else os.startfile
    if os.name == "nt":
        os.startfile(out)
    else:
        subprocess.run([opener, str(out)])

if __name__ == "__main__":
    main()

4. 运行验证

在终端执行：

python3 scripts/git_daily.py

因为你在 settings.json 里已经 allow 了 Bash(git log:*) 和 Read(**)，所以这一步不会反复弹确认。

5. 三端接力演示

终端 CLI：跑上面的命令，看报告生成。
VS Code 插件：选中 git_daily.py，对 Claude 说"给这个脚本加类型注解和单元测试"，它会就地修改并在编辑器里高亮 diff。
Web 端：连上本地后，在浏览器里继续说"把报告里加上'本周累计提交数'一列"，改完在终端复跑即可。

6. 常见问题

报告为空：仓库今日没有提交，--since=midnight 换成 --since="1 week ago" 验证脚本逻辑。
git 命令失败：确认在仓库目录内运行，或确认 git 已加入 PATH。
中文乱码：读写统一用 encoding="utf-8"（脚本已处理）。

工作流程图：三端如何协同

flowchart TB
    subgraph 内核["Claude Code Agent 引擎（单一内核）"]
        ENGINE[配置解析 + 权限裁决 + 工具调用]
    end

    subgraph 配置层["配置三层（共享）"]
        S1["~/.claude/settings.json<br/>用户全局"]
        S2[".claude/settings.json<br/>项目共享"]
        S3[".claude/settings.local.json<br/>个人私有"]
        MD["CLAUDE.md<br/>项目记忆"]
    end

    CLI["终端 CLI<br/>claude 命令"] --> ENGINE
    IDE["IDE 插件<br/>VS Code / JetBrains"] --> ENGINE
    WEB["Web 端<br/>claude.ai/code"] --> ENGINE

    S1 --> ENGINE
    S2 --> ENGINE
    S3 --> ENGINE
    MD --> ENGINE

    ENGINE -->|读文件/跑命令/写报告| FS[本机文件系统与 Git 仓库]

    style ENGINE fill:#fde68a,stroke:#b45309,stroke-width:2px
    style MD fill:#bbf7d0,stroke:#15803d

核心结论：前端换皮，内核不变，配置一份。所以你的精力应花在配好 settings.json 和 CLAUDE.md 上，而不是在三端各配一遍。

训练营适用性评估

维度	说明
适合训练营类型	通用开发者入门营、前端/后端/DevOps 工程效能营、AI 辅助编程训练营
难度	★★☆☆☆（零基础可上手，配置层需一点点耐心）
建议时长	讲授 45 分钟 + 动手实验 60 分钟，合计约 2 课时
前置依赖	无（自带 Node.js 安装环节）
可考核产出	学员提交一个含 `settings.json` + `CLAUDE.md` + 可运行脚本的小仓库
延伸作业	把日报生成器升级为"周报 + 月报"，并接入 GitHub Actions 定时运行（衔接后续 CI 章节）
不适合	纯非技术受众；对命令行完全抵触者建议先用 Web 端体验再回头装 CLI

参考来源

Quickstart - Claude Code Docs — 官方快速上手指南，安装与首条命令
How to Install Claude Code: Complete Setup Guide (2026) — npm/原生安装与系统要求
Claude Code settings - Claude Code Docs — settings.json 分层与环境变量权威说明
Configure permissions - Claude Code Docs — allow/ask/deny 权限规则与四种模式
Getting Started with Claude Code in 2026: Setup to First Commit — 从安装到首次提交的五步实战

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

51学通信知识星球海报-扫码加入