第一个 Claude Code 任务：装好就跑通，一条命令的事

1. 从零跑通第一个 Claude Code 任务：装好就能用的完整链路

Claude Code 是 Anthropic 推出的终端 Agent 工具，能读代码、改文件、跑测试、执行 git 提交，适合已经会写 Python 但不想手写重复逻辑的开发者。它和普通代码补全最大的区别是：你给它一个需求，它自己拆步骤、自己调工具、自己验证结果。我第一次用它处理一个躺了三个月的report.py需求——给销售汇总脚本加--json输出——从打开终端到git commit完成，六分钟。这篇文章把这条链路完整拆开：安装、配置统一 Key/API 通道、写settings.json、用argparse小脚本 +pytest用例 +git commit三步验证任务确实跑通，最后把常见报错对照着排一遍。你照着做，第一个任务就能落地。

核心检索词先明确：Claude Code 是什么、能做什么、适合谁。它是一个跑在终端里的编码 Agent，通过自然语言指令操作你的项目文件；能做的事包括重构参数解析、补测试、生成 commit message、执行 shell 命令；适合手上有真实小项目、想验证 Agent 工作流的开发者。不适合只想补全单行代码的场景，那种用编辑器插件更省事。

我试过的第一个任务背景很简单：report.py每周读一次销售 CSV，按区域汇总金额打印到终端。老板问“能不能导出 JSON”，我拖了三个月。这次不自己写，丢给 Claude Code。下面每一步都给可复制命令和配置，你换成自己的项目路径即可。

在开始之前，先理清整条链路的三个关键点。第一，安装方式选原生脚本，别用 sudo；第二，API 通道用统一 Key，避免在多个工具间反复切换环境变量；第三，验证不能只看它说“跑通了”，要自己跑pytest、看 JSON 输出、确认git commit真的生成。这三点做到了，第一个任务才算真跑通，而不是“看起来跑通”。

2. TaoToken 前置：统一 Key 与 API 通道配置

在装 Claude Code 之前，先把 API 通道准备好。很多新手卡在认证环节：订阅账号登录弹浏览器、API Key 又要单独设环境变量，切来切去容易乱。我的做法是用 TaoToken 统一管理 Key 和 API 通道，Claude Code、Codex、Cline 这些工具共用一套入口，省掉重复配置。

TaoToken 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。API 基础地址是 https://taotoken.net/api ，注意这个地址不加 UTM 参数，配置里直接写这个。

先去控制台创建 API Key。打开 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面新建一个 Key，复制出来。这个 Key 就是后面ANTHROPIC_API_KEY和settings.json里要填的值。建议单独建一个给 Claude Code 用的 Key，方便后面按工具排查用量。

拿到 Key 之后，先设环境变量。macOS/Linux 在~/.zshrc或~/.bashrc里加：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoTokenKey"

Windows PowerShell 用：

$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的TaoTokenKey"

设完source ~/.zshrc或重开终端，用echo $ANTHROPIC_API_KEY确认能打印出来。这一步别跳过，环境变量没生效，后面 Claude Code 启动会直接报认证失败。

如果你更习惯用配置文件而不是环境变量，Claude Code 支持~/.claude/settings.json。这个文件是全局配置，所有项目共用。内容如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey" }, "permissions": { "allow": ["Bash(git:*)", "Bash(python:*)", "Bash(pytest:*)"] } }

permissions.allow里我放开了 git、python、pytest 三类命令，这样 Claude Code 跑测试和提交时不用每次弹确认。生产项目里你可以收紧，只放开必要命令。注意settings.json里的 Key 是明文，别把这份文件提交到 git，加到.gitignore里。

项目级配置放在项目根目录的.claude/settings.json，格式一样，只对当前项目生效。我一般全局放 Key 和 Base URL，项目级放ignorePatterns和权限，分工清楚。

配置完先验证通道通不通。用 curl 打一下模型列表或直接发一条最小请求：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

返回里有content字段就说明 Key 和通道都正常。这一步过了再装 Claude Code，能省掉后面一半的排错时间。

3. 可复制配置：安装 Claude Code 与 settings 片段

通道验证通过后，装 Claude Code。官方推荐原生安装脚本，一条命令：

curl -fsSL https://claude.ai/install.sh | bash

装完确认版本：

claude --version

能打印出版本号就装好了。如果你 Node 环境有问题，也可以用 Homebrew：

brew install --cask claude-code

npm 方式npm install -g @anthropic-ai/claude-code仍然可用，但官方已推荐原生脚本。不管哪种方式，都别加 sudo，权限问题排查起来很痛苦。

装完进项目目录启动：

cd ~/projects/sales-tools claude

第一次启动它会扫描目录，输出类似：

Reading project structure... - report.py (main script) - data/ (CSV files) - README.md - No CLAUDE.md found, no .claude/ config

