1. 从零搭 Agent为什么先卡在配置这一层很多人第一次做 Agent脑子里想的是「让模型自己调工具、自己跑命令」结果代码写到一半发现真正难的不是循环逻辑而是配置散落一地Prompt 写死在 Python 字符串里模型地址和 Key 硬编码在脚本顶部换一个模型要改三处JSON 配置和代码里的字段名还对不上。个人开发者从零搭建 Agent最该先解决的就是「统一入口」这件事——把 Prompt 调用和 JSON 配置收敛到一条 API 通道上后面加工具、换模型、接 CMD 执行才有地方落脚。这篇就聚焦配置环节运行环境是 Windows 的 CMD 加 Python。我会用 TaoToken 作为统一的 Key 与 API 通道把 Prompt 调用和 JSON 配置文件串起来交付一份可复制的settings.json与config.toml骨架、Key 注入步骤以及一次 CMD 启动验证动作。适合已经会写一点 Python、想让自己的 Agent 最小链路先跑通的人。读完你能得到一个结构清晰的配置层模型地址、Key、Prompt 模板、工具开关都从配置文件读代码只负责调度。先说清楚 TaoToken 在这里的角色。它是一个统一的模型 API 通道你申请一个 Key就能通过同一个 base_url 调用不同模型不用为每个模型单独记地址和密钥。对 Agent 来说这很关键你的config.toml里只写一个base_url和一个api_key换模型只改model字段。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个就行。2. TaoToken 前置拿 Key 与确认通道在写任何配置之前先把 Key 拿到手。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来先存到临时文本里。这个 Key 后面会注入到环境变量不直接写进代码或配置文件避免提交到 Git 时泄露。创建 Key 的时候注意两点一是给它起个能认出来的名字比如agent-local-dev以后多个项目共用时好区分二是如果控制台支持额度或权限设置先按最小可用配Agent 调试阶段用不了太多。拿到 Key 后顺手确认一下模型列表看看你要用的模型名是什么比如常见的对话模型或代码模型名字要和你config.toml里写的完全一致。通道确认这一步别省。你可以先用模型对话页面手动发一条消息确认 Key 有效、通道通。入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个模型发一句「你好」能正常返回就说明 Key 和通道都没问题。这一步花两分钟能省掉后面在代码里排查 401 的时间。Key 注入我推荐用环境变量Windows 下有两种方式。临时会话用 CMD 的set永久写入用setx。下面这条命令把 Key 写进当前用户环境变量重启终端后生效setx TAOTOKEN_API_KEY sk-你的实际Key写完之后关掉当前 CMD 再开一个新的用echo %TAOTOKEN_API_KEY%验证是否读得到。注意setx有长度限制Key 太长可能被截断如果发现读出来不完整改用临时set或者写进本地.env文件由代码加载。我个人习惯是开发阶段用.env部署时再用系统环境变量这样切换环境不折腾。3. 可复制配置settings.json 与 config.toml 骨架配置层我拆成两个文件各管一摊。config.toml管通道和模型参数settings.json管 Agent 行为和 Prompt 模板。分开的好处是通道信息属于环境相关Prompt 属于业务相关改一个不影响另一个。先看config.toml。TOML 格式对小白友好支持注释读起来像配置文件而不是代码# config.toml - 通道与模型配置 [api] # TaoToken 统一通道API 地址不带 UTM base_url https://taotoken.net/api # Key 从环境变量读取不写死在这里 api_key_env TAOTOKEN_API_KEY # 请求超时秒 timeout 60 [model] # 换模型只改这一行 name 你的模型名 temperature 0.1 max_tokens 2048 [agent] # Agent 循环最大轮数防止死循环 max_turns 8 # 是否开启命令执行 enable_cmd true这里有个设计点api_key_env存的是环境变量名不是 Key 本身。代码读配置时先拿这个名字再去os.environ里取值。这样配置文件可以放心提交Key 留在环境里。再看settings.json管 Prompt 模板和工具声明{ system_prompt: 你是一个可以调用本地终端执行命令的助手。请严格只输出 JSON格式为 {\command\: \待执行命令\, \reason\: \原因\} 或 {\final\: \最终回答\}。禁止生成破坏性命令。, tools: [ { name: run_cmd, description: 在 Windows CMD 中执行命令并返回输出, enabled: true } ], safety: { require_confirm: true, blocked_keywords: [format, del /f, rd /s] } }system_prompt里我强制模型只输出 JSON这是 Agent 能解析结果的前提。tools数组先声明一个run_cmd后面加工具就往这里加。safety里的require_confirm控制是否人工确认调试阶段建议开着blocked_keywords是简单黑名单拦掉明显危险的命令。两个文件放同一目录比如agent/下。目录结构大概这样agent/ config.toml settings.json main.py .env # 可选本地开发用如果你用.env存 Key记得在.gitignore里加上它。加载顺序建议是先读.env注入环境变量再读config.toml最后读settings.json。这样本地开发和部署环境用同一套代码。4. 验证请求CMD 启动跑通最小链路配置写完写一个最小main.py把链路串起来。核心逻辑是读配置、拼 Prompt、发请求、解析 JSON、执行命令、把结果拼回对话。下面这段可以直接复制改一下模型名就能跑import json import os import subprocess import sys import tomllib # Python 3.11低版本用 tomli from openai import OpenAI # 读取 config.toml with open(config.toml, rb) as f: config tomllib.load(f) api_cfg config[api] model_cfg config[model] agent_cfg config[agent] # 从环境变量取 Key api_key os.environ.get(api_cfg[api_key_env]) if not api_key: print(f未找到环境变量 {api_cfg[api_key_env]}请先注入 Key) sys.exit(1) client OpenAI(api_keyapi_key, base_urlapi_cfg[base_url]) # 读取 settings.json with open(settings.json, r, encodingutf-8) as f: settings json.load(f) def run_cmd(command: str) - str: 执行 CMD 命令并返回结果 try: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeoutapi_cfg[timeout], encodingutf-8, errorsignore, ) return ( fExit Code: {result.returncode}\n fOutput: {result.stdout[-1000:]}\n fError: {result.stderr[-1000:]} ) except subprocess.TimeoutExpired: return f命令超时: {command} except Exception as e: return f执行出错: {e} def main(): history [{role: system, content: settings[system_prompt]}] print(输入 exit 退出。) while True: user_input input(\nuser: ).strip() if user_input.lower() in (exit, quit): break history.append({role: user, content: user_input}) response client.chat.completions.create( modelmodel_cfg[name], messageshistory, temperaturemodel_cfg[temperature], max_tokensmodel_cfg[max_tokens], ) reply response.choices[0].message.content print(fAI: {reply}) history.append({role: assistant, content: reply}) try: data json.loads(reply) except json.JSONDecodeError: print(返回不是合法 JSON跳过。) continue if final in data: print(f最终回答: {data[final]}) continue if command in data: cmd data[command] print(f\n待执行: {cmd}) print(f原因: {data.get(reason, 无)}) choice input(允许执行[y/n]: ).strip().lower() if choice y: result run_cmd(cmd) print(f结果:\n{result}) history.append({role: user, content: f命令已执行: {result}}) else: history.append({role: user, content: 用户拒绝执行}) if __name__ __main__: main()启动验证在 CMD 里做。先确认 Python 版本tomllib需要 3.11 以上低版本把import tomllib换成import tomli as tomllib并pip install tomli。然后装依赖pip install openai进入agent/目录运行python main.py成功的话你会看到user:提示符。输入一句「列出当前目录的文件」模型应该返回类似{command: dir, reason: 列出当前目录文件}的 JSON程序打印待执行命令并问你y/n。输入yCMD 执行dir输出被拼回对话模型再根据结果给出下一步或最终回答。这条链路跑通说明 Key 注入、通道、配置读取、JSON 解析、命令执行全部打通。实测下来第一次跑最容易卡在模型返回的 JSON 带 markdown 代码块标记比如json包一层。如果你遇到在json.loads前加一步清洗把首尾的代码块标记去掉。这个坑我在好几个模型上都碰到过属于 Prompt 约束不够严的典型表现。5. 本篇常见错排查配置和启动过程中报错集中在几个地方。下面按现象、原因、处理列出来方便对照。现象可能原因处理401 UnauthorizedKey 没读到或写错echo %TAOTOKEN_API_KEY%确认检查config.toml里环境变量名是否一致404 或连接失败base_url 写错确认填的是https://taotoken.net/api不带 UTM 和多余路径tomllib导入失败Python 低于 3.11升级 Python 或改用tomliJSON 解析失败模型返回带代码块标记解析前清洗首尾json和命令执行无输出编码问题subprocess.run里加encodingutf-8, errorsignore死循环模型反复执行同一命令设max_turns上限或在 Prompt 里要求每轮必须推进还有一个隐蔽的坑setx写入的环境变量在同一个 CMD 会话里读不到必须新开终端。我试过在同一个窗口里setx完直接跑脚本结果一直报 Key 为空折腾了十分钟才反应过来。记住setx是给未来会话用的当前会话要用set。另外如果你的 Agent 要长期跑、频繁调用按量计费的方式可能不够省心。TaoToken 有 Coding Plan 这类长期方案入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合把 Agent 当日常工具用的场景。调试阶段先用按量跑顺了再考虑。配置文件的字段名要和代码里读的完全一致大小写敏感。config.toml里写base_url代码里读api_cfg[base_url]差一个字母就是 KeyError。建议改配置后先跑一次python -c import tomllib; print(tomllib.load(open(config.toml,rb)))确认能解析。6. 把配置层固定下来再往上加工具最小链路跑通之后你的 Agent 就有了一个稳定的底座通道统一在config.toml行为统一在settings.jsonKey 在环境变量里。接下来加工具只需要在settings.json的tools数组里声明在main.py里加对应的执行函数Prompt 里补一句工具说明。换模型只改config.toml的name字段其他不动。如果你在接入过程中遇到通道或 Key 的问题先看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 常见报错和参数说明都在里面。需要新建或管理 Key 就去 https://taotoken.net/api-keys 想先手动验证模型返回格式就去 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发几条消息看看。长期编码和 Agent 场景可以了解 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实用习惯每次改完配置先跑一次「列出当前目录文件」这种最简任务验证链路再上复杂任务。配置层的价值就在于链路验证和业务逻辑解耦了出问题能快速定位是通道、配置还是 Prompt。把这一步做扎实后面加多少工具都不慌。