河洛序
会员
制器坊 工具使用

Claude Code 使用：安装、权限与项目工作流

在自己的测试项目中完成一次受控修改。配合操作示例、图解和检查点，完成第一次练习，再逐步排查使用中的问题。

入门整理更新：2026-10-13编程 Agent

信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。

⚠️ 地区提醒：Anthropic 仅在支持的国家/地区提供服务。若你所在地区不在列表中，请优先考虑当地合法可用的替代工具。本文不提供任何规避地区限制的方法。

1. 定位

【有据可查】Anthropic 官方编程 Agent，提供终端 CLI、VS Code / JetBrains 扩展、桌面应用等形态；设置文件为 ~/.claude/settings.json 等，项目指令文件为 CLAUDE.md。来源：Claude Code Docs、Settings

2. 订阅方案结构（不列价格）

方式 计费 说明 层级
Claude 订阅登录（Pro / Max / Team / Enterprise 等） 订阅内用量限额 文档提到 Pro、Max、Team 套餐的默认权限模式行为 有据可查：Permission modes
Claude Console API Key 按 token 计费 适合脚本/CI 有据可查
企业网关 / 云厂商（Bedrock、Google Cloud、Microsoft Foundry 等） 由网关背后的账户按 API 价格计费 使用网关凭据时，订阅额度不被使用 有据可查：Gateways

2.1 OAuth 订阅凭据与 API Key 的使用范围【有据可查（官方文档）】

【有据可查】Anthropic 官方 Legal and compliance 区分 OAuth 与 API Key：订阅 OAuth 用于 Claude Code 及其他 Anthropic 原生应用的正常使用；开发与 Claude 交互的产品或服务应使用 Claude Console API Key 或受支持云厂商凭据。官方禁止第三方开发者向用户提供自己应用内的 Claude.ai 登录，或代用户用 Free/Pro/Max 凭据路由请求。 → magpie 使用：来源配置、模型切换与恢复（magpie）、Cockpit Tools：凭据存放、功能边界与条款判断（Cockpit Tools）、OpenClaw 入门：独立环境、配置与安全边界（OpenClaw）的具体用法需按凭据如何取得、是否代他人路由、是否运行未修改的 Claude Code 分别判断；功能名称不能单独证明条款结论。原始说明见上述官方文档。

3. 安装【有据可查】

来源：Advanced setup

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
claude --version
  • 原生安装会自动更新；若提示命令找不到，将 ~/.local/bin（Windows 为 %USERPROFILE%\.local\bin）加入 PATH。

4. 首次配置

  1. claude 启动并登录；
  2. 在项目根让它生成/补充 CLAUDE.md（项目约定、测试命令、禁区）；
  3. /permissions 设置允许/询问/拒绝规则；/config 调整设置。

【有据可查】CLAUDE.md 只是"指令"，不能改变权限的强制执行；真正的约束要写在 settings 的 permissions.allow / ask / deny 里，deny 优先。来源：Permissions

5. 权限与安全模型【有据可查】

5.1 权限模式

模式 行为
default（Manual） 每种工具首次使用时询问
acceptEdits 自动接受工作目录内的文件编辑与常见文件命令（mkdir/touch/mv/cp）
plan 只读探索并写计划，不改源码，批准计划后才进入编辑
auto 无常规弹窗；Shell 命令、网络请求等执行前由后台分类器判断是否符合你的请求
dontAsk 所有本该询问的调用一律自动拒绝，只放行预授权的
bypassPermissions 跳过权限（对应 --dangerously-skip-permissions）
  • Shift+Tab 在 Manual → Accept edits → Plan → Auto 之间切换；/plan 让单条提示进入计划模式。
  • 安全设计：auto 与 bypassPermissions 不能从项目级 .claude/settings.json / .claude/settings.local.json 生效——防止仓库自带配置给你"开后门"。
  • 组织可通过 permissions.disableBypassPermissionsMode / disableAutoMode 禁用这两种模式。

来源：Permission modes、Settings、Auto mode config

5.2 沙箱

  • /sandbox 或 "sandbox": {"enabled": true} 开启 OS 级沙箱，限制 Bash/PowerShell 等命令及其子进程的文件与网络；默认只能写工作目录与临时目录。来源：Sandboxing
