本文由Claude code+DeepSeek-V4-Flash编写

为什么这么做？

1. Claude 账号风险太高

Claude 官方对账号的风控比较严格，尤其是国内用户，经常遇到莫名其妙的封号、IP 限制、支付卡被拒等问题。与其提心吊胆地养号，不如直接用国内大模型做底层引擎。DeepSeek 注册门槛低、无封号焦虑，用起来踏实。

2. API 费用极其便宜

DeepSeek V4 的 API 定价比 Claude 官方 API 便宜一到两个数量级。配合 Claude Code 的本地编辑模式，日常开发场景下 token 消耗可控，成本几乎可以忽略不计。不用再盯着用量生怕超支。

3. claude-mem 插件的优势：上下文管理，省 token

Claude Code 本身每次会话都是一次性的，切到新会话后之前的上下文就丢了。claude-mem 解决了这个痛点：

• 跨会话记忆：上次聊到哪、改过什么文件、做过什么决策，下次打开都能 recall
• 节省 token：不需要每次手动粘贴背景信息，claude-mem 自动注入最相关的上下文，减少了冗余 prompt 的 token 消耗
• 渐进式召回：按需检索，不会一股脑把全部历史塞进上下文，精确控制 token 开销

三层加起来的效果就是：低风险 + 低成本 + 有记忆，日常编码体验比纯原版 Claude Code 还舒服。

DeepSeek 也提供了 Anthropic 兼容 API，可以直接把 Claude Code 的底层模型换成 DeepSeek V4，同时再装上 claude-mem 插件让 Claude 拥有跨会话的持久记忆。整个过程很简单，记录一下。

一、获取 DeepSeek API Key

首先去 DeepSeek 开放平台 注册账号。

注册后在左侧导航栏找到 API Keys，点击 Create new secret key，给 Key 取个名字，创建后复制并保存好（弹窗关了就看不到了）。

API 模型价格如下（限时优惠）

API Key 的使用地址（Anthropic 兼容模式）：

https://api.deepseek.com/anthropic

参考官方文档：https://api-docs.deepseek.com/zh-cn/

二、 更新 Claude Code

如果你是 Windows 环境，可以直接用 winget 更新：

winget upgrade Anthropic.ClaudeCode
或
winget install Anthropic.ClaudeCode

更新过程如下：

更新完成后，建议先确认一下版本：

claude --version

我这边更新后的版本如下：

三、配置 Claude Code 的 settings.json

Claude Code 的配置文件位置一般在：

C:\Users\你的用户名\.claude\settings.json

找到 Claude Code 的配置文件 settings.json，填入以下内容：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<你的 DeepSeek API Key>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash[1m]",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  },
  "model": "opus"
}

关键点说明：

保存后重启 Claude Code，模型就切换完成了。

注意： [1m] 后缀是模型标识的一部分，不要去掉。模型 deepseek-chat 和 deepseek-reasoner 将在 2026 年 7 月 24 日弃用，推荐直接使用 V4 系列。

三、安装 claude-mem 持久记忆插件

claude-mem 是一款让 Claude Code 拥有跨会话持久记忆的开源插件，它会自动记录你的操作并生成语义摘要，在后续会话中注入相关上下文。

安装方式一：通过 Claude Code 插件市场

在 Claude Code 会话中依次执行：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
/reload-plugins

安装方式二：一行命令安装（推荐）

npx claude-mem install

安装后的检查

确认插件正常工作：

# 查看记忆数据库中的记录数
sqlite3 ~/.claude-mem/claude-mem.db "SELECT count(*) FROM observations;"

# 健康检查
curl http://localhost:37777/health

如果记录数 > 0，说明已经在工作了。

常见踩坑

1. 安装范围选”为本用户安装”，不要选 project 或 local
2. Worker 起不来？ 检查 Bun 是否正常安装，可以手动装一下
3. 默认模型不对？ 修改 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_MODEL": "sonnet",
  "CLAUDE_MEM_MODE": "code--zh"
}

4. 修改配置后重启 worker：

cd ~/.claude/plugins/marketplaces/thedotmack
npm run worker:restart

四、最终效果

配置完成后，你的 Claude Code 变成了：

• 引擎： DeepSeek V4 模型（Pro 负责推理、Flash 负责快速响应）
• 记忆： claude-mem 提供跨会话上下文（打开 Web UI http://localhost:37777 可以实时查看记忆流）
• 成本： DeepSeek API 价格远低于原版 Claude API