它在找CLAUDE.md和.claude/配置目录。空项目没关系，它会直接读代码。这里有个关键配置要提前做：ignorePatterns。Claude Code 扫描时不受.gitignore限制，node_modules、.venv这些目录照样会被 Grep 和 Glob 扫进去，启动会变慢。在项目根目录建.claude/settings.json：

{ "ignorePatterns": ["node_modules", ".venv", "dist", "__pycache__", "*.pyc"], "permissions": { "allow": ["Bash(git:*)", "Bash(python:*)", "Bash(pytest:*)"] } }

ignorePatterns语法跟.gitignore一样。你也可以单独建.claudeignore文件，效果相同。我习惯放settings.json里，配置集中好管理。

再补一个项目级CLAUDE.md，告诉 Claude Code 这个项目的约定。放在项目根目录：

# sales-tools ## 项目说明 销售数据汇总脚本，主入口 report.py。 ## 代码约定 - Python 3.11+ - 参数解析统一用 argparse - 测试用 pytest，测试文件命名 test_*.py - 提交信息用 conventional commits 格式 ## 常用命令 - 跑测试：python -m pytest -v - 跑脚本：python report.py data/sales.csv

CLAUDE.md不是必须的，但写了之后 Claude Code 生成的代码风格会更贴合项目。它每次启动会读这个文件，相当于给 Agent 一份项目说明书。

配置三件套到这里齐了：Base URL 用https://taotoken.net/api，Key 用 TaoToken 控制台创建的 Key，Model ID 在请求里指定，比如claude-sonnet-4-20250514。这三个值在环境变量、settings.json、curl 验证里保持一致，后面排错就有对照基准。

启动后如果认证失败，先检查ANTHROPIC_BASE_URL有没有带尾部斜杠。正确写法是https://taotoken.net/api，不要写成https://taotoken.net/api/，有些客户端会把双斜杠拼进路径导致 404。这个坑我踩过，排查了十几分钟。

4. 验证请求：argparse 脚本 + pytest + git commit 三步跑通

配置就绪，开始第一个任务。我的report.py原始版本用sys.argv手动解析参数：

import csv import sys from collections import defaultdict def load_sales(filepath): with open(filepath, 'r') as f: return list(csv.DictReader(f)) def summarize(rows): regions = defaultdict(float) for r in rows: regions[r['region']] += float(r['amount']) return regions def main(): if len(sys.argv) < 2: print("Usage: python report.py <csv_file>") sys.exit(1) filepath = sys.argv[1] rows = load_sales(filepath) summary = summarize(rows) for region, total in summary.items(): print(f"{region}: ${total:,.2f}") if __name__ == '__main__': main()

在 Claude Code 交互界面里输入需求：

给 report.py 加一个 --json 选项。当传了 --json 时，输出改为 JSON 格式， 长这样： { "regions": [{"name": "East", "total": 12345.67}, ...], "total": 98765.43 } 要求： - 用 argparse 替代现在的 sys.argv 手动解析 - JSON 输出要格式化（indent=2） - 不影响现有的纯文本输出行为 - 写对应的测试

Claude Code 不是一次性吐代码让你复制，而是一步步来。它会先Read读源码，然后Edit改参数解析，Write新建测试文件，最后Bash跑 pytest。整个过程你能看到它的工具调用日志。

第一步验证：跑 pytest。它生成的test_report.py覆盖四个用例——文本输出、JSON 输出、缺参数、带样例 CSV。执行：

python -m pytest test_report.py -v

预期输出：

test_text_output PASSED test_json_output PASSED test_missing_args PASSED test_with_sample_csv PASSED 4 passed in 0.23s

四个全过，零失败。如果挂了，Claude Code 会把错误贴出来自己修，你先看它能不能自愈。

第二步验证：实际跑脚本，确认两种输出都对。准备一个样例 CSVdata/sales_2026_05.csv：

region,amount East,45230.00 West,32100.50 North,28900.00 South,19450.75

跑默认文本输出：

python report.py data/sales_2026_05.csv

输出：

East: $45,230.00 West: $32,100.50 North: $28,900.00 South: $19,450.75

跑 JSON 输出：

python report.py data/sales_2026_05.csv --json

输出：

{ "regions": [ {"name": "East", "total": 45230.0}, {"name": "West", "total": 32100.5}, {"name": "North", "total": 28900.0}, {"name": "South", "total": 19450.75} ], "total": 125681.25 }

两种输出都正确，--json不影响默认行为。这一步是“任务确实跑通”的硬证据，别只看 Agent 说完成。

第三步验证：git commit。在 Claude Code 里说“帮我提交”。它先跑git diff --stat看变更：

report.py | 24 +++++++++++++++++--- test_report.py | 38 ++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 4 deletions(-)

然后生成 commit message：

feat: add --json output option to report.py Replace manual sys.argv parsing with argparse. Add --json flag that outputs region summaries and total as formatted JSON. Includes test coverage for text output, JSON output, and CLI error handling.

