在国内网络环境里搭建 AI 编程工具，常见麻烦主要有三类：模型 API（应用程序编程接口）不好接、命令行工具配置项多、图片理解和联网搜索不能直接用。一个比较顺的方案是：用 Claude Code 作为本地命令行编程助手，把模型请求转发到智谱 AI 的 Anthropic 兼容接口，再用 MCP（Model Context Protocol，模型上下文协议）补上视觉理解和联网搜索。

整体关系可以理解成这样：

flowchart LR
    U[开发者] --> C[Claude Code]
    C -->|代码问答 / 修改 / 生成| A[智谱 Anthropic 兼容接口]
    A --> G[GLM-4.6]

    C -->|MCP 调用| V[智谱视觉 MCP]
    V --> VM[图片 / 视频理解模型]

    C -->|MCP 调用| S[Web Search Prime MCP]
    S --> W[联网搜索结果]

Claude Code 负责读项目、理解需求、修改代码；GLM-4.6 负责模型推理；视觉和联网搜索不是靠 Claude Code 自带能力完成，而是通过 MCP 注册成外部工具，在需要的时候让模型调用。

准备工作

需要先准备三样东西：

项目	用途
Node.js 和 npm	安装 Claude Code、运行 MCP 服务
智谱 AI 开放平台账号	获取 API Key，调用 GLM-4.6 和相关工具
一个本地项目目录	Claude Code 需要在具体项目目录里工作

确认本机已经安装 Node.js：

node -v
npm -v

如果命令能正常输出版本号，就可以继续安装 Claude Code。

获取智谱 API Key

打开智谱 AI 开放平台：

https://bigmodel.cn/

进入控制台后，找到 API Key 管理入口，新建一个 Key，并复制保存。这个 Key 后面会同时用于两类配置：

Claude Code 调用 GLM-4.6。
MCP 服务调用智谱视觉、联网搜索能力。

API Key 只会完整展示一次，建议保存到密码管理器或本机安全位置，不要写进公开仓库，也不要发到聊天记录或截图里。

安装或更新 Claude Code

Claude Code 是 Anthropic 提供的 CLI（Command Line Interface，命令行界面）编程助手。安装命令如下：

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

检查版本：

claude -v

进入一个项目目录后启动：

cd your-project
claude

如果已经安装过 Claude Code，再执行一次全局安装命令即可更新到较新的版本。

让 Claude Code 使用 GLM-4.6

Claude Code 默认连接 Anthropic 官方接口，但它支持通过环境变量修改模型服务地址。智谱开放平台提供了 Anthropic 兼容接口，因此只要把基础地址、认证 Token 和默认模型改掉，Claude Code 就可以把请求发给 GLM-4.6。

核心配置如下：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6"
  }
}

几个配置项的含义如下：

配置项	含义
`ANTHROPIC_BASE_URL`	Claude Code 请求的模型服务地址，这里改成智谱 Anthropic 兼容接口
`ANTHROPIC_AUTH_TOKEN`	智谱 API Key，不需要加 `Bearer` 前缀
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	轻量模型，适合简单任务
`ANTHROPIC_DEFAULT_SONNET_MODEL`	默认主力模型，这里使用 `glm-4.6`
`ANTHROPIC_DEFAULT_OPUS_MODEL`	更高档位模型映射，这里同样使用 `glm-4.6`

推荐方式：用环境变量配置

macOS / Linux 可以写入当前 Shell：

export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.5-air"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.6"

如果想长期生效，可以写入 ~/.zshrc 或 ~/.bashrc：

cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.5-air"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.6"
EOF

source ~/.zshrc

Windows PowerShell 可以使用：

setx ANTHROPIC_BASE_URL "https://open.bigmodel.cn/api/anthropic"
setx ANTHROPIC_AUTH_TOKEN "your-api-key"
setx ANTHROPIC_DEFAULT_HAIKU_MODEL "glm-4.5-air"
setx ANTHROPIC_DEFAULT_SONNET_MODEL "glm-4.6"
setx ANTHROPIC_DEFAULT_OPUS_MODEL "glm-4.6"

setx 写入的是用户环境变量，执行后需要重新打开终端才会生效。

也可以写入 Claude Code 配置文件

如果不想把变量放进 Shell，也可以写进 Claude Code 的用户配置或项目配置。不同版本的 Claude Code 配置路径可能略有差异，常见位置包括：

