DeepFloodbeta
search for post search for people use google search

claude code 极简上手（macOS/Linux）：从安装、联网检索到转发站与提示词

tmptmp
tmptmp楼主种子
edited 291days ago in 人工智能
#0

claude code 极简上手（macOS/Linux）：从安装、联网检索到转发站与提示词工程

最近更新：2025-10-05（北京时间）。本文分享一下 claude code 的简单教程，聚焦 macOS 与 Linux（顺带给出 WSL 备注）。只保留“能跑通、好复用”的关键步骤，风格朴素直接，适合从 Cursor/Copilot/Windsurf 迁移到 Claude Code 的同学。全文中文输出，英文仅用于命令、配置键名与检索关键词示例。

关键词：macOS、Linux、第三方 API、转发站（AnyRouter/LiteLLM/OpenRouter/Helicone/One‑API）、WebSearch/WebFetch、MCP、IDE 联动、状态栏、自定义提示词、后端向提示词工程（Go/Python/Rust）。

0. 适用范围与你要的结果

  • 你将获得：一个可用的 Claude Code 工作环境（macOS/Linux），开箱即用的联网检索与 IDE 联动，能在限制网络里通过“转发站”统一出入口，且有一整套后端向提示词模板。
  • 参考来源：官方文档（设置、WebSearch/WebFetch、MCP、IDE、状态栏等）（文末附链接）。
  • 系统与前提：
    • macOS 13+/14+/15+ 或主流 Linux（Ubuntu/Debian/Arch/CentOS 等）；WSL 亦可，注意代理与文件权限差异。
    • 终端基础：会改 ~/.zshrc/~/.bashrc，懂环境变量。
    • 账号与密钥：官方账号或企业下发的 API Key/SSO/IdP。

术语速览：

  • Claude Code：本地开发者体验（CLI + IDE 插件），可读写项目、运行命令、联网检索。
  • Web Search / Web Fetch：搜索互联网与抓取指定 URL，作为回答依据与上下文。
  • MCP：Model Context Protocol，把外部系统/数据源接到模型里，受权限控制。
  • 转发站（Relay/Proxy）：统一出入口或做合规桥接，如 AnyRouter/LiteLLM/OpenRouter/Helicone/One‑API 等。

说明：截至 2025-10-05，Claude 4.5（Sonnet 4.5）已对外公布，典型 ID 形如 claude-sonnet-4-5-20250929；不同地区与资质开放度不同，请先“列举模型”确认可用项。

1. 安装与最简可用（macOS / Linux）

目标：把 CLI 装起来，最小配置生效，确认能进对话、有权限、有 IDE 联动。

1.1 安装 Node 与 CLI

# 安装 nvm（macOS/Linux 通用）
export NVM_DIR="$HOME/.nvm" && \
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 载入 nvm（或重新开一个终端）
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# 安装 Node LTS（>=18）
nvm install --lts
nvm use --lts

# 安装 Claude Code CLI（全局，不要 sudo）
npm i -g @anthropic-ai/claude-code

# 验证
claude --version

macOS 额外依赖（可选）：

xcode-select --install  # 安装命令行工具（含 git 等）

Linux（Debian/Ubuntu）常用依赖：

sudo apt update
sudo apt install -y build-essential curl git ca-certificates

1.2 登录与体检

# 浏览器登录（默认 OAuth）
claude /login

# 健康检查（环境、权限、网络、IDE、工具能力）
claude /doctor

无 GUI（如 SSH/服务器）时：

  • 在本机先 /login，再把凭据同步到服务器（按组织安全规范执行）。
  • 或走企业 SSO/IdP；也可纯 API Key 模式（见第 4 节）。

1.3 IDE 联动（VS Code / JetBrains）

# VS Code 扩展市场安装 “Anthropic • Claude Code”
code --install-extension Anthropic.claude-code  # 可选

# 外部终端连接 IDE（VS Code/JetBrains）
claude
# 在对话里输入：
/ide

建议：在 /config 中启用 IDE 自动连接与内联 diff 预览。远程开发（SSH/Container）时，远端也要安装 CLI，路径映射务必跑一遍 /doctor。

2. 启用联网检索：Web Search 与 Web Fetch

联网检索分两类：

  • Web Search：模型主动“搜索”互联网以获得线索与最新信息。
  • Web Fetch：抓取指定 URL 的网页内容作为上下文与证据。

2.1 在 CLI/IDE 中开启权限