图 1

5.3 示例：给新手的保守配置

{
  "permissions": {
    "defaultMode": "default",
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  },
  "sandbox": { "enabled": true }
}

（deny 示例改写自官方 Example settings。）

6. 常用工作流

图 2

【社区共识】高效习惯：先 Plan 后改；一个会话一个目标；把反复强调的规则写入 CLAUDE.md；危险命令写进 deny。

7. 接入自定义模型 / 网关【有据可查】

来源：Connect to an LLM gateway、Gateway protocol、Other LLM gateways

export ANTHROPIC_BASE_URL=https://gateway.example.com     # 需提供 Anthropic Messages 格式 /v1/messages
export ANTHROPIC_AUTH_TOKEN=网关凭据                       # 或 ANTHROPIC_API_KEY
# 可选: 模型名
export ANTHROPIC_MODEL=网关上的模型名
# 可选: 网关支持 GET /v1/models 时开启模型发现(默认关闭)
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

关键事实：

  • 只设 ANTHROPIC_BASE_URL 不设网关凭据：请求经过网关，但仍用你的 claude.ai 登录与订阅额度。
  • 设了网关凭据：按网关背后账户的 API 价格计费，订阅不被使用。
  • ⚠️ Anthropic 不支持通过网关把 Claude Code 路由到非 Claude 模型，也不背书/审计第三方网关产品。社区确有人这样用，但属于官方不支持的用法，出问题自负。

8. 常见报错

现象 原因 处理 层级
claude: command not found PATH 未包含安装目录 加 ~/.local/bin 有据可查
项目里设置 defaultMode: auto 不生效 设计如此 写到 ~/.claude/settings.json 或用 --permission-mode 有据可查
网关 401 凭据变量错/缺失 检查 ANTHROPIC_AUTH_TOKEN/ANTHROPIC_API_KEY 有据可查
529 overloaded Anthropic API 整体过载 指数退避重试 有据可查：API errors
账号被限制/封禁 地区、风控、违反条款等 见 AI 账号安全：登录态、密钥、授权与申诉；无可靠"解封"方法 社区共识

9. 适合人群

10. 本篇无法核实/需谨慎的点

  • Anthropic OAuth/API 区别的官方原文已核对，见 Legal and compliance；具体第三方工具版本是否符合上述条件，仍需检查其实现。
  • 各订阅档的具体用量限额（变化快，未列）。
  • 社区"用网关接非 Claude 模型"的稳定性：官方明确不支持。

小白练习：把本文流程逐项走通

练习目标：在自己的测试项目中完成一次受控修改。

上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。

  1. 先确认自己的账户具备所选登录方式的使用资格，再按系统选择官方安装命令。Bash 与 PowerShell 两种命令选其一。

  2. 安装后重新打开终端，运行 claude --version；无法识别时先查安装目录和 PATH。

  3. 进入练习目录后运行 claude，完成登录。查看当前模型和计费来源，再检查权限模式。

  4. 把项目结构、测试命令与不应修改的文件写入 CLAUDE.md。它是说明文件，访问控制仍由权限设置执行。

  5. 先用计划模式让它说明将改什么，阅读后再允许实现。逐次查看需要批准的命令。

  6. 结束后打开 diff，运行测试，再查看真实输出。第三方网关和订阅转用另见履霜录，不把 API Key 和 OAuth 登录态互换。

不要把请求链路和凭据混为一谈

【有据可查】官方同时说明：终端用户用自己的订阅登录未修改的 Claude Code 二进制，并不被上述说明一概禁止；开发者不得收集、存储或中介 Claude.ai 凭据或会话 token，登录须经过 Anthropic 自己的流程。

【待判断】“本机安装了 Claude Code”仅说明一个技术环节，不能独自证明整个产品符合条件。配置网关前分别核对它保存什么凭据、请求经谁发出、实际计费来源；原稿安装、权限设置、测试与复核步骤仍完整保留。

核对来源：Anthropic 官方：Legal and compliance · Authentication and credential use。

继续浏览制器坊 返回顶部 ↑
教程图解100%
教程图解
灵犀台