位置	作用范围
`~/.claude/settings.json`	当前用户全局生效
项目内 `.claude/settings.json`	当前项目生效
项目内 `.claude/settings.local.json`	当前项目本机生效，适合放密钥

项目里如果需要放本机私有配置，建议把本地配置文件加入 .gitignore：

# Claude Code local secrets
.claude/settings.local.json
.env

同一个配置项如果在多个地方都出现，排查时优先检查环境变量，其次检查用户配置，再检查项目配置。为了减少混乱，最好只保留一种配置方式。

测试 GLM-4.6 是否接通

进入项目目录后启动 Claude Code：

cd your-project
claude

可以输入一个简单任务：

请读取当前项目结构，说明这个项目的主要模块，并指出启动入口在哪里。

如果 Claude Code 能正常分析项目，说明模型接口已经接通。也可以让它修改一个小文件、生成一个测试用例，进一步确认读写文件权限和模型调用都正常。

用 MCP 接入视觉理解

Claude Code 本身更偏向代码项目操作。图片、视频这类多模态输入，如果直接粘贴进命令行，体验通常不稳定。更稳的做法是配置智谱官方 MCP 服务，把图片或视频文件路径交给工具处理。

视觉 MCP 的配置示例：

{
  "mcpServers": {
    "zai-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@z_ai/mcp-server"
      ],
      "env": {
        "Z_AI_API_KEY": "your_api_key",
        "Z_AI_MODE": "ZHIPU"
      }
    }
  }
}

可以把它放到用户目录的 Claude Code 配置文件中，例如：

系统	常见路径
Windows	`C:\Users\<用户名>\.claude.json`
macOS / Linux	`~/.claude.json`

如果文件里已经有 mcpServers，不要再新建第二个同名顶层字段，而是把 zai-mcp-server 合并进去。例如同时配置视觉和搜索时，结构应该像这样：

{
  "mcpServers": {
    "zai-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@z_ai/mcp-server"
      ],
      "env": {
        "Z_AI_API_KEY": "your_api_key",
        "Z_AI_MODE": "ZHIPU"
      }
    }
  }
}

配置完成后重新启动 Claude Code。可以这样测试：

请使用智谱视觉 MCP 分析 ./assets/login-error.png，说明截图里可能的报错原因，并给出前端排查建议。

这里有两个细节很关键：

图片要以文件路径形式传入，例如 ./assets/login-error.png，不要只说“看这张图”。
如果同时配置了多个 MCP 服务，提示词里可以明确写“使用智谱视觉 MCP”，避免模型选择其他工具。

视觉能力适合处理这些任务：

场景	示例
UI 截图排查	分析页面布局错位、表单报错、弹窗遮挡
设计稿转代码	根据截图生成 HTML / CSS / 组件结构
报错截图理解	识别终端、IDE、浏览器控制台里的错误信息
图表说明	解释架构图、流程图、接口时序图

用 MCP 接入联网搜索

模型本身的知识有时间边界，依赖版本、框架文档、模型排名、API 变更这类信息，最好通过联网搜索获得。智谱的 web_search_prime 可以作为 HTTP 类型 MCP 服务接入 Claude Code。

配置示例：