# 打开交互式权限配置
claude /permissions

# 直接批准常见 Web 工具（按需收紧）
claude /allow WebSearch
claude /allow WebFetch

# 查看当前权限
claude /permissions --list

IDE 插件设置也能勾选对应工具；团队环境建议配合“允许域名白名单/调用上限”。

2.2 API 侧（可选）

在 API 请求体里声明工具：[{"type":"web_search_20250305"}, {"type":"web_fetch_20250910"}]，并通过 allowed_domains/max_uses 等限制作用范围。

2.3 使用范式

  • 明确关键词（英文为主）、站点和时间范围；
  • 先 Search 再 Fetch，最后总结并落地到代码/文档；
  • 要求“带出处回答”（列链接与核验要点）。

例子（在对话直接说，关键词用英文）：

claude, please first WebSearch with keywords: "Anthropic Messages API list models" and "Claude Code settings env"; then WebFetch the exact model ID page. Finally give me Chinese steps for macOS.

3. 使用 MCP（Model Context Protocol）扩展能力

MCP 让模型“看到/调用”外部系统：从文件/终端/浏览器，到数据库/知识库/云 API。Claude Code 内置部分工具，并支持连接“远程 MCP 服务器”。

3.1 添加远程 MCP 服务器

claude mcp add my-tools http://127.0.0.1:8989
claude mcp list
claude mcp remove my-tools

典型用法：把“企业知识库 / 代码搜索 / 内部 API”封装成 MCP，通过权限规则限制调用范围、参数与频率。

3.2 权限与审计

  • 用 /permissions 为 MCP 指定可用工具与参数边界；
  • 团队/企业版结合审计日志与密钥托管，保证可追溯与最小权限；
  • 涉及文件写入/终端执行时，强制“先计划/预览，再执行”。

4. 设置文件与环境变量（按 Linux.do 的“最简配置”思路）

Claude Code 的配置采用“分层 settings.json”，优先级（低→高）：用户层 → 项目层 → 项目私有层：

~/.claude/settings.json                 # 用户层（作用于所有项目）
<project>/.claude/settings.json         # 项目层（可提交到仓库）
<project>/.claude/settings.local.json   # 项目私有（不提交）

最小可用示例：

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-你的官方key或第三方key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"  // 指向转发站时改成转发地址
  },
  "permissions": {
    "ask": [],
    "allow": ["Read(**)", "Edit(**)", "Bash(echo:*)"],
    "deny": ["Read(./.env*)", "Read(./secrets/**)"]
  }
}

全局提示词（影响所有会话的“行为基调”）建议放到 ~/.claude/CLAUDE.md：

## Response Language
除非另有说明，请用中文回答。

## Safety & Permissions
先展示计划与改动预览，涉及写文件、运行命令、网络访问时，必须先征求确认。

另可通过环境变量控制访问路径（bash 示例）：

export ANTHROPIC_API_KEY="sk-your-anthropic-key"   # 或 ANTHROPIC_AUTH_TOKEN（官方同样支持）
export ANTHROPIC_BASE_URL="https://api.anthropic.com"  # 指向转发站时改此值
export HTTP_PROXY="http://proxy.corp:3128"       # 企业代理（可选）
export HTTPS_PROXY="http://proxy.corp:3128"
export ANTHROPIC_BEDROCK_BASE_URL="https://bedrock-runtime.us-east-1.amazonaws.com"   # 企业合规路径（可选）
export ANTHROPIC_VERTEX_BASE_URL="https://us-central1-aiplatform.googleapis.com"      # 企业合规路径（可选）

将上述变量追加到 ~/.bashrc 或 ~/.zshrc 后 source 生效。

5. “转发站”配置

目标：在受限网络或需要统一出口/记费/配额管理时，搭建/选择一层“中转”。以下给出常见选项与最小配置，注意合规与密钥安全。

5.1 AnyRouter（第三方聚合，OpenAI 兼容）

  • 适合人群：想快速试用、统一 OpenAI 兼容接口；
  • 用户层 settings.json 示例：
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-anyrouter-xxx",
    "ANTHROPIC_BASE_URL": "https://anyrouter.top"
  }
}

生产前务必评估隐私/合规；域名可能变动，以服务方公告为准。

5.2 LiteLLM Proxy（自建，/anthropic 直通）