参考资料

• DeepSeek API 官方文档
• DeepSeek 开放平台
• claude-mem GitHub
• claude-mem 中文安装指南

用 DeepSeek 模型驱动 Claude Code + 安装 claude-mem 持久记忆插件最先出现在Liao's blog。

本篇博文由Codex生成

如果刚开始接触智能体，一个很常见的问题是：概念都能听懂，但落到代码时还是不知道“智能体到底是怎么跑起来的”。这篇文章就用一个极小的本地项目 travel_agent_demo 来回答这个问题，并把它和 Datawhale《Hello Agents》第一章 1.3 小节“动手体验：5 分钟实现第一个智能体”对应起来。

这个项目很适合入门了解，因为它没有依赖复杂框架，而是把智能体最核心的三件事直接摊开：

• 大模型负责理解任务和决定下一步动作
• Python 函数负责充当外部工具
• 一个循环负责执行 Thought -> Action -> Observation

本地使用的环境是：

• Python 3.11.3
• Ollama
• gemma4:31b
• tavily_key

参考资料：

• Datawhale 原文

一、先看整体：这个智能体的结构与调用流程

Datawhale 1.3 小节的目标很明确：先写一个最小可运行 Agent，再通过它理解 Thought-Action-Observation 范式。当前这个 travel_agent_demo 项目正好就是这一思路的本地版实现。

项目结构只有 4 个核心文件：

• config.py：定义系统提示词和模型配置
• tools.py：定义工具函数
• llm_client.py：封装 OpenAI 兼容接口
• agent.py：驱动整个行动循环

它的调用流程可以概括成下面这张图：

用户输入需求
   |
   v
agent.py 收集上下文并组装 Prompt
   |
   v
llm_client.py 调用本地 Ollama / gemma4:31b
   |
   v
模型输出 Thought + Action
   |
   +---- 如果 Action 是工具调用 ----> tools.py 执行函数
   |                                     |
   |                                     v
   |                              返回 Observation
   |
   v
agent.py 把 Observation 追加回上下文
   |
   v
模型继续下一轮推理
   |
   v
输出 Finish[最终答案]

如果换成更工程化的说法，这个项目实际上由三层组成：

1. 协议层：用提示词规定模型必须输出 Thought 和 Action
2. 执行层：Python 代码解析 Action 并调用工具
3. 反馈层：把工具结果作为 Observation 继续喂给模型

这正是 Datawhale 1.3 里最想让初学者建立起来的认知：智能体不是“会聊天的大模型”，而是“能在循环里做决策并调用工具的大模型程序”。

二、环境准备

1. Python 和依赖

项目依赖很少，requirements.txt 里只有 4 个包：

openai
requests
tavily-python
python-dotenv

安装方式：

python -m pip install -r requirements.txt

这里每个依赖的作用都很明确：

• openai：访问 OpenAI 兼容接口，这里用来对接 Ollama
• requests：请求天气接口 wttr.in
• tavily-python：做网页搜索
• python-dotenv：从 .env 自动加载环境变量

2. 本地模型环境

你本地已经准备好了 ollama 和 gemma4:31b，所以 LLM 侧不需要再展开安装过程。这个项目只要求 Ollama 提供 OpenAI 兼容接口即可。

推荐先确认模型已经就绪：

ollama list

如果 gemma4:31b 已经存在，就可以直接继续下面的配置。

3. 配置 .env

项目启动时会在 config.py中自动执行 load_dotenv()，因此只需要在项目根目录准备 .env 文件即可。

建议配置如下：

LLM_API_KEY=ollama
LLM_BASE_URL=http://127.0.0.1:11434/v1
LLM_MODEL=gemma4:31b
TAVILY_API_KEY=你的_tavily_key

这里有两个细节值得写进博客：

• LLM_API_KEY 对本地 Ollama 通常只是占位符，填 ollama 即可
• 项目默认值里 LLM_BASE_URL 是 http://192.168.1.201:11434/v1，如果是本机运行，更推荐改成 http://127.0.0.1:11434/v1

4. 环境准备的现实限制

这个项目并不是所有功能都只靠本地模型：

• get_weather() 通过 wttr.in 查天气，需要能访问外网
• web_search() 和 get_attraction() 依赖 Tavily，需要 TAVILY_API_KEY

