★ FEATURED ARTICLE 1. 从“只会聊天”到“动手做事”OpenClaw 的 Agent 落地场景大语言模型和 AI Agent 的区别用一句话就能说清传统 LLM 只动口不动手。你让它“帮我生成一个视频并上传到网站”它会给你一份制作流程清单但它没法注册账号、没法操作外部平台、没法真的把文件传上去。而 AI Agent 做的事情是先创建账号并输入自我介绍调用绘图工具生成图像并上传搜集资料写演讲稿调用视频制作工具和语音合成工具合成影片最后上传到网站。整条链路它自己跑完。OpenClaw 在这个链路里扮演什么角色它本身不是 AI而是连接用户和大语言模型的桥梁与躯干。OpenClaw 拦截并解析大模型生成的文字指令然后在用户的电脑系统Terminal/Shell上真正执行这些操作——读取文件、写入代码、执行系统命令。执行完后再把结果传回给大模型。这个“生成指令→本地执行→回传结果”的循环就是 Agent 动手做事的核心机制。为什么这件事值得关注因为大模型的能力已经足够强但它的输出始终停留在文字层面。Agent 架构补上了“行动力”这一环。System Prompt 锚定身份工具调用让模型能操作外部世界Sub-agent 机制解决复杂任务的上下文压力Heartbeat 机制让 Agent 能定时主动工作。这套组合下来模型从“百科全书”变成了“数字员工”。我试过用 OpenClaw 跑一个多步骤任务让 Agent 读取本地 question.txt 里的问题把答案写入 ans.txt然后汇报完成。整个过程不需要我手动干预Agent 自己完成了“读文件→理解内容→写文件→汇报”的闭环。这个场景虽然简单但它验证了 Agent 的核心能力链路。适合谁来跟做这篇教程如果你已经能用大模型 API 做基本的对话调用想进一步理解 Agent 是怎么把“对话”变成“执行”的这篇内容就是为你准备的。我会给出可复制的 System Prompt 模板、Sub-agent 配置示例以及在 TaoToken 统一 Key/API 通道下完成一次任务编排的验证动作。你不需要从头搭建框架跟着步骤走就能跑通一次完整的 Agent 任务。2. TaoToken 前置统一 Key/API 通道的配置与模型选型在跑 OpenClaw 之前你需要一个稳定的大模型 API 通道。TaoToken 提供统一的 Key 和 API 入口兼容 OpenAI 风格的接口格式OpenClaw 可以直接对接。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先完成 API Key 的创建。打开 https://taotoken.net/api-keys 登录后创建一个新的 Key。建议给这个 Key 起一个能识别用途的名字比如 “openclaw-agent-test”方便后续排查问题时定位。创建完成后把 Key 复制出来格式通常是 sk- 开头的一串字符。这个 Key 只会显示一次丢了就得重新创建。接下来确认你要用哪个模型。OpenClaw 的 System Prompt 和 Sub-agent 机制对模型的指令遵循能力有一定要求。如果你跑的是任务编排类的场景建议选指令遵循较强的模型如果只是做简单的文件读写验证通用模型就够用。你可以在 https://taotoken.net/models 查看当前可用的模型列表和对应的 Model ID。记下你要用的 Model ID后面配置里会用到。TaoToken 的 API 基础地址是 https://taotoken.net/api 兼容 OpenAI 的 /v1/chat/completions 接口。OpenClaw 的配置文件里需要填三个东西Base URL、API Key、Model ID。这三个参数缺一不可后面我会给出具体的配置片段。如果你打算长期跑 Agent 任务建议了解一下 Coding Plan。Agent 的调用频率比普通对话高得多尤其是 Sub-agent 机制会频繁发起子任务请求。Coding Plan 在调用额度和成本控制上更适合这种场景。具体可以看 https://taotoken.net/coding-plan 。配置完成后你可以先用模型对话功能快速验证 Key 是否可用。打开 https://taotoken.net/chat 选一个模型发一条简单的消息确认能正常返回结果。这一步能排除掉 Key 无效或额度不足的问题避免后面在 OpenClaw 里排查时多绕弯路。3. 可复制配置System Prompt 模板与 Sub-agent 配置示例这一节给出可以直接复制使用的配置片段。先看 System Prompt 模板。OpenClaw 的 System Prompt 通常由多个 Markdown 文件组成核心是 IDENTITY.md 和 SOUL.md。下面是一个精简版的 IDENTITY.md 模板你可以直接复制到本地文件里# IDENTITY.md ## 基本信息 - 名称小爪 - 角色本地任务执行助手 - 运行环境OpenClaw 框架 TaoToken API 通道 ## 行为准则 1. 每次执行文件操作前先确认目标路径是否存在 2. 遇到高危命令rm、mv、dd 等必须暂停并请求人工确认 3. 任务完成后用一句话汇报结果不输出多余解释 4. 如果连续两次执行同一操作失败停止重试并上报错误 ## 能力边界 - 允许操作的工作目录~/agent-workspace/ - 禁止访问的路径/etc/、/System/、~/.ssh/ - 单次任务最大执行时间120 秒SOUL.md 负责性格和沟通风格可以写得更简短# SOUL.md ## 沟通风格 - 简洁直接不寒暄 - 汇报结果时用“已完成”开头 - 遇到不确定的情况先问再做 ## 记忆策略 - 每完成一个任务把关键信息写入 memory.md - 每周日压缩一次 memory.md保留最近 7 天的摘要接下来是 Sub-agent 的配置示例。OpenClaw 通过 Spawn 工具创建子代理子代理的配置通常放在 subagent.toml 或类似的配置文件中。下面是一个 TOML 格式的配置片段[subagent] enabled true max_depth 1 timeout_seconds 180 [subagent.restrictions] can_spawn_subagent false allowed_tools [read_file, write_file, search] max_context_tokens 8000 [subagent.model] base_url https://taotoken.net/api api_key sk-你的Key model_id 你的ModelID这里有几个关键参数需要解释。max_depth 1 表示子代理不能再创建子代理这是防止无限递归的必要限制。can_spawn_subagent false 是同样的目的双重保险。allowed_tools 限制了子代理能调用的工具范围避免它执行超出预期的操作。max_context_tokens 控制子代理的上下文窗口因为子代理通常只处理一个子任务不需要太大的上下文。主代理的配置文件里需要填 TaoToken 的接入信息。如果你用的是 JSON 格式的 settings 文件可以这样写{ llm: { base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: 你的ModelID, max_tokens: 4096, temperature: 0.3 }, agent: { system_prompt_dir: ./prompts/, memory_file: ./memory.md, heartbeat_interval: 1800, exec_timeout: 120 } }temperature 设成 0.3 是为了让 Agent 的输出更稳定减少幻觉导致的误操作。heartbeat_interval 是心跳间隔单位是秒1800 秒就是 30 分钟。exec_timeout 是单次命令执行的超时时间超过这个时间会强制中断。配置写完后把文件放到 OpenClaw 的工作目录下。建议先用一个测试目录跑通流程确认没问题再迁移到正式环境。4. 验证请求跑通一次完整的 Agent 任务编排配置就绪后我们来跑一次完整的任务编排。这个验证动作的目标是让 Agent 读取一个本地文件理解内容执行一个计算或转换把结果写入另一个文件最后汇报完成。整个过程会经过 System Prompt 加载、工具调用、结果回传三个环节。先准备测试文件。在工作目录下创建 question.txt内容写一行简单的算术题mkdir -p ~/agent-workspace echo 11 ~/agent-workspace/question.txt然后启动 OpenClaw。启动命令根据你的安装方式可能不同常见的是cd ~/agent-workspace openclaw start --config ./settings.json启动后OpenClaw 会加载 System Prompt 文件把 IDENTITY.md 和 SOUL.md 的内容注入到每次请求的上下文中。你可以在日志里看到类似 “Loaded system prompt: 1247 tokens” 的输出这说明身份设定已经生效。接下来给 Agent 下达任务。在 OpenClaw 的交互界面里输入读取 question.txt计算结果把答案写入 ans.txt然后告诉我完成。Agent 的处理流程是这样的它先输出一个工具调用指令类似[tool_use] Read(question.txt)。OpenClaw 拦截这个指令在本地执行读取操作把文件内容 “11” 回传给模型。模型看到内容后生成下一个指令[tool_use] Write(ans.txt, 2)。OpenClaw 执行写入把结果回传。模型确认写入成功后输出 “已完成答案 2 已写入 ans.txt”。你可以在终端里验证结果cat ~/agent-workspace/ans.txt如果输出是 “2”说明整条链路跑通了。这个过程验证了三个关键点System Prompt 正确加载、工具调用指令被正确解析和执行、结果正确回传给模型。如果你想验证 Sub-agent 机制可以给一个更复杂的任务比较 question.txt 和 question2.txt 的内容分别写摘要到 summary1.txt 和 summary2.txt然后比较两个摘要的差异。主代理会通过 Spawn 工具创建两个子代理一个处理 question.txt一个处理 question2.txt。每个子代理独立完成读取和摘要写入主代理只接收两份摘要然后做比较。你可以在日志里看到 “Spawned subagent: task-1” 和 “Spawned subagent: task-2” 的记录。子代理完成后主代理的上下文里只有两份摘要而不是两个文件的完整内容这就是上下文工程的实际效果。验证完成后检查 memory.md 文件看看 Agent 是否把这次任务的关键信息写入了记忆文件。如果配置了 heartbeat等 30 分钟后观察 Agent 是否自动执行了 HEARTBEAT.md 里的例行任务。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth跑 Agent 任务时最容易遇到的几个报错我按出现频率排一下。401 Unauthorized是最常见的。报错信息通常是{error: {message: Invalid API key, type: invalid_request_error}}。原因一般是 API Key 填错了、Key 被删了、或者 Key 没有绑定正确的模型权限。排查步骤先确认 settings.json 里的 api_key 字段和你在 https://taotoken.net/api-keys 创建的一致然后确认 base_url 是 https://taotoken.net/api 而不是其他地址最后用 curl 直接测一下 Key 是否有效curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model: 你的ModelID, messages: [{role: user, content: test}]}如果 curl 返回正常但 OpenClaw 报 401检查配置文件里是否有空格或换行符混入 Key。local proxy failed通常出现在 OpenClaw 尝试通过本地代理转发请求时。报错信息类似Error: local proxy failed to connect to upstream。原因可能是本地代理端口被占用、代理配置和 TaoToken 的 API 地址冲突、或者网络环境导致连接超时。排查步骤先确认没有其他程序占用 OpenClaw 的默认代理端口然后检查配置文件里是否有多余的 proxy 设置如果有删掉或注释掉最后确认 base_url 直接指向 https://taotoken.net/api 不要经过额外的转发层。reading choices 报错的完整信息通常是Error: reading choices: unexpected end of JSON input或Error: reading choices: invalid character。这说明 OpenClaw 收到了 API 返回的数据但解析失败了。原因可能是模型返回了非标准格式的内容、API 返回了错误信息但被截断、或者网络传输过程中数据损坏。排查步骤先在 OpenClaw 的日志里找到原始返回内容看看是不是完整的 JSON然后确认 Model ID 是否正确有些模型不支持某些参数会导致返回格式异常最后检查 max_tokens 是否设得太小导致返回被截断。OAuth 相关报错通常出现在你尝试用 OAuth 方式接入而不是 API Key 时。报错信息类似OAuth token expired或OAuth callback failed。如果你用的是 TaoToken 的 API Key 接入不应该出现 OAuth 报错。如果出现了检查配置文件里是否误开了 OAuth 模式把认证方式改回 api_key 即可。如果你确实需要用 OAuth确认回调地址配置正确并且 token 没有过期。还有一个容易忽略的问题Sub-agent 创建失败。报错信息可能是Spawn failed: max depth exceeded或Subagent timeout。前者说明子代理试图创建子代理检查 subagent.toml 里的 max_depth 和 can_spawn_subagent 设置后者说明子代理执行超时适当调大 timeout_seconds 或检查子任务是否过于复杂。6. 语义一致 CTA从验证到长期运行的路径跑通一次任务编排之后你可能会想把这个流程固化下来让 Agent 长期在后台工作。这时候需要关注几个点记忆文件的压缩策略、心跳任务的配置、以及 Sub-agent 的权限控制。记忆文件如果一直追加不压缩迟早会撑爆上下文窗口。建议在 SOUL.md 里明确写入压缩规则比如每周日把 memory.md 里超过 7 天的内容压缩成摘要。你也可以手动触发压缩让 Agent 执行一次 “压缩 memory.md保留最近 7 天的关键信息” 的任务。心跳任务的配置在 settings.json 的 heartbeat_interval 字段。默认 1800 秒是 30 分钟你可以根据任务频率调整。HEARTBEAT.md 里写的例行任务要尽量具体比如 “检查 ~/agent-workspace/inbox/ 是否有新文件如果有读取并摘要到 daily.md”。模糊的指令会让 Agent 在心跳时做无意义的操作浪费调用额度。Sub-agent 的权限控制是安全底线。allowed_tools 里只放必要的工具can_spawn_subagent 始终设为 falsemax_depth 设为 1。这样即使主代理被提示词注入攻击子代理也无法执行超出预期的操作。如果你打算把 Agent 用在更复杂的场景比如多步骤的任务编排、长时间运行的后台任务、或者需要频繁调用模型的场景可以了解一下 Coding Plan 的额度方案https://taotoken.net/coding-plan 。Agent 的调用模式和普通对话不同Sub-agent 机制会产生大量子任务请求提前规划好额度能避免中途断掉。接入文档在 https://taotoken.net/doc 里面有完整的 API 参数说明和错误码对照表。遇到报错时先查文档大部分问题都能找到对应的解决方案。最后一步把你跑通的配置和 System Prompt 模板保存下来作为后续任务的起点。每次新建 Agent 时复制这套配置改一下 IDENTITY.md 里的角色描述和工作目录就能快速启动一个新的 Agent 实例。
阅读完成 · 觉得有帮助？