{
  "mcpServers": {
    "web-search-prime": {
      "type": "http",
      "url": "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

注意这里和前面的 ANTHROPIC_AUTH_TOKEN 不一样：

位置	API Key 写法
Claude Code 模型接口	`ANTHROPIC_AUTH_TOKEN="your-api-key"`
Web Search MCP 请求头	`"Authorization": "Bearer your_api_key"`

如果要同时配置视觉和联网搜索，可以合并成一份完整的 MCP 配置：

{
  "mcpServers": {
    "zai-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@z_ai/mcp-server"
      ],
      "env": {
        "Z_AI_API_KEY": "your_api_key",
        "Z_AI_MODE": "ZHIPU"
      }
    },
    "web-search-prime": {
      "type": "http",
      "url": "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

重启 Claude Code 后，可以这样测试联网搜索：

请使用 web-search-prime 查询 GLM-4.6 的最新公开信息，列出来源、发布时间和主要能力变化。

做技术调研时，建议让模型带上来源和时间：

请联网查询 React 19 的 useActionState 用法，要求给出官方文档来源、适用版本，并用一个表单提交示例说明。

这样能减少模型凭旧知识回答的概率。

常见使用组合

不同任务需要的能力不一样，不必每次都调用全部工具。

任务	推荐能力组合	说明
修改业务代码	Claude Code + GLM-4.6	让模型读项目、定位文件、生成补丁
生成单元测试	Claude Code + GLM-4.6	适合补测试、解释失败用例
根据截图修 UI	Claude Code + GLM-4.6 + 视觉 MCP	截图以文件路径传入
查询新框架用法	Claude Code + GLM-4.6 + 联网搜索 MCP	让模型引用最新文档
分析报错截图	Claude Code + 视觉 MCP	适合 IDE、浏览器控制台、终端截图
调研模型或工具动态	联网搜索 MCP	要求返回来源和日期

常见问题和排查方法

1. 提示认证失败或 401

重点检查 API Key：

ANTHROPIC_AUTH_TOKEN 只写 Key 本身，不加 Bearer。
Web Search MCP 的请求头需要写成 Bearer your_api_key。
确认 Key 没有复制空格、换行或中文引号。
确认账号套餐或余额能调用对应能力。

2. Claude Code 仍然请求默认接口

检查环境变量是否真的生效。

macOS / Linux：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_DEFAULT_SONNET_MODEL

Windows PowerShell：

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_DEFAULT_SONNET_MODEL

如果没有输出，说明当前终端没有加载配置。重新打开终端，或者重新执行 source ~/.zshrc。

3. MCP 服务没有出现或无法调用

先检查 JSON（JavaScript Object Notation，常用配置格式）是否合法，尤其是逗号和大括号。最常见的错误是写了两个顶层 mcpServers，正确做法是把多个服务放在同一个 mcpServers 对象里。

还可以检查 npx 是否可用：

npx -v

如果 npx 不存在，需要重新安装或修复 Node.js 环境。

4. 视觉工具没有被调用

如果配置了多个 MCP 服务，模型可能不会自动选择视觉工具。提示词要更明确：

请使用 zai-mcp-server 分析 ./screenshots/profile-page.png，不要只根据文件名猜测。

同时确认文件路径真实存在。Windows 路径如果放进 JSON 字符串，反斜杠需要转义，例如：

"C:\\Users\\name\\Pictures\\error.png"

在提示词里使用相对路径通常更省事：

请分析 ./screenshots/error.png

5. 搜索结果不够新或没有来源

把要求写清楚：

请使用 web-search-prime 搜索最近 30 天内的资料，回答时列出来源链接、发布日期和关键结论。

联网搜索适合查事实，不适合直接替你判断所有技术取舍。对依赖升级、生产配置、接口变更这类问题，仍然要回到官方文档和项目代码里验证。

安全和成本注意事项

API Key 和代码都会经过云端模型服务处理，使用时需要注意边界：

注意点	建议
API Key 泄露	不要提交到 Git，不要放进公开截图
私有代码	涉及敏感业务、密钥、客户数据时先脱敏
MCP 工具调用	视觉和搜索也会消耗额度，具体按平台计费规则为准
项目配置共享	团队仓库只提交占位配置，本机密钥放到 local 文件或环境变量
输出代码	模型生成后要运行测试、做代码审查，不要直接合并

一套可落地的配置流程

完整流程可以压缩成这几步：

flowchart TD
    A[安装 Node.js 和 npm] --> B[安装 Claude Code]
    B --> C[获取智谱 API Key]
    C --> D[配置 Anthropic 兼容接口环境变量]
    D --> E[进入项目启动 claude]
    E --> F{是否需要图片或视频理解}
    F -->|需要| G[配置 zai-mcp-server]
    F -->|不需要| H{是否需要最新资料}
    G --> H
    H -->|需要| I[配置 web-search-prime]
    H -->|不需要| J[直接进行代码任务]
    I --> J

完成这些配置后，Claude Code 可以承担项目阅读、代码生成、重构、测试补齐等工作；GLM-4.6 负责主要推理；视觉 MCP 处理截图、图片、视频文件；联网搜索 MCP 用来补充最新资料。对日常 AI 编程来说，这套组合已经能覆盖代码编辑、问题排查和技术调研的大部分场景。

菜单

用 Claude Code 接入智谱 GLM-4.6：API 配置、视觉理解与联网搜索