也就是说：

• 只测模型输出格式，不一定需要 Tavily
• 想完整复现“天气 -> 景点推荐 -> 最终回答”的链路，最好配置 Tavily

三、对照 Datawhale 1.3：这个项目的每个代码块在做什么

Datawhale 1.3 大致分成三步：

1. 定义系统提示词
2. 定义工具
3. 执行行动循环

本项目几乎就是这个结构的直接映射。

1. config.py：对应 1.3 的“定义 Agent 提示词”

config.py 里的 AGENT_SYSTEM_PROMPT 是整个智能体的协议中心。

它做了四件关键事情：

• 明确角色：你是一个“智能旅行助手”
• 明确工具：告诉模型有哪些函数可调用
• 明确格式：每次只能输出一组 Thought 和 Action
• 明确结束条件：信息足够时必须输出 Finish[...]

对应代码位置：

• 角色与任务定义：config.py:14
• 工具清单：config.py:16
• 输出格式约束：config.py:26
• 结束条件与错误处理要求：config.py:35

这一块和 Datawhale 1.3 的核心思想完全一致。智能体之所以“可执行”，不是因为模型自己知道该怎么做，而是因为我们先定义了一个稳定的动作协议。

2. tools.py：对应 1.3 的“定义工具函数”

tools.py是这个项目和外部世界交互的地方。对智能体来说，工具就是“能力边界的延伸”。

get_weather(city: str)

入口在 tools.py:13。

它的作用是：

• 访问 https://wttr.in/{city}?format=j1
• 读取返回 JSON
• 提取天气描述和温度
• 组装成模型容易理解的字符串

这一段可以理解为 Datawhale 1.3 里“天气查询工具”的本地可运行版。

web_search(query: str)

入口在 tools.py:31。

它的作用是：

• 通过 _get_tavily_client() 获取 Tavily 客户端
• 调用 Tavily 搜索网页
• 把返回的摘要、标题、链接和内容截断后整理成文本
• 作为 Observation 返回给模型

为什么这里要手动整理结果，而不是把 Tavily 原始 JSON 直接塞回模型？原因很简单：原始结果太长、噪声太多，而智能体更需要“可读的摘要”。这也是 Prompt 工程和工具工程结合的典型做法。

get_attraction(city: str, weather: str)

入口在 tools.py:76。

这个函数很巧妙，它本身不直接做景点推荐，而是：

• 根据 城市 + 天气 组装查询词
• 复用 web_search() 去搜索“适合当前天气的旅游景点推荐及理由”

这和 Datawhale 1.3 中“根据天气再推荐景点”的第二步完全一致，只是这里把“景点推荐工具”实现成了“带业务语义的搜索封装”。

AVAILABLE_TOOLS

tools.py:82 把全部工具注册成字典：

AVAILABLE_TOOLS = {
    "get_weather": get_weather,
    "get_attraction": get_attraction,
    "web_search": web_search,
}

这一步的意义是把“模型输出的动作字符串”映射成“程序里真实可执行的函数”。没有这层映射，模型就只是说了一个动作名字，程序并不知道该调用谁。

3. llm_client.py：对应 1.3 的“定义 LLM 客户端”

llm_client.py:4 只有一个很小的封装类 OpenAICompatibleClient，但它的作用非常关键：把本地 Ollama 包装成一个统一的“模型调用接口”。

核心逻辑有三步：

• 初始化时记录 model、api_key、base_url
• 调用 chat.completions.create()
• 传入 system prompt 和当前轮次的 user prompt

对应代码位置：

• 初始化客户端：llm_client.py:7
• 发起模型请求：llm_client.py:11
• 超时控制 timeout=60：llm_client.py:20

这部分和 Datawhale 1.3 的思路也一致：不要把模型调用散落在业务代码里，而是先包成一个可复用组件，后面主循环只负责“何时调模型”，不用关心底层细节。

4. agent.py：对应 1.3 的“执行行动循环”

真正体现 Agent 味道的地方在 agent.py:26

这一段建议在博客里重点展开，因为它就是 Datawhale 1.3 里最核心的执行闭环。

第一步：初始化模型和上下文

在 agent.py:27 到 agent.py:34 中，程序做了两件事：

• 创建 OpenAICompatibleClient
• 初始化 prompt_history = [f"用户请求: {user_prompt}"]