确认后执行git commit。到这里三步验证闭环：pytest 过、脚本实际输出对、commit 生成。一个躺了三个月的需求，六分钟落地。

最终report.py的改动点值得看一眼。sys.argv手动解析换成argparse，文本输出拆成format_text，JSON 输出抽成format_json，--jsonflag 干净切换格式，参数缺失时 argparse 自己处理错误提示。变量命名对称、纯函数拆分、help 文本完整，像一个人认真写过的代码。这就是项目级上下文的作用——它读了代码风格，然后在同一风格里编程。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

第一个任务跑通不代表后面不踩坑。这一节把 Claude Code 接入过程中最常见的四类报错对照着排一遍，每个都给真实报错文本和定位方法。

401 Unauthorized。报错长这样：

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}

原因通常是 Key 没生效或写错。排查顺序：先echo $ANTHROPIC_API_KEY确认环境变量能打印；再检查settings.json里的 Key 有没有多余空格或换行；最后确认ANTHROPIC_BASE_URL是https://taotoken.net/api，没有尾部斜杠。如果环境变量和settings.json同时设了，settings.json优先级更高，改的时候别只改一处。还有一种情况是 Key 被删了或过期，去控制台 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新建一个。

local proxy failed。报错：

Error: local proxy failed to start: listen tcp 127.0.0.1:xxxx: bind: address already in use

这是本地端口被占用。Claude Code 某些模式会起本地代理端口，如果之前有进程没退干净就会冲突。排查：lsof -i :端口号找到占用进程，kill掉；或者重启终端。如果你同时开了多个 Claude Code 实例，也会撞端口，关掉多余的。这个报错跟网络环境无关，纯粹是本地端口问题，别往通道配置上想。

reading choices 相关报错。报错：

Error: reading choices: unexpected end of JSON input

这类报错通常出现在流式响应解析时，响应体被截断或返回了非 JSON 内容。排查：先用第 2 节的 curl 命令直接打 API，看返回是不是合法 JSON。如果 curl 正常但 Claude Code 报错，检查settings.json里有没有写错 model 字段，或者 Base URL 拼错导致请求打到了错误端点。还有一种可能是请求超时，长任务里偶发，重试一次通常能过。

OAuth 相关报错。报错：

Error: OAuth token expired, please re-authenticate

如果你用的是订阅账号登录而不是 API Key，会走 OAuth 流程。token 过期后需要重新认证。但如果你已经配了ANTHROPIC_API_KEY，Claude Code 应该优先用 Key 而不是 OAuth。出现这个报错说明它没读到你的 Key。排查：确认settings.json的env字段拼写正确，ANTHROPIC_API_KEY全大写；确认没有残留的 OAuth 配置文件覆盖，检查~/.claude/目录下有没有旧的认证缓存，必要时清掉重来。

把四类报错对照成表：

排错的核心思路是分层：先确认通道（curl 直连），再确认配置（环境变量 + settings.json），最后确认工具行为（Claude Code 日志）。三层都过了还报错，去接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 对照最新配置说明。别一上来就怀疑通道，大部分问题出在配置拼写和端口占用上。

还有一个容易忽略的点：settings.json是 JSON 格式，不能写注释，不能有尾逗号。一个多余的逗号会让整个文件解析失败，Claude Code 读不到配置就回退到默认行为，表现就是“配置明明写了却不生效”。改完用python -m json.tool ~/.claude/settings.json验证一下格式。

6. 长期编码与 Agent 工作流：把第一个任务变成日常

第一个任务跑通后，真正有价值的是把它变成日常流程。Claude Code 的定位不是补全工具，是 Agent——能读代码、能写、能测、能提交。这意味着你可以把一整类重复需求丢给它，而不是只让它补几行。

我现在的用法是：每个项目根目录放一份CLAUDE.md写清约定，.claude/settings.json配好ignorePatterns和权限，API 通道统一走 TaoToken。新需求进来，先让 Claude Code 读一遍相关文件，再描述需求，它自己拆步骤、跑测试、提交。整个过程我只在关键节点确认，比如 commit message 和权限放开。

如果你要长期跑编码任务或搭 Agent 工作流，Coding Plan 比按量调用更划算，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它适合每天都有编码任务、需要稳定通道的场景。偶尔验证模型能力的话，用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 直接试就行，不用装工具。

回到那个report.py。六分钟提交完之后，我又让它加了 CSV 列名校验和空文件处理，两次都是同样的流程：描述需求、看它跑测试、确认提交。踩过的坑是第一次没配ignorePatterns，启动扫描把.venv全扫了一遍，慢得以为卡死。加上配置后启动秒进。

如果你刚开始，建议第一个任务就选手上真实的小需求，别用玩具项目。真实项目有上下文、有代码风格、有测试约定，Claude Code 的表现更能反映它在你工作流里的价值。装好、配好、跑通、提交，这条链路走一遍，后面就是重复和扩展。