Claude Code 这类工具真正难跑通的地方往往不是模型能力而是 Harness 配置。Learn Claude Code 这个开源项目把 Agent Loop 和 Subagent 机制拆成 s01-s12 逐步演示核心观点很直接模型才是 Agent代码只是 HarnessHarness 只做三件事——跑循环、执行工具、把结果回传给模型。这篇就按这个思路用 TaoToken 统一 Key 和 API 通道把 config.toml 与 settings.json 骨架配好再触发一次 Loop 和 Subagent 调用让整套骨架先跑起来。1. 先理解 Agent Loop 与 Subagent 到底在解决什么Learn Claude Code 把 Agent 定义成一个永不停止的循环用户发请求模型判断要不要调工具调完把结果塞回上下文模型再判断下一步。所有复杂机制都叠加在这个 Loop 上代码不写死流程。但裸 Loop 有四个典型痛点项目里对应了四个解法痛点表现项目解法Context Fade 失忆多步任务丢进度、重复执行、跑偏TodoWrite 约束最多 20 项仅 1 个 in_progressContext Pollution 探索垃圾父 Agent 上下文被读文件污染Subagent 隔离主进程写代码子进程读文件知识瓶颈大量 Skill 无法全量加载Skills 渐进式加载先读目录再按需拉取上下文爆表窗口有限不能无限增长三层压缩Micro / Auto / Manual compactSubagent 在这里不是独立进程而是一个工具。模型判断需要探索时调用它子进程读完文件只回传结论父进程上下文保持干净。这就是 Harness 的边界它不替模型做决策只负责把工具执行结果结构化返回。2. TaoToken 前置统一 Key 与 API 通道在写配置之前先把 Key 和通道准备好。TaoToken 的作用是给 Claude Code 这类工具提供统一的 API 入口避免在多个配置文件里散落不同来源的 Key。你需要拿到两样东西API Basehttps://taotoken.net/apiAPI Key在控制台创建建议按项目单独建 Key方便后续轮换控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite注意Key 只放在本地环境变量或本地配置文件里不要提交到 Git。项目里建议用.env或系统环境变量注入。如果你还没决定用哪种接入方式可以先看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite3. 可复制骨架config.toml 与 settings.json下面这套骨架的目标是让 Harness 能读到统一的 API 通道同时把 Loop 和 Subagent 的关键参数暴露出来。你可以直接复制后改 Key。3.1 config.toml# config.toml # Harness 主配置Loop 与 Subagent 共用同一 API 通道 [api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 max_tokens 8192 timeout_seconds 120 [loop] max_iterations 30 tool_result_keep_recent 3 auto_compact_threshold_tokens 50000 enable_manual_compact true [todo] max_items 20 max_in_progress 1 stale_rounds_alert 3 [subagent] enabled true max_concurrent 3 isolate_context true return_only_summary true [skills] progressive_loading true index_file ./skills/index.json max_skills_per_turn 5几个参数值得单独说tool_result_keep_recent 3对应 Micro 压缩只保留最近三条工具结果更早的替换成工具名占位符。auto_compact_threshold_tokens 50000对应 Auto 压缩超过阈值先落盘 JSON 再摘要。isolate_context trueSubagent 隔离开关子进程读文件不污染父上下文。progressive_loading trueSkills 按需加载先读 index 再拉具体 skill。3.2 settings.json{ env: { TAOTOKEN_API_KEY: sk-your-key-here, ANTHROPIC_BASE_URL: https://taotoken.net/api }, harness: { config_path: ./config.toml, workspace_root: ./workspace, inbox_dir: ./workspace/inbox, tasks_dir: ./workspace/tasks, history_dir: ./workspace/history }, subagent: { inbox_poll_before_llm: true, git_worktree: true, worktree_root: ./workspace/worktrees }, compact: { micro_enabled: true, auto_enabled: true, manual_tool_name: compact } }inbox_poll_before_llm true对应项目里的 JSONL 收件箱机制每次调模型前先查邮箱有消息就并入上下文。git_worktree true让每个 Subagent 在自己的目录下干活避免两个 Agent 改同一文件导致回滚困难。4. 验证动作触发一次 Loop 与 Subagent 调用配置写完后不要急着跑复杂任务先用一个最小动作验证 Loop 和 Subagent 是否真的被触发。4.1 设置环境变量export TAOTOKEN_API_KEYsk-your-key-here export ANTHROPIC_BASE_URLhttps://taotoken.net/api4.2 启动 Harnesspython -m harness.main --config ./config.toml --settings ./settings.json启动后观察日志里是否出现loop started和api base https://taotoken.net/api。如果 base 不对说明 settings.json 没被读到。4.3 触发 Loop在交互窗口输入一个需要多步的任务帮我分析当前项目的目录结构并给出模块划分建议预期日志顺序[loop] iteration 1 [llm] request - taotoken [tool] list_dir called [tool] read_file called [loop] iteration 2 [llm] request - taotoken [loop] done如果只出现一次iteration 1就结束说明 Loop 没继续检查max_iterations是否被覆盖成 1。4.4 触发 Subagent输入一个明确需要探索的任务用 Subagent 扫描 src 下所有 Python 文件汇总每个文件的职责预期看到[subagent] spawn idsub-001 [subagent] isolated contexttrue [subagent] read_file src/agent.py [subagent] read_file src/tools.py [subagent] summary returned [loop] iteration 2关键验证点父进程日志里不应该出现具体的文件内容只应该出现 Subagent 返回的摘要。如果父上下文里出现了完整文件内容说明isolate_context没生效。5. 本篇常见报错与排查5.1 401 Unauthorized[llm] error: 401 Unauthorized原因通常是TAOTOKEN_API_KEY没注入或者 settings.json 里的 env 没被加载。先确认echo $TAOTOKEN_API_KEY如果为空重新 export。如果 settings.json 里写了 Key 但环境变量为空检查 Harness 是否真的读取了 settings.json 的 env 段。5.2 Loop 不继续[loop] iteration 1 [loop] done模型没有返回工具调用Loop 就结束了。检查两点一是模型是否支持 tool use二是工具定义是否注册到了请求里。可以在日志里搜tools字段确认。5.3 Subagent 上下文污染父进程日志里出现完整文件内容说明 Subagent 没有隔离。检查config.toml里isolate_context是否为 true以及 Subagent 是否真的以子进程方式启动。如果 Subagent 和主进程共用同一个 messages 列表隔离就是假的。5.4 Auto compact 不触发[tokens] current62000 threshold50000 [compact] skipped阈值到了但没触发通常是auto_enabled被覆盖或者 token 计数没接上。检查compact.auto_enabled和 token 统计模块是否在每次 LLM 调用前执行。5.5 Skills 全量加载日志里一次性出现 100 个 skill 加载记录说明渐进式加载没生效。检查skills.index_file是否存在以及progressive_loading是否为 true。正确行为是先读 index只加载当前任务相关的 skill。6. 长期编码场景用 Coding Plan 固定通道如果你打算把这套 Harness 长期用于日常编码建议把 API 通道固定下来避免每次换 Key 都改配置。Coding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite模型对话入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewriteClaude Code 相关接入参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite把 Key 和通道固定后Harness 的 config.toml 基本不用再动后续只需要调整 Loop 参数和 Subagent 并发数。这套骨架跑通后再往上叠加 TodoWrite、Skills 渐进加载、三层压缩就是 Learn Claude Code 里 s03 到 s07 的完整路径。先让 Loop 转起来再让 Subagent 隔离生效最后才是压缩和协作。顺序反了排查成本会高很多。