这一步的作用是把“用户目标”变成第一轮推理的上下文。

第二步：进入多轮循环

agent.py:36 开始进入 for i in range(max_turns)。

这是典型的 Agent 调度器做法：

• 每一轮都让模型思考一次
• 每一轮最多执行一个动作
• 直到任务完成或达到最大轮数

这也对应 Datawhale 1.3 里反复强调的循环思路，而不是“一次提问，一次回答”的普通聊天模式。

第三步：构造本轮 Prompt

在 agent.py:38，程序通过：

full_prompt = "\n".join(prompt_history)

把历史上的用户请求、模型动作、工具观察结果全部拼起来，形成当前轮次完整上下文。

为什么要这么做？因为模型不会自动记得上一轮工具执行了什么。你必须显式把历史传回去，它才能基于新观察继续规划下一步。

第四步：调用模型生成 Thought + Action

agent.py:39 调用：

llm_output = llm.generate(full_prompt, system_prompt=AGENT_SYSTEM_PROMPT)

这正是 Datawhale 1.3 里的“让模型先思考，再给出行动”。

紧接着 agent.py:41 到 agent.py:47又做了一层截断处理，目的是防止模型一次性吐出多组 Thought/Action。这属于很实用的工程兜底，说明这个项目已经开始考虑真实模型输出的不稳定性，而不是只停留在理想示例。

第五步：解析 Action

agent.py:52到 agent.py:67先判断当前输出里是否存在 Action:，然后继续区分两类情况：

• 如果是 Finish[...]，说明任务完成，直接返回最终答案
• 如果不是 Finish[...]，就继续解析工具名和参数

其中工具名和参数的提取逻辑被单独封装在 agent.py:8 的 parse_action() 里。这个函数用正则把：

get_weather(city="北京")

解析成：

• 工具名 get_weather
• 参数字典 {"city": "北京"}

这一步就是把“语言动作”翻译成“程序动作”。

第六步：执行工具

agent.py:69 到 agent.py:78 负责真正调用工具：

• 先通过 parse_action() 解析动作
• 再到 AVAILABLE_TOOLS 里查找对应函数
• 最后执行函数并拿到结果

这一段是整个 Agent 最关键的分界线：从这里开始，模型不再只是“生成文本”，而是真的触发了外部能力。

第七步：把工具结果回填为 Observation

agent.py:80 到 agent.py:83会把工具结果包装成：

Observation: ...

然后重新放回 prompt_history。

这一步就是 Thought-Action-Observation 闭环中最不能缺的一环。没有 Observation，模型就不知道刚才的行动产生了什么结果，也就无法进行下一轮更合理的决策。

第八步：控制上下文长度

和 Datawhale 1.3 的教学示例相比，这个项目多做了一点更贴近真实场景的优化：agent.py:19 定义了 summarize_observation()，在 agent.py:83 处对过长的观察结果进行截断。

这背后的原因很实际：

• 工具返回内容可能很长
• 上下文越长，本地模型越慢
• 多轮对话里如果不控制上下文，很容易拖垮响应速度

对于本地 gemma4:31b 这种大模型来说，这个小优化是有价值的。

四、把这个项目映射回 Datawhale 1.3，可以怎么理解

如果只保留最关键的对应关系，可以总结成下面这张表：

所以这篇博客其实可以给读者一个很直接的结论：

Datawhale 1.3 不是一个“抽象案例”，而是一个可以直接投影到真实项目结构里的最小 Agent 模型。

五、怎么启动这个项目

启动步骤很短

1. 安装依赖

python -m pip install -r requirements.txt

2. 准备 .env

LLM_API_KEY=ollama
LLM_BASE_URL=http://127.0.0.1:11434/v1
LLM_MODEL=gemma4:31b
TAVILY_API_KEY=你的_tavily_key

3. 确认 Ollama 正在提供服务

如果你本地已经正常运行 Ollama，这一步一般不需要额外操作。只要 LLM_BASE_URL 对应的接口可访问即可。

4. 运行 Agent

python agent.py

运行后终端会提示：

请输入你的需求:

这时可以输入例如：

帮我看一下贵阳的天气，并推荐一下热门的商圈

5. 终端里会发生什么

执行时你通常会看到类似下面的过程：