pip install "litellm[proxy]"
export ANTHROPIC_API_KEY="sk-your-anthropic-key"
litellm --port 4000 --host 0.0.0.0 \
  --passthrough-endpoints /anthropic \
  --passthrough-authorization-header "x-api-key" \
  --passthrough-base-url https://api.anthropic.com

curl -s http://127.0.0.1:4000/anthropic/v1/models | jq .

export ANTHROPIC_BASE_URL="http://127.0.0.1:4000/anthropic"

生产：加服务端鉴权/限流/出口白名单；上游 Key 仅放服务端。

5.3 OpenRouter（聚合服务，OpenAI 兼容）

  • 面向多模型聚合，提供 OpenAI 兼容接口；
  • 按其文档设置 API Key 与 Base URL；与 Claude Code 联动时，可将 ANTHROPIC_BASE_URL 指向其兼容端点（以官方文档为准）。

5.4 Helicone（网关与观测）

  • 提供“AI Gateway”与观测，支持直通 Anthropic；
  • 优点：带日志与用量监控，适合团队快速上线、后续迁移到自建治理。

5.5 One‑API（开源聚合，OpenAI 兼容）

  • 自建“Key 管理 + 分发 + OpenAI 统一适配”，宣称支持 Anthropic；
  • 建议仅供内部/实验环境；务必限制外部暴露并加强审计。

5.6 Bedrock / Vertex（合规路径）

  • 由云厂商负责网络与合规；
  • Claude Code 配合 ANTHROPIC_BEDROCK_BASE_URL 或 ANTHROPIC_VERTEX_BASE_URL；
  • 企业侧可叠加 API Gateway/WAF/私网出口治理。

6. 选择与验证模型（含 Claude 4.5）

# 列出可用模型（官方直连）
curl -s https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" | jq -r '.data[].id'

# 如走转发站：
curl -s ${ANTHROPIC_BASE_URL}/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" | jq -r '.data[].id'

若输出包含 claude-sonnet-4-5-YYYYMMDD（如 claude-sonnet-4-5-20250929）即可用；否则先用 claude-sonnet-4 或账号支持的 4.x/3.x 家族。

7. 最小“语言特定提示词”合集：让 claude code 改 Go / Python / Rust 代码

7.1 Go（Golang）

我是 claude，你是我搭档。请在本项目中改造 Go 代码：
目标：将 `internal/pkg/http/middleware.go` 重构为可插拔日志中间件；支持 trace-id 透传、超时、错误包装；不引入重型依赖。
约束：
- 仅修改当前仓库；优先在原文件内小步提交；
- 遵循 Go 官方与标准库风格；
- 不要创建多余文件；若需新增，请先说明理由；
- 先给出计划（变更点 + 风险），再展示 diff 预览，最后征求确认后执行；
- 单元测试：为关键路径补 2-3 个基准/单测（`testing`），命名清晰；
- 性能：避免过度分配与切片反复扩容，解释关键选择。
输出：
- 计划要点与影响面；
- 预览 diff；
- 测试方法与 `go test -run` 命令；
- 如需，请 `/permissions` 申请必要的 Read/Edit/Bash。