1. 模型先输出 Thought 和 Action
2. 如果 Action 是 get_weather(...)，程序就去查天气
3. 天气结果以 Observation 的形式回填
4. 模型再决定是否调用 get_attraction(...) 或 web_search(...)
5. 信息足够后，模型输出 Finish[...]
   这就是一个标准的最小智能体启动过程。

六、写在最后：为什么说它是“第一个智能体”，而不只是一个脚本

很多初学者第一次写这类程序时，会觉得它不过是“模型 + 函数调用”。但从 Agent 视角看，它已经具备了最基本的自主决策结构：

• 它会先判断下一步做什么
• 它会根据当前任务选择工具
• 它会利用工具结果更新自己的后续决策
• 它会在信息足够时主动结束任务

这就是智能体的最小闭环。

当然，这个项目还不是一个完整产品，它还缺少很多更高级的能力，比如长期记忆、重试机制、结构化函数调用、预算约束和更复杂的旅行规划。但作为“第一个智能体”的博客案例，它已经足够合理，甚至比直接上框架更适合入门。

如果要用一句话总结这个项目，我会写成：

travel_agent_demo 的价值不在于功能多复杂，而在于它把 Datawhale 1.3 中“提示词 + 工具 + 行动循环”的智能体最小结构，用本地 Ollama 和 gemma4:31b 真实跑通了。

项目demo地址下载

5 分钟实现第一个Agent智能体：结合Hello agents实现最先出现在Liao's blog。

TL;DR：手把手带你从零安装 Claude Code，并在 VSCode 里解锁最强 AI 编程体验。

前言

Claude Code 是 Anthropic 推出的 CLI 工具，它不只是代码补全——它能读懂整个项目上下文、自主修改文件、执行命令、跑测试，像一个真正的结对编程伙伴坐在你的终端里。

配合 VSCode 扩展，你会得到一个无缝嵌入编辑器的 AI Agent。

环境准备

前置依赖

检查当前环境：

node -v
npm -v

安装 Claude Code

全局安装 CLI

npm（通用，所有平台）：

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

WinGet（Windows，我使用的）：

winget install Anthropic.ClaudeCode

Homebrew（macOS / Linux）：

brew install claude

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

安装完成后验证：

claude --version

🚨 国内用户必读：代理配置

问题根源：Anthropic 屏蔽了来自中国 IP 的 API 访问，影响所有环节——OAuth 登录、API 调用、CLI 和 VSCode 扩展。即使拥有付费的 Claude Max 订阅，从中国 IP 发出的请求一律返回 403。必须先配置代理，再启动 Claude Code。

常见报错：

OAuth error: Failed to fetch user roles: Request failed with status code 403

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST
Note: Claude Code might not be available in your country.

以 v2rayN 为例（设置里查看端口，默认本地代理端口 10808，clash默认端口改为7890），需将 HTTPS_PROXY 环境变量指向本地代理。

临时设置（仅当前窗口有效）

CMD：

set HTTPS_PROXY=http://127.0.0.1:10808

PowerShell：

$env:HTTPS_PROXY = "http://127.0.0.1:10808"

设置后在同一窗口直接运行 claude 即可。

永久设置（推荐，重启后仍有效）

方式一：图形界面（新手推荐）

1. Win + I → 搜索「高级系统设置」→ 点击「环境变量」
2. 在「用户变量」区域点击「新建」
3. 变量名：HTTPS_PROXY，变量值：http://127.0.0.1:10808
4. 确定保存，重新打开命令行窗口生效

方式二：命令行一键设置

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:10808", [EnvironmentVariableTarget]::User)

执行后重新打开命令行窗口即可，无需重启电脑。

验证是否生效

:: CMD
echo %HTTPS_PROXY%

# PowerShell
echo $env:HTTPS_PROXY

输出 http://127.0.0.1:10808 即为设置成功，之后再启动 Claude Code。

启动 Claude Code

进入你的项目目录，直接启动：

cd your-project
claude

弹出以下提示，选择 1 即可继续：

Accessing workspace: C:\Users\...
Quick safety check: Is this a project you created or one you trust?
❯ 1. Yes, I trust this folder
  2. No, exit
Enter to confirm · Esc to cancel

若遇到连接报错。

Unable to connect to Anthropic services  
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST  
Please check your internet connection and network settings.  
Note: Claude Code might not be available in your country. Check supported countries at https://anthropic.com/supported-countries

Windows下操作:

按下键盘 Win + R 键，输入 cmd 后回车，打开命令行程序
在命令行中运行以下命令后回车

powershell -Command "f='%USERPROFILE%\.claude.json';j=Get-Content f|ConvertFrom-Json;j|Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue true -Force;j|ConvertTo-Json|Set-Content $f"

重启你的Claude Cli

首次启动会有简短的引导流程，授权完成后即可使用。

VSCode 扩展安装与配置

安装扩展

打开 VSCode，按 Ctrl+Shift+X 打开扩展市场，搜索：

Claude Code

找到 Anthropic 官方发布的扩展，点击 Install。

或者直接通过命令行安装：

code --install-extension anthropic.claude-code

扩展功能一览

安装完成后，你将解锁以下能力：

• 内嵌聊天面板 — 不离开编辑器，直接和 Claude 对话
• 选中代码提问 — 高亮代码后右键，发送给 Claude 分析
• 差异视图 — Claude 的修改建议以 diff 形式展示，一键接受或拒绝
• 终端集成 — Claude 可直接在 VSCode 内置终端执行命令

核心用法速查

基础对话

# 启动交互式会话
claude

# 单次提问（非交互模式）
claude -p "解释一下这个项目的架构"

常用快捷指令

在 Claude Code 会话中，输入 / 触发命令列表：

让 Claude 读懂你的项目

在项目根目录启动 Claude，进入交互式会话后执行：

/init

这会生成一个 CLAUDE.md，你可以在里面写：

• 项目架构说明
• 技术栈约定
• 代码风格要求
• 不希望 Claude 修改的文件

Claude 每次启动都会自动读取这个文件。

VSCode 进阶配置

settings.json 推荐配置

打开 Ctrl+Shift+P → Open User Settings (JSON)，添加：

{
  "terminal.integrated.defaultProfile.windows": "Git Bash"
}

其他 Claude Code 相关选项可在 VSCode 设置页（Ctrl+,）搜索 claude-code 查看完整列表，按需开启。

自定义键位绑定

打开 Ctrl+Shift+P → Open Keyboard Shortcuts (JSON)：

[
  {
    "key": "ctrl+shift+a",
    "command": "claude-code.openChat"
  },
  {
    "key": "ctrl+shift+r",
    "command": "claude-code.reviewSelection"
  }
]

权限模式说明

Claude Code 在执行文件读写、命令时会请求权限，分三种模式：

Hooks 机制（进阶）

Claude Code 支持配置 Hooks，在特定事件触发时执行自定义脚本。

编辑 ~/.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[HOOK] 即将执行 Bash 命令'"
          }
        ]
      }
    ]
  }
}

可以用来：审计命令执行、拦截危险操作、记录日志。

常见问题排查

Q：claude: command not found

# 检查 npm 全局安装路径是否在 PATH 中
npm config get prefix
# 将 {prefix}/bin 加入 PATH

Q：403 / 无法连接 Anthropic 服务（国内常见）

先配置代理，参考上方「国内用户必读」章节。代理配置完成后，在同一终端窗口再次执行 claude。

Q：VSCode 扩展无法连接

代理环境变量必须在启动 VSCode 的终端中生效，或永久写入系统环境变量，VSCode 扩展才能继承代理设置。确认终端中 claude 命令可以正常执行后，重启 VSCode。

小技巧 & 最佳实践

• 用 CLAUDE.md 约束行为：写明”不要修改 config/ 目录下的文件”之类的规则，Claude 会遵守。
• 善用 /compact：长对话会消耗大量 token，及时压缩可以降低成本。
• 选中代码再提问：在 VSCode 里高亮代码后打开 Claude 面板，上下文更精准。
• 让 Claude 写测试：直接说”给这个函数写单元测试”，效果出奇得好。
• 多模型切换：复杂推理用 Opus，日常编码用 Sonnet，速度与效果自由切换。

总结

安装 CLI → 装 VSCode 扩展 → 初始化 CLAUDE.md → 开始 vibe coding

Claude Code 最大的价值不是补全代码，而是理解项目、自主行动。把它当作一个真正的协作者，而不是一个更聪明的 Tab 键。

本文基于 Claude Code 最新版本（2026年3月）编写，部分功能随版本更新可能有所变化。

🚀 Claude Code × VSCode：开发者的 AI 终端利器配置指南最先出现在Liao's blog。