常用变体：

  • “并发 Bug 定位”：附 pprof 片段与 goroutine 栈，要求先假设后验证，再给最小复现；
  • “接口可观测性”：在 handler 返回处加结构化日志与 error wrapping，列出 MDC/fields；
  • “数据库边界”：限定在 internal/repo/*.go，补事务模板与重试。

7.2 Python

我是 claude。请在 `app/` 下将 FastAPI 同步路由迁移为 async，并保持 idempotency：
范围：`app/main.py`、`app/services/*.py`；
要求：
- 先列迁移策略与兼容性；
- 给出逐步 diff 预览；
- 连接池与超时参数明确；
- 使用 `pytest` 增加 3 个最小用例；
- 禁止引入过多依赖；
- 若需要运行命令，请先说明并征求 `/permissions`。
输出：
- 变更计划 + diff；
- `pytest -q` 与 `uvicorn` 本地跑法；
- 回滚方案（如何一键恢复原始版本）。

7.3 Rust

我是 claude。请为 `src/` 的 Axum 项目增加配置模块：
目标：从 env/file 读取，支持层叠覆盖；暴露只读配置；零 unsafe；
约束：
- 推荐 `serde` + `figment`/`clap` 之一；
- 先给设计草图（模块边界/数据结构），再给 `diff`；
- 加 2 个单元测试与一个 `cargo run` 示例；
- 对 tokio 任务取消与背压，写出风险点清单；
- 如需新增文件，先说明理由与命名。
输出：
- 设计说明 + diff 预览；
- 测试与运行命令；
- 性能与可维护性权衡说明。

8. 后端向提示词工程（分功能模板）

使用建议：

  • 结构化输入：目标 + 约束 + 上下文 + 输出格式；
  • 尽量提供仓库路径/关键文件/接口设计；
  • 联网检索任务末尾追加“如需，请 WebSearch + WebFetch 并附来源链接”。

8.1 架构速读与任务分解

我是 claude。请：
1) 速读仓库结构（/cmd, /internal, /pkg, /docs）；
2) 输出文字架构图（模块与数据流）；
3) 标出技术债/风险点（并发、资源泄漏、错误边界、日志、重试）；
4) 给出三阶段任务拆分；
5) 如需，WebSearch 官方最佳实践并贴链接。

8.2 代码走查（Code Review）

我是 claude。请对以下改动做审查：
目标：降低 p99 延迟且不牺牲正确性。
上下文：<贴 PR 摘要/关键 diff>。
输出：
- 问题与分级（Blocker/Major/Minor）
- 并发/锁/IO/GC 影响评估
- 单测缺口与建议用例
- 安全项（注入、越权、反序列化、路径遍历）
- 如可，生成修复补丁（逐文件说明）

8.3 生成/改造模块（Go/Python/Rust 各给一个）

Go：生成 idiomatic 的 HTTP 中间件（日志、trace-id、超时、错误分类），给出 chi/gin/标准库 mux 用法与设计说明。

Python：将 FastAPI 服务改为 async 路线，补连接池/超时/重试/熔断，并附 pytest 基线用例。

Rust：为 Axum 项目添加配置模块（env/file 读取、层叠覆盖、只读暴露），并附单测与 README 片段。

8.4 并发与性能

Go：给出 pprof 报告解读、锁争用/切片扩容建议、最小复现场景与基准线。

Python：生成 asyncio 压测器，压 3 条关键路径，输出 p50/p95/p99 与错误率。

Rust：评审 tokio 任务取消与背压，画取消传播图与缓冲建议，列死锁/饥饿风险。

8.5 数据库与事务

MySQL → Postgres 在线迁移：双写/回放/校验流程、DDL 兼容清单、零停机与回滚策略。

Go repository 事务边界：给事务模板（隔离级别、超时）、错误包装与幂等重试建议。

8.6 API 设计与契约

基于需求输出 OpenAPI 3.1：生成 openapi.yaml、服务端/客户端代码生成命令（Go/Py/Rust）、版本化策略。

8.7 测试与 CI/CD

补齐测试分层：单测/集成/端到端；Go: testify+gomock；Py: pytest；Rust: cargo test；覆盖率门槛与报告收敛；给出 GitHub Actions 样例。

8.8 安全与合规

轻量安全审计：输入校验、反序列化、路径遍历、命令注入、SQL 注入、SSRF；输出问题清单与修复补丁；预防策略（lint/hook/扫描）。

8.9 联网检索与证据式回答

围绕“Go 1.xx 新特性”写迁移指南：先 WebSearch 再 WebFetch 官方 release notes 与提案；输出带出处链接的要点清单；列出影响到的内部代码位置与 refactor 建议。

9. IDE 联动与状态栏（像 Cursor 那样顺手）

  • 连接 IDE：外部终端运行 claude → 输入 /ide 选择 VS Code/JetBrains；无法检测时检查 code 命令或 JetBrains 插件是否安装，必要时重启 IDE。
  • 自动连接：在 /config 启用 “Auto‑connect to IDE (external terminal)”。
  • 自定义状态栏：
// ~/.claude/settings.json（片段）
{
  "statusLine": "npx -y ccusage@latest statusline"
}

或使用更可定制的：

{
  "statusLine": "bunx ccstatusline@latest"
}

更多能力（刷新节流、ANSI 颜色等）见“状态栏配置”文档；ccusage/ccstatusline 为社区脚本，按需取舍。

10. 故障排查（Troubleshooting）

  • 登录失败或 CLI 无法打开浏览器：

    • claude /login --copy-url 在有 GUI 的机器完成；或改 API Key；
    • 检查代理：env | rg -i proxy，必要时临时 unset HTTPS_PROXY 再试。

  • Web 工具未授权：

    • claude /permissions 允许 WebSearch 与 WebFetch；
    • IDE 插件里也要勾选对应权限；
    • 组织策略下可能需要管理员侧放权。

  • 无法访问模型/超时：

    • curl -v $ANTHROPIC_BASE_URL/v1/models 或 curl -v https://api.anthropic.com/v1/models；
    • 检查证书、SNI 与公司代理；
    • 使用转发站时，确认 /anthropic 路径与 x-api-key 透传。

  • 模型 ID 不存在：

    • 先“列举模型”；
    • 根据账号地区与额度不同，4.5 可能尚未开放；退用 4.x 或 3.x。

  • IDE 文件/终端操作被拒：

    • Settings -> Permissions 开启文件读写与 Shell；
    • 限定目录为工作区根，逐步放权。

  • 权限提示过于频繁：

    • 核对 ~/.claude/settings.json 的 permissions.allow/ask/deny 是否匹配实际工具名；
    • 删除项目的 settings.local.json 重新生成；
    • defaultMode 放在 permissions.defaultMode 下；用 /doctor 校验无效字段。

11. 实操

# 1) 安装 CLI
npm i -g @anthropic-ai/claude-code && claude --version

# 2) 登录与体检
claude /login && claude /doctor

# 3) 开启联网检索
claude /allow WebSearch && claude /allow WebFetch && claude /permissions --list

# 4)（可选）添加 MCP 远程服务器
claude mcp add my-tools http://127.0.0.1:8989 && claude mcp list

# 5)（可选）搭建转发站（LiteLLM Passthrough）
pip install "litellm[proxy]"
export ANTHROPIC_API_KEY=sk-your-key
litellm --port 4000 --host 0.0.0.0 \
  --passthrough-endpoints /anthropic \
  --passthrough-authorization-header x-api-key \
  --passthrough-base-url https://api.anthropic.com
curl -s http://127.0.0.1:4000/anthropic/v1/models | jq .

# 6)（可选）让 CLI/SDK 指向转发站
export ANTHROPIC_BASE_URL=http://127.0.0.1:4000/anthropic

# 7) 列举模型并设置默认模型
export ANTHROPIC_MODEL=$(curl -s ${ANTHROPIC_BASE_URL:-https://api.anthropic.com}/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" | jq -r '.data[] | select(.id|test("4-5|4.5|4")) | .id' | head -n1)
echo "Using model: $ANTHROPIC_MODEL"

13. 结语

至此，你已具备：

  • 在 macOS/Linux 下安装与登录 Claude Code；
  • 开启 WebSearch/WebFetch 并做最小权限设定；
  • 接入 MCP 远程服务器，把内部系统/知识库安全地“接到模型里”；
  • 在企业/跨地域环境下搭建“转发站”，统一出口与配额；
  • 使用一套后端向提示词模板，覆盖生成、重构、测试、性能与安全等场景。

把这些写进项目的 CLAUDE.md 与 .claude/settings.json 后，新同学 30 分钟内能跑通环境，1 小时内交付一个迭代雏形。效率来自“流程清晰、权限可控、范式稳定”。

祝编码顺利——我们在下一个 git push 里见。

附：进一步阅读（选）

以下链接便于延伸阅读与核验。不同账号/地区可用功能与模型 ID 可能存在差异，请以官方文档为准。

  • yuyan
    yuyan种子
    #1

    不错的帖子 涵盖了好多 我的cc她已经自己跑了一个小时了也没停 结果写的全是文档笑死我了

  • tmptmp
    tmptmp楼主种子
    #2

    @yuyan #1 哈哈，有时候确实降智。

  • xausky
    xausky种子
    #3

    讲道理，如果不是特别喜欢命令行或者要用 claude code 官方服务的话，不如 kilo code

  • kvans
    kvans元老
    #4

    收藏了

  • turbux
    turbux种子
    #5

    多谢分享

  • 777
    777种子
    #6

    感谢分享

你好啊，陌生人!

我的朋友，看起来你是新来的，如果想参与到讨论中，点击下面的按钮！
登录 注册

快捷功能区

所有版块

📈用户数目📈

目前论坛共有13151位用户

🎉欢迎新用户🎉

刺痛
刺痛
xiaoqianmo
xiaoqianmo
fzkkk
fzkkk
xw
xw
Oleany
Oleany
x689ac
x689ac
tigerc
tigerc
橘子不黄
橘子不黄