按官方 Quickstart 的四步走:装好客户端、让 Agent 读懂仓库、改一处小代码、再逐条审查 diff。
📚 AI教程资源
精选 AI 工具的使用教程、上手指南与深度评测,共 940 篇,893 篇新内容
Agent 由指令、工具、模型三块拼成;检查点负责回滚,排队消息与即时消息负责控制它的节奏。
Cloud Agent 在隔离的 Ubuntu 机器上跑,环境配得好不好直接决定它能不能自己验证改动;三层配置与解析顺序。
都叫命令行编程 Agent,但入口、模式、会话管理与自动化形态各不相同,按官方文档逐项对比。
project rule 必须是 .mdc,靠 alwaysApply、description、globs 三个字段决定何时进入上下文;写错扩展名等于没写。
MCP 让 Cursor 直接连外部工具与数据源。选 stdio 还是远程 HTTP、什么时候要填静态 OAuth 凭据,是配置时真正的分岔。
Bugbot 分析 PR diff 并在代码行上留下问题说明与修复建议,每次 PR 更新自动跑;它只审 diff、会跳过过大的 PR 与 linguist-generated 标注的文件,检查结论默认是 neutral。
终端里用 agent 命令开交互会话,三种模式与编辑器一致;接 CI 用 -p print 模式;会话可 ls、resume、continue,加 & 前缀能把任务交给云端代理继续跑。
Plan Mode 会先反问你没说清的地方、读完相关代码,再给出一份可以逐条修的实施方案;计划默认存家目录,确认后才进入编码。
Debug Mode 不让代理直接猜着改代码,而是先列假设、加日志、让你复现,拿到运行时证据后只改几行。
打开 Agents Window 里的浏览器,用 Annotate 点选元素、框选区域、直接改文案或调 CSS,每条批注都带截图和选择器路径发给代理。
Agent Review 在 Cursor 内部对本地改动做专项代码评审,可按每次提交自动跑、用 /agent-review 手动触发,或从源代码管理面板对比整批改动。
Agents Window 把本地、云端、远程 SSH 的代理收进同一个工作台,支持并行代理、worktree 隔离与新 diff 视图,随时切回传统编辑器。
语音对话是与代理的双向通话,语音代理负责听和说、把编码任务转交给当前会话的代理;Agents Window、IDE、网页与 iOS 都能用。
print 模式让 agent 命令不进入交互:默认只回最终答案,配 --force 才真改文件,输出可选 text、json 或 stream-json。
CLI 里可以直接跑 shell 命令,但每条命令独立执行、30 秒超时、不支持交互式进程;cd 不跨条生效,要用 cd 目录 && 命令。
描述一个仪表盘或内部工具,云代理会建仓库、配 Postgres、加登录与密钥,发布前跑四项固定检查,通过后给出可访问链接。
Project 面向跨多天的大活:协调者只做规划与分派、不写代码,共享上下文随项目累积,还能订阅 Slack、PR 与定时信号。
Build 是预构建好的云代理环境快照:克隆仓库、跑完 install、记下每个仓库的 commit;新 Build 失败时仍沿用上一个成功版本。
在 Linear 里把 issue 的负责人选成 Cursor,或评论里 @Cursor,就能让云代理开工并自动开 PR;单个 issue 还能用 [key=value] 临时指定仓库与分支。
Cursor 在 Notion 里以代理形式出现,可在 spec 页面评论里 @ 它、把任务库的条目指派给它;运行在沙箱化的云代理虚拟机中,权限按页面单独授予。
deeplink 可以带上一段提示词、一个自定义命令或一条规则,别人点开后在 Cursor 里预填,必须本人确认才会执行。
读文件与搜代码默认不拦,改工作区文件直接落盘,配置文件与终端命令要审批;MCP 每个工具调用单独确认,网络请求只放行三类目标。
钩子是独立进程,用标准输入输出换 JSON;命令式跑脚本、提示式问模型,退出码 0 走输出、2 直接拦、其它默认放行;云代理只认命令式钩子,且只读阶段不加载。
技能是带 YAML frontmatter 的 SKILL.md 文件夹,资源按需加载;四个默认目录外还兼容 Claude 与 Codex 目录,paths 控制生效范围,缺 description 代理基本不会自己选。
每个子代理自带独立上下文窗口,前台阻塞、后台并行;内置 Explore 与 Browser,自定义子代理靠 .cursor/agents 里的 frontmatter 控制模型、只读与后台运行。
插件把 rules、skills、agents、commands、MCP 服务器与 hooks 打成可分发的包;Cursor 插件格式与 Agent Plugins 开放标准并存,团队市场可设默认关、默认开与强制安装。
触发器覆盖定时、代码托管事件、Slack、Webhook、Linear、Sentry、PagerDuty;仓库设置决定它能不能改代码,工具决定它能发消息还是开 PR。
手机端不是精简聊天框,能选 worker、看子代理、审 PR 并合并;Remote Control 把代理循环放到云端、工具调用留在你的电脑上,代价是电脑必须保持在线。
把工单 assign 给 Cursor 或评论里 @Cursor 就能起一次云代理;仓库按显式参数、工单内容、路由规则、最近活动、默认仓库的顺序判定。
@ 能挂文件、终端输出、历史对话、git diff 与内置浏览器;斜杠加 Option/Alt+Enter 把技能固定成模式;上下文环能按系统提示、工具、规则、技能、MCP 等分类看占用。
开 PR 时写落地方案,部署后按日志、指标、链路复查,并在部署当时、20 分钟、1 小时、1 天、3 天后各查一次;方案没写好可以让人在评论里改。
按代码归属与提交历史指派评审人,低风险 PR 可自动批准;策略文件只认精确文件名,冲突时从更具体、更严格;改了策略文件的那次 PR 不能用新内容放宽要求。
Cursor 以带标签的临时设备加入你的 tailnet,每次连接现签一把 10 分钟的密钥;服务器必须是 https,且只能走标签策略允许的主机与端口。
一个安装只属于一个 Cursor 账号或团队,被别处占用时连接会直接报错;团队间可共享安装,但同一仓库只能有一个团队开 Bugbot;org 用 IP 白名单时走出口代理。
自建客户端通过 stdio 上的 JSON-RPC 2.0 跟 Cursor CLI 对话,会话要依次走 initialize、认证、session/new、session/prompt;权限请求不回,工具执行就卡在那里。
加 -w 让代理在新的 git worktree 里动手,检出目录落在 ~/.cursor/worktrees/<仓库>/<名字>;--workspace 只决定仓库根;Ctrl+R 逐文件过改动,消息前面加符号可把活交给云代理。
npm 包名带 @ 前缀,Node.js 22.13 起步;Agent 保存会话状态、Run 是一次提示词提交;同一个 Agent.create 里传 local 还是 cloud,决定代理循环跑在你机器上还是 Cursor 的隔离虚拟机里。
pip install cursor-sdk,Python 3.10 起;Agent.create 传 local 或 cloud,agent.send(...).text() 取最终文本;服务端与机器人场景用 AsyncClient.launch_bridge,没有默认可用的全局异步客户端。
桥是一个本地小服务,内嵌 TS SDK,用 Connect/protobuf 暴露同一套代理能力;监听回环地址、每次 RPC 带 bearer、两个密钥各管一段,经典 gRPC over HTTP/2 连不上。
只支持 dev.azure.com,Server 不支持;云代理与 Bugbot 可用,自动化与安全代理还没有;Bugbot 需要 Entra 管理员一次性同意、再把服务主体加进各项目的管理员组。
集成依赖项目访问令牌,而 GitLab 免费版不提供该令牌,所以需要 Premium 或 Ultimate;云代理以令牌的 bot 用户身份提交,令牌拿不到时会退回 cursoragent@cursor.com 并被推送规则挡住。
云代理克隆、推分支、开 PR 用的是你本人连上的 Bitbucket 账号,Bugbot 的评论与状态用的是工作区里安装的 Cursor 应用;两者权限来源不同,缺一个就会有一半功能不工作。
前提是付费 Cursor 套餐加 2025.1 以上、启用 AI Assistant 插件的 JetBrains IDE;在 AI Chat 面板的代理列表里从注册表添加 Cursor,IDE 当客户端、Cursor 当服务端,按用量计费。
频道里 @Cursor 加提示词即可起云代理,它按消息内容、近期活动与默认仓库判断目标;repo、env、branch、model 四个选项里 env 优先于 repo,线程里再 @ 一次是追加指令。
Slack 集成把选项写在消息任意位置都能识别,但三反引号代码块里的 key=value 会被忽略并原样留在提示词里;autopr、channel、pool 这类只在行内写法才生效。
Xcode 26.3 起内置 MCP 服务,xcrun mcpbridge 把协议转成 Xcode 的 XPC 调用;在 Cursor 里注册一条 stdio 服务即可读写文件、构建、跑测试、截 SwiftUI 预览、搜苹果文档。
官方文档把接口分成七类:Admin、Analytics、AI Code Tracking、Bugbot、Cloud Agents、Origin 加两个 SDK。它们的鉴权方式、限流额度、能否缓存都不一样,选错一类会白写很多代码。
它和本地 agent 用的是同一套 agent 逻辑,区别在于跑在隔离虚拟机里,有克隆好的仓库、装好的依赖、密钥、启动命令和出网权限。能不能干成事,八成取决于环境配得对不对。
Cloud Agents 的后台配置集中在四块:环境版本管理、默认模型与分支、三档网络模式、以及安全侧的四个开关。其中 team follow-ups 牵涉到密钥横向移动,官方给的风险说明值得单独读一遍。
环境、密钥与出网、本地可测性、上下文供给——Cursor 把这四件事排在提示词之前。它还建议把 agent 当成一个聪明但缺少上下文的开发者,工具要照着 agent 的使用习惯反过来改。
Security Review 盯合并前的改动,Vulnerability Remediation 定期扫存量代码并让 agent 写测试证明漏洞成立。两者都跑在 Automations 上、都依赖 Cloud Agents,但触发方式完全不同。
扫描器报出的问题存在 findings 里,验证和修补走 verifications。整套接口是「先列出、再排队、最后轮询」的三段式,企业版可用,每个端点每分钟 20 次。
Cursor 的扩展体系现在由六种可组合的组件构成,Customize 页负责按用户、工作区、团队三级作用域把它们装起来、开起来、看排行榜。
Bot 不是一次性对话,而是有名字、有职责、记忆会累积的角色。每个 Bot 共用你账号名下的一台持久云电脑,带浏览器、文件系统和终端,所以任务能落到真实工具里而不是停在草稿上。
从下载到第一次交付只有六步,其中第三步最关键——在第一条消息里就把职责、来源和审批边界定死,并让 Bot 记住。任务描述要包含结果、来源、约束、交付物和停在哪。
把 Bot 当同事用,真正要设计的不是提示词,而是四件事:它记什么、几个 Bot 怎么分工、共享电脑上的权限怎么划、以及一次成功的流程怎么变成能重跑的东西。
销售外呼、人才搜寻、付费投放、费用管理、产品性能、缺陷复现、客户健康、幕僚长——官方给的不是模板,而是八种「职责边界怎么写」的范例,共同点是最后一句都在划红线。
一般页放时区与自动复核规则,电脑页放本地执行与流量路由,用量页看周额度,更新页分应用与云电脑两条线。团队里管理员下发的规则会锁定,且与本机策略互相独立。
Cursor 自己的代码托管目前是早期测试阶段。启用顺序是认领命名空间、建仓或从 GitHub 同步、再分配权限;命名空间在测试期内不能改,这一步值得慢一点。
仓库的 Settings 管可见性、协作人与分支保护,codebase settings 管整个团队的启用权限、Slack 通知与频道订阅。团队仓和个人仓的设置页还不一样。
最近几个版本集中在四块:环境复用、自托管 worker 的归属与健康检查、子代理的模型回退、以及 Windows 上的编码问题。这些恰好都是「用久了才会遇到」的坑。
付费套餐给的是一个按周重置的用量池,自有模型从池里扣、第三方模型走预付额度;Auto 分成本、均衡、智能三档,路由结果决定这次算哪边的钱。具体费率以官网为准。
同一天发的两个 3.27 各有重心。窗口端把 Project 的焦点、任务看板和标签恢复做扎实;编辑器端处理非 UTF-8 文本、降低动效、以及 Mermaid 图的查看方式。
版本说明通常最枯燥,但它暴露的是真实使用中的断裂点。最近几个版本集中在三件事:多团队归属、Claude Code 钩子的拒绝语义、以及本地数据库打不开时怎么不丢结果。
Codex 走的是 Responses API,DeepSeek 原生支持这套协议。所以接入的难点不在协议,而在两份配置文件:models.json 负责告诉 Codex「这个模型有多大、支持哪些档位」,config.toml 负责告诉它「去哪里找」。
已经装过 Claude Code 的人只需要改环境变量;从零装的人还要先备 Node 18 与 Git。真正值得记住的是模型名映射规则——opus 开头的走旗舰,haiku 与 sonnet 开头的都落到 flash。
Codex 通过 Responses API 直连 Kimi,关键配置是 wire_api=responses、env_key 和 model_context_window。配置改了不生效,通常是没重启或本地路由工具在改写文件。
Claude Code 会按场景调用不同档位的模型。只配主模型时,后台摘要和子 Agent 会因为请求了不存在的模型名而报错。settings.json 的 env 还会覆盖终端里的同名变量。
线程事件默认最旧在前,倒序时翻页令牌往更早走;会话级接口只能看到协调者线程。历史末尾的流游标可以直接接到实时流上,增量预览永远不进历史。
Admin API 的游标只携带页位置,服务端不会校验你翻页时参数是否与首页一致。复用旧游标配上新过滤条件,得到的是跨两次查询串在一起的页,而不是报错。
列出批处理任务时,翻页参数是上一页最后一条任务的 ID,而不是序号或偏移量。判断是否还有下一页看 has_more,每一条都带已完成数与总数,可以直接拿来盘点积压。
官方给出的 Codex 接法是改 config.toml 的 model_provider 段,五个字段里 wire_api 必须写 responses,验证用 codex exec 跑一句固定问题。
Codex harness 把 OpenClaw 工具挂在 openclaw 命名空间下,默认以 searchable 方式延迟加载;与 Codex 原生工作区操作重复的九个工具不再重复暴露,progress_card 例外保留。策略在构造工具时抓成快照,改完需要重启网关才生效。
有限白名单一定受限;deny 名单里只要有一个名字不在审计过的安全集合内也受限;disableTools 等于空白名单。受限回合没有环境选择、没有原生 Code Mode,也不宣告原生委派助手。
动态工具的超时不是单一常量,而是一条按先后取值的阶梯:单次 timeoutMs、timeoutSeconds 加两段 30 秒、图像与媒体各自的默认值、message 的 600 秒外壳预算,最后才落到 90 秒。代理等待类工具另有 30 秒收尾宽限。
沉默、工具输出完成、看起来完整的助手消息都不算结束,只有身份精确匹配的 turn/completed 才对。原生终止之后还有两分钟绝对本地结算预算,超期仍能把完整答复保留成降级成功。
本地 stdio 默认是三项全开的 YOLO 姿态,理由是无人值守的回合不该卡在没人应答的原生审批上。系统要求文件不认可时自动降级为 guardian,而 tools.exec.mode 设成 auto 会强制 guardian 并丢掉旧的不安全覆盖。
Codex 子进程只持短期访问令牌,长期密钥留在 OpenClaw 的配置库里;401 时由 Codex 反向请求 OpenClaw 刷新。另外订阅型配置会主动从子进程环境里移除两个 API key,避免回合意外走成按量计费。
默认按代理隔离,Codex 的配置、账号、插件缓存与线程状态都留在该代理内;改成 user 才共享原生家目录,也只有这个模式能用线程管理工具。但托管搜索与结算终结仍然用私有临时家目录。
模型可用性由 Codex app-server 拥有,OpenClaw 只是去问。订阅列表按 npm 上最新的稳定 Codex 版本列出并六小时刷新一次,发现预算默认十秒,401 与 403 会返回空目录而不是离线提示。
普通线程用基线指令整体替换 Codex 的模型提示,AGENTS.md 大多仍走原生项目文档发现,只有受限回合才由 OpenClaw 送有界快照。人格三件套走父级请求指令层,原生子代理不会自动继承。
会话目录负责把网关机器与配对节点上未归档的 Codex 会话列进侧边栏,缓存三十二秒;监督负责给代理开放读取与写入原生会话的能力,三个子开关默认全关。打开目录不等于打开监督。
原生权限钩子对无决策的返回值不当成放行;记住的允许只对精确的命令、参数、结果与工作目录指纹有效。MCP 表单最多十二个字段、每批三个、每项四个选项,超限是拒绝而不是截断。
默认的排队模式会把一段静默窗内的消息合并成一次转向请求,按到达顺序发出。终止性工具结果之前会关闭准入并等一秒消费通知,等不到就保留不可重放的不确定结果。
普通回合可以申请一次有界的补答,用已完成线程的模型选择与原始认证,在私有临时家目录里跑。补答只保留最近的整段交换,遇到未完成的工具交换宁可丢掉全部更早上下文,也不在转向消息处劈开。
原生压缩由 Codex 拥有,OpenClaw 只维护抄本镜像。有一条明确的例外:极速档会把原生自动压缩上限压到二十六万 token。镜像记录了压缩的开始与终止状态,但不提供保留删除了哪些条目的清单。
清理只针对已注册、且原父进程已不存在的子进程;判定依据是进程号、启动时间、进程组与命令行指纹,而库里只存指纹摘要。检查不通过时宁可直接拒绝启动新子进程,也不盲目多开一个。
放置的是命令、文件、能力发现与无凭证 HTTP,app-server、模型连接、提供商认证与抄本仍留在网关。每次启动都要单独授权,常驻授权只存在当前进程里,重启就回到弹窗。
支持清单里最硬的一条是 MCP 参数改写:必须是对象、不超过 256 KiB、深度 32、4096 个值、每对象 512 键、每字符串 64 KiB,且不能出现被 JS 解析改过的数字。不支持清单则包括原生抄本改写与压缩干预。
绑定线程、发送与停止回合、改模型与权限、压缩、解绑、查看账号与主机级信息都需要所有者或管理客户端。普通授权发送者只保留帮助、模型列表与自己会话的只读检查。
使用 OpenAI 模型前缀本身从不选中 Codex。运行时空着或自动时,只有精确的官方 HTTPS Responses 或订阅 Responses 路由、且没有自建的请求覆盖,才可能隐式落到 Codex。显式要求则会在插件缺失时提前失败。
通用快档命令改的是共享策略,专用快档命令改的是绑定的原生会话偏好,后者的关闭项存的是一个弹性档而不是关。共享运行控制一旦出现,会覆盖配置与绑定偏好。
同一条视频链接,给新系列能跑 2 小时,给老模型 40 秒就封顶;体积上限从 150MB 到 2GB 分三档,音频轨一律不解析。
万相3.0 的任务清单里有一类视频音频编辑,输入原视频即可调整人声、音乐与音效;它与画面编辑、参考图编辑并列,靠提示词区分。
万相3.0 的文件与网页参考各限一个且不可同时输入,示例把 Excel 单元格值直接写进分镜并逐项核对,文档仅为公开免登录页面。
官方提示词基础:短句优于长清单,主体、媒介、环境、光线、颜色、情绪、构图七项按需交代。
参数统一写在提示词末尾;--ar 改比例、--s 调风格化、--no 排排除项、--sref 做风格参考,语法细节决定是否生效。
按 Kimi 官方文档整理 K2.6 的上下文窗口、视觉与工具调用能力,以及 temperature、top_p 被固定为定值的约束;同时说明官方已把它列入下线计划,给出迁移检查项。
按 DeepSeek 官方文档梳理 deepseek-flash 与 deepseek-v4-pro 的能力差异、缓存命中与峰谷计价规则、思考模式的参数约束,以及 OpenAI 与 Anthropic 两种接入地址的用法。
缓存默认开启、无需改代码,但命中要求前缀被完整持久化成一个单元。搞懂三种持久化时机,才知道为什么有时候不命中。
JSON Output 不是打开开关就完事:prompt 里必须有 json 字样并给示例、max_tokens 要留够;解析失败时返回的可能是一串空格。
GLM in Excel 走的是 Office 加载项的手动部署路径:清单文件放进 Wef 目录,再把该目录设为受信任的加载项目录。
一个 npm 包同时解决装工具、写套餐配置、管 MCP、开插件市场四件事。适合不想手工改环境变量的用户。
标准 API 与编程套餐的 Key 分入口创建、互不通用。历史 Key 不必更换,但用哪类额度取决于调用端点,而不是它显示在哪个列表里。
套餐改版后,老用户按原规则走完当前周期。判断自己在 V1、V2 还是新版积分制,才知道续订时会发生什么。
套餐只在官方清单内的工具生效;清单内又分编码代理与通用代理两档,后者在高负载时会让路。端点配错是最常见的「用不上套餐」原因。
换模型编码不是改一行字符串。默认采样值、思考开关和工具调用的流式拼装,都要跟着改,否则会出现「能跑但结果不对」。
它只接受文本输入、上限 1000 字符,输出是图片 URL 需要自己下载;自定义尺寸时只要有一个边不是 32 的倍数,请求就不成立。
K3.1 Pro 把 temperature、top_p、n 和两个 penalty 固定成确定值,传入其他值会直接报错;思考模式也没有关闭开关,只能降推理强度。真正需要改的只有 max_completion_tokens 与缓存 TTL。
K3.1 Pro 的能力重心不在闲聊,而在端到端交付:写代码时直接驱动游戏引擎,做 3D 时自己写 Blender、FreeCAD 脚本,做金融时按文档核对数字。这三类场景对工具链的要求各不相同。
K2.7 Code 为了稳定表现,把思考模式、温度、top_p、n 与两个 penalty 全部锁定;tool_choice 只接受 auto 和 none。迁移时最容易被这些约束卡住。
kha 是与控制台、API 并列的第三个入口,让 AI 编程助手用自然语言创建智能体、跑会话、取产物。login 只存凭据,whoami 才真正验证身份。
把研究任务拆成检索、分析、输出三段,各段交给合适的工具;工具循环里必须回填完整的 assistant 消息,否则会丢掉推理内容。
K3 是上一代旗舰,2.8 万亿参数、100 万 token 上下文、原生视觉。官方把提升归因于 KDA 混合线性注意力、Attention Residuals 与更稀疏的 MoE,并称扩展效率相比 K2 提升约 2.5 倍。
已经装好 OpenClaw 的,用 onboard 加 install-daemon 重新进入配置阶段即可切换到 DeepSeek;向导里六个提问按顺序回答,模型名要手动输入,最后用 dashboard 打开界面验证。
仅 glm-5.3/5.2/5.1/5 支持,glm-5.3 默认 true 其余 false;开启后丢弃历史 reasoning_content 降成本,关闭则必须原样完整回传。
glm-5.3 恒含思维链且忽略 thinking_budget;glm-5.2 看是否传了 thinking_budget;其他模型只算回答;GLM 默认 65536、上限 131072。
备份有三条互补的路径:整包归档带走状态与凭证,SQLite 快照只抓单个库且可校验,Git 历史则提供可对比的版本序列。归档可以在网关运行时创建,但涉及 PostgreSQL 的恢复要求先停网关。
agents 子命令管的是隔离:每个智能体有自己的工作区、认证与路由。用角色模板起一个新智能体,用 bind 决定哪个渠道账号归它,比手工改配置更不容易把权限弄串。
browser 子命令管的是浏览器控制面:默认用隔离的 OpenClaw 专用 Chrome,也可以挂到你已登录的 Chrome 或任意 CDP 端点。start 失败与 open 失败指向两类完全不同的问题。
approvals 命令管理本机、网关主机与节点主机三处的执行审批。allow-always 的含义是「在这个目录、这组参数下始终允许」,换目录就要重新批准;自动化产生的批准会铸成可撤销的常设授权。
常设指令(standing orders)把重复工作从「每次提示」变成「一次授权、长期执行」。它定义做什么,自动化定义什么时候做,两者组合才有稳定的自主运行。
一个钩子只需两个文件:带 frontmatter 的 HOOK.md 与导出一个函数的 handler。事件有固定的五个字段,往 event.messages 里塞字符串不等于发消息,只有特定生产者会把它当回复投递。
doctor 有引导检查、JSON 报告、修复、lint、共享库维护、会话库工具六种姿态。关键区别是:不带 --fix 也可能写盘,真正只读的是 --lint 与裸 --json。
要让 iMessage 通道支持表情回应、编辑、撤回、特效与群管理,必须让 imsg 把 helper 注入 Messages.app。这需要关闭 SIP,并在 macOS 11 之后额外关闭库校验,否则表现为注入超时。
加密房间不只是打开一个开关:要跑 encryption setup 建立秘密存储与交叉签名,用 verify status 看三个独立信任信号,再用 verify device 与 verify self 完成设备验证,密钥备份另有独立的恢复流程。
Slack 通道的频道白名单必须以 C 开头的稳定频道 ID 为键,企业版还要写成团队前缀形式;群私聊默认关闭,且开关只能过滤 Slack 已经投递的会话,无法让机器人看到它没被拉进的群。
Discord 通道除 dmPolicy 与 guilds 两层准入外,还有一个容易踩的机制:只要给某个服务器写了 channels 表,这张表就从「例外配置」变成「准入名单」,未列出的频道一律被拒。
OpenClaw 的 pairing 有两套流程:一套批准谁能私聊机器人,一套批准哪些设备能接入网关。配对码 8 位、1 小时过期、每账号最多 3 条待批;设备配对另有 10 分钟有效的引导令牌。
accessGroups 把发件人名单定义一次、在多个渠道的 allowFrom 里用 accessGroup: 名字 引用;它只是白名单别名,不创建所有者,也不会在各渠道之间翻译 ID。
Telegram 通道有三个独立入口要守:dmPolicy 决定谁能私聊、groups 决定哪个群能用、groupAllowFrom 决定群里谁能触发;配对批准只给私聊权限,不继承到群。
OpenClaw v2.7.5飞书配置全流程:开放平台创建应用-获取App ID/Secret-事件订阅-权限配置-飞书聊天直接下达AI任务。
Windows/Mac一键部署包,解压即用。内置所有运行依赖与基础技能,零代码门槛、可视化操作、跨平台兼容。
OpenClaw 用 provider/model 指定模型。本文梳理官方 provider 清单、moonshot 的安装与配置示例、自定义 base_url 的写法,以及 fallback、utilityModel 与 modelPolicy 之间的关系。
企业把 AI 智能体接进 IM,难点不在装插件而在权限边界。梳理 OpenClaw 三个通道的安装方式、凭证归属、事件传输与访问控制配置,以及上线前的检查项。
openclaw migrate 支持从 Claude、Codex、Hermes 导入指令与 MCP 配置;换机则要停网关、做可验证备份、再搬状态目录。
飞书渠道装好之后真正决定安全边界的是三个开关:dmPolicy、groupPolicy 与 requireMention。本文按官方文档拆开讲这三项取值,以及 chat_id、open_id 的查找与卡片回执的前提条件。
Discord 通道最容易卡在两步:特权 intent 没开、首条私信没配对。按官方文档把权限和配对一次配好。
Slack 通道要先装插件、用 manifest 建应用,再在 Socket Mode 和 HTTP Request URL 之间选一条;身份还能选机器人或真人。
iMessage 通道必须有一台登录了信息的 Mac,权限按进程上下文授予;远程模式要写一个不缓冲的 SSH 包装。
automations 是网关内置的调度器:五种触发方式、时区与错峰规则、main 与 isolated 会话各自适合什么任务。
internal hooks 是跑在网关进程里的 JS/TS 处理器,用来在 /new、/reset 这类事件上做副作用;它和插件钩子、webhook 是三套东西。
回复永远回到消息来的那个频道,模型不选频道;私信默认收敛到主会话,群组与频道各自独立。搞懂会话键就搞懂了上下文为什么串。
Matrix 通道要先装插件、再绑 homeserver 账号,autoJoin 默认关闭意味着新邀请一律不自动进房;加密房间还需要单独跑一次 encryption setup 建立交叉签名与密钥备份。
Teams 通道在打包版里已内置,但 Teams 访问不到 localhost,必须开隧道;应用清单只声明资源级许可(RSC),少一条就收不到频道里不带 @ 的消息。
微信通道由腾讯微信团队维护的外部插件提供,不在 OpenClaw 核心里;装完要在跑网关的同一台机器上扫码登录,且该插件只声明支持私聊。
WhatsApp 通道走 WhatsApp Web(Baileys)协议,会话由网关持有,没有 Twilio 那条路;登录只有扫码一种方式,无头服务器要先解决二维码怎么送到手机上。
一条命令跑完配置与状态体检,重点是共享会话、hooks 令牌复用、沙箱与权限、以及 Node 运行时补丁级别;--fix 只处理安全的部分,不会替你放开闸门。
语义记忆由内置 memory-core 插件提供,索引排障看 status --deep,召回测试用 search,把短期记忆固化进 MEMORY.md 用 promote,按来源删除用 forget 先跑 dry-run。
Signal 是独立插件,网关通过 HTTP 连 signal-cli,原生守护进程走 JSON-RPC+SSE、容器走 REST+WebSocket;写内容前先想清楚用独立机器人号码,否则机器人会忽略你自己的消息。
QQ 机器人走官方 Bot API 的 WebSocket 网关,私聊与群 @ 是主力场景,频道消息只支持文本和远程图片;配置时注意 allowFrom 里的 approval-disabled 标记会关掉原生审批按钮。
Google Chat 只走 HTTP webhook,不用 Pub/Sub,需要公网 HTTPS 地址;用 Tailscale 的 serve 与 funnel 分工,只把 /googlechat 暴露出去,仪表盘留在内网。
Twitch 渠道走聊天 IRC 接口、用 Twurple 客户端,一个账号条目只加入一个频道;Token Generator 生成的令牌几小时就过期且无法自动刷新,长期挂机要自建应用。
config 子命令把 openclaw.json 的读写变成可脚本化的操作:get/set/patch/unset 走点或括号路径,patch 支持 --dry-run;网关在跑时写入会被路由给网关,中途改过配置会被拒绝。
channels 命令负责渠道账号与运行时状态;status 只读网关记录,--probe 才会真的逐账号探活;耗尽了重试的入站事件留在死信队列里,可以看原因并重投。
devices list 会并排显示请求访问与已批准访问,所以「权限升级」不会伪装成配对丢失;approve 省略 ID 只做预览,join-code 签发的是一次性入网地址而不是手机配对码。
审计账本只记身份、顺序、动作与结果码,不存正文;运行与工具记录默认开,执行身份与消息记录默认关,开了不重启即生效但不回溯历史。
HTTP 钩子让外部服务唤醒代理或提交一个回合,默认关闭;200 只代表拿到会话准入,不代表模型跑完或消息送达,要看最终结果得加 waitForCompletion。
内置 IMAP 插件只监听已有邮箱、为每封放行的来信起一个隔离会话,不发信也不改标记;发件人先过白名单再过 DMARC 档位,默认只认本地校验出的 verified。
ACP 桥在 stdio 上说协议、把提示转给网关的 WebSocket,会话仍映射到网关会话键;它不做会话级 MCP、不碰客户端文件系统与终端,结构化提问也会退回普通文本。
join-code 签发的一次性地址带 128 位熵、约十分钟过期且只能取一次;--service 装后台服务,--session-host 才是同意托管会话,两者默认不该一起无脑加。
voice.autoJoin 只管在场与对话,持久录制要显式启动;全覆盖依赖每个说话者一条音频流加批量转写,只有实时连接时只能拿到被放行说话者的最终文本。
只给 RSC 时频道图片与文件只有一个 HTML 存根,历史也读不到;要拿 SharePoint 附件或补离线期间的消息,必须在 Entra ID 加 Graph 应用权限并让管理员同意。
打开动态创建后,每个私聊用户拿到独立工作区、各自的 SOUL/MEMORY 与私有历史;dmScope 是全局开关,选 main 能自动加载 bootstrap 文件,选 per-channel-peer 隔离更强但要自己管这些文件。
LINE 走的是 webhook 接收路线,要先装独立插件、在开发者控制台拿渠道令牌与密钥、手动打开 Use webhook 并填上 HTTPS 地址;消息按会话排队投递,文本切成 5000 字符一段,Markdown 会被剥掉,群聊回复还要额外过一道群允许名单。
短信渠道靠 Twilio 号码收发,网关注册 /webhooks/sms 并默认校验 Twilio 签名;功能面上只有一对一文本与彩信附件。真正卡人的通常不是配置,而是美国 10DLC 号码的 A2P 备案——备案没过,配置全对也发不出去。
Mattermost 是能自建的团队聊天,走机器人令牌加 WebSocket 事件;配置只要令牌和站点地址两样。自建部署常在内网地址上,会被出站 SSRF 防护挡住,需要显式打开私有网络放行;斜杠命令是另一套可选项,默认不注册。
IRC 渠道接的是传统 #频道 与私聊,配置只要服务器、昵称和要加入的频道。它没有可重放的投递 ID,断线期间的消息补不回来,所以更适合当自建网络里的内部通道,而不是靠它承载关键通知。
Zalo 渠道在 OpenClaw 里仍标着实验状态,靠 Bot Creator 平台发的 numeric_id:secret 令牌工作,默认长轮询、也可切 webhook。群聊必须 @ 机器人才响应且不可配置,单条文本上限 2000 字符。
Nextcloud Talk 用 webhook 机器人对接,机器人要在 Nextcloud 服务器上用 occ 命令创建,并且必须带 response 特性,否则回复会 401。没有配 API 账号时,所有会话都会被当成房间处理,私聊与房间也就分不出来了。
群晖 Chat 靠一进一出两条 webhook 配对:出站 webhook 把私聊推进网关,网关再用入站 webhook 把回复发回 NAS。它没有配对流程,只能靠数字用户 ID 白名单放人;附件发给 NAS 的是一条十分钟有效的临时地址。
X 渠道不做私聊,只把别人对机器人账号的提及变成对话,并把答案作为公开回复发在原帖下。默认只有白名单里的作者能触发,陌生人连配对提示都没有;插件还内置日/月花费上限,防止意外刷爆额度。
Nostr 渠道只做私信,靠 NIP-04 加密消息在中继之间收发,一个网关只能挂一个账号。密钥支持 nsec 与十六进制两种写法,默认中继是 damus 与 nos.lol,身份资料以 kind:0 事件发布。
Tlon 跑在 Urbit 上,OpenClaw 连的是你自己的飞船:填飞船名、访问地址和网页登录码即可。群聊默认要 @ 才响应,授权按频道收窄;连接静默约 60 秒会自动重连,好让未确认的事件重放。
sandbox 子命令只管隔离运行时的生命周期:list 看现状、recreate 按配置重建、recover 把卡住同步的超大文件挪出去。重建要求独占离线所有权,网关在跑就直接拒绝,--force 也绕不过这一关。
secrets 子命令把「凭据从哪来」变成可审计的流程:audit 只读扫描明文残留,configure 生成计划,apply 执行并擦除明文,reload 让运行时重新解析。CI 里可以直接用退出码卡门禁。
models 子命令负责默认模型、别名、故障转移与认证画像。最常见的误用是把 status 当成「模型能不能用」的测试——它默认不发真实请求,要看得出通不通得加 --probe,而那会真的产生调用。
skills 子命令管本地技能与 ClawHub 来源:search 找、install 装、list --eligible 看哪些真能用、check 查缺什么。装完不代表能跑,缺二进制、缺环境变量、缺配置都会让它不可用,check 就是查这三样。
插件安装支持 ClawHub、npm、本地 tarball、Git、本地路径与市场简写,默认一律走 ClawHub。非官方来源会先警告再问,非交互环境必须显式 --force;想复现环境就加 --pin 把版本钉死。
三个问题就能定档:合规是否要求代码与工具执行不出边界、内网服务能否通过 Tailscale 或白名单触达、是否需要自定义系统或大仓库的本地盘。
Origin 目前是早期测试版;自动化可对着 Origin 仓库按 push、PR 事件或标签变化起云代理。在 Origin 上建的仓库开 Origin PR,从 GitHub 镜像来的仓库仍开 GitHub PR。
会话、项目、语义、情景、程序,五种记忆的生命周期和写入位置完全不同。把该进仓库的规则塞进会话,或者把一次性经验写进项目文件,都会让代理越用越糊涂。
三种投递模式不是三个通知渠道,而是三套送达语义。announce 要等通道确认才落转录,webhook 只有 2xx 才算送达,超时一律记成未知且不重试。
把新邮件变成代理的输入,链路是三段:Gmail 推给 Pub/Sub,Pub/Sub 打给 watch 服务,watch 服务转给网关的 hook。安全的关键在中间那个受限代理。
重启网关不是 kill 再起。safe 会等工作排空并合并成一次重启,上限五分钟;force 立刻断;wait 只影响重启意图;skip-deferral 必须跟 safe 一起用。
这个 Mini App 不是装个插件就有。要有可发布的 HTTPS 地址、要有一个数字用户 ID 在白名单里、要在一对一私聊里执行命令。三条缺一条,按钮就出不来。
把「让模型连续干活」拆成四个对象之后,哪些事归平台、哪些事仍归你,就变得可讨论了。这篇按生命周期把四者排开,再说清平台接手的六件事和三种不该用它的场景。
新接入时最容易被「统一成最新日期」这个直觉带偏的,就是这两个请求头。它们不是同一个版本号的两种写法,而是两层独立的兼容控制,混用会直接拿不到预期字段。
很多人期待「本次允许、下次别问」这类中间形态,托管智能体的权限策略里没有。理解这一点,才能正确设计无人值守任务,也才能读懂 requires_action 到底在等什么。
把 token 塞进环境变量是最省事也最危险的做法。托管智能体的凭据库换了个思路:密钥永不回显,沙箱里看到的只是代理值。这篇讲清五种类型各自绑什么身份键。
跨会话记忆常被做成一堆向量和黑盒检索层。托管智能体的做法朴素得多:记忆是文件,Agent 用 read 和 grep 去查,用 write 和 edit 去写,每次写入都留一条版本记录。
同一个 version: "latest",在会话、定时任务和旧协议里指的是三个不同的时刻。把这件事想清楚,才能解释「明明更新了技能,为什么线上没变」以及「删掉技能后老会话为什么还在跑」。
把 Agent 挂上 cron 之后,最容易误判的三件事都出在语义上:DeploymentRun 的成功指的是什么、暂停期间漏掉的触发去哪了、以及没人值守时 always_ask 会把任务卡在哪里。
把 Agent 的得分从 62 提到 78 并不难,难的是证明这个变化来自改动本身。托管智能体的评测与自迭代把变量收在三个地方,这篇讲怎么用,也讲哪些结论不能从分数里读出来。
沙箱里装了什么、哪些东西会话结束就没了、哪些会被编目成可下载文件——这三件事决定了你的脚本能不能复现。附上预装语言与工具的实际版本基线。
把 token 写进 Agent 定义是最省事也最难维护的做法——Agent 是可复用模板,一旦混进密钥就再也不能随便共享。托管智能体把地址与鉴权拆成两处,代价是会话创建时不预检连通性,失败得自己接。
一个 Session 里可能有二十几个线程,每条事件都带归属字段,方向还相对于你正在读的那个线程。搞清楚这几个 ID 的关系,日志才读得下去。
托管智能体的多智能体编排刻意做得很浅——不能嵌套、没有消费上限、成员之间不共享对话。理解这些限制,比学会配置更能决定架构是否成立。
两种接法常被当成同一个东西。一个把代码 clone 进沙箱让你改,一个让你远程调 API;token 的权限范围、缓存隔离的边界也完全不同。
同一个 File 对象,做输入和做产物的差别不在格式,而在路径和可下载性。搞不清这一点,就会出现「Agent 说写好了,接口却拉不到文件」。
省略 tools 不等于全开,而是全关。这条容易反着记的规则背后,是一套按工具集、configs、default_config 三层覆盖的配置模型,外加一个完全跑在平台外的自定义工具通道。
更新会话的接口看着简单,但真正能改的只有 title、metadata、agent.tools 和 agent.mcp_servers。model、system、skills、vault_ids、environment_id 一旦建好就动不了,这条边界决定了调试该怎么走。
控制台的会话详情不是一堆信息的堆叠,五个面板对应五类问题。选错面板,就会在一个正常的地方找一个不存在的 bug。
通知只告诉你「某个资源变了」,具体变成什么样得自己回查。理解这一点,后面那些设计——幂等、去重、不补发、不重放——就都顺理成章了。
group_reply_in_thread 看起来只是一个布尔值,打开它却会同时改变 Session 的划分方式、记忆的共享范围,以及失败时的表现。
Agent 在沙箱里生成了 txt 报告,钉钉渠道却发不出去。文件格式白名单、互动卡片模板、群媒体限制,是三处各自独立的约束。
带上版本号是乐观锁,冲突就 409;不带你就是在覆盖别人的改动。这个字段不是必填,但选错会静默吃掉同事的修改。
glm-5.3 不写 effort 就是 max,flash 系列不写是 high。同一段配置换个模型跑,推理强度会悄悄变一档。
interrupt 有约三秒宽限期且不产生错误事件,归档只是变只读,而 MCP 在创建会话时根本不做预检。
编码代理不是「一次生成一段代码」,而是在获取上下文、执行操作、验证结果之间反复切换。理解这个循环,才能判断一个需求该只问、该改码还是该跑测试。
理解陌生仓库、定位缺陷、重构、写测试、生成 PR 描述、补文档,每一类任务都有对应的提问方式与验证动作。
从「智能补全」到「给一个目标就干活」,差别不在模型,而在扩展层。CLAUDE.md、Skills、Subagent、MCP、Hook、Plugin 各解决一段问题,也各自占用上下文。
效果不稳定,多数时候不是模型不行,而是任务没给结构化、规则没沉淀、执行环境没配好。
描述任务、确认配置、配环境与凭据、发测试任务、留住结果。第一轮只需要验证三件事:输入读对没有、工具调通没有、产物符合要求没有。
一个是多轮对话加业务写操作,一个是沙箱里算表格再交产物。差别不在模型,而在内置工具开哪几个、敏感动作谁来把关、产物写哪里。
它本身不是云端产品,而是一个装到本地编码助手里的 Skill。作用是让助手替你选配置、调 Managed Agents API、跑一次真实任务,并留下可复用的 ID。
两个字段、两个层级。默认是「全部启用 + 直接执行」,意味着写文件、跑命令这类动作不会停下来问你。想把风险动作改成询问,得自己配。
技能创建即不可变,改内容只能归档旧的、新建一个。智能体引用时可以固定版本,也可以留 latest 在唤醒时重解析;会话创建那一刻,所有版本都冻住。
插件把 MCP 服务连接与技能打包成一个分发单元。包里必须有 kimi.plugin.json,interface 下的每个字段都有格式要求,校验不通过时 HTTP 仍是 200,要看 report.ok。
凭据库按类型和匹配字段为会话提供第三方凭据:MCP 用 URL 匹配,环境变量用变量名匹配。凭据值只接受写入,任何查询接口都不会返回密钥;环境变量凭据在沙箱里只是占位符。
自托管只把沙箱工具挪到自己的 Worker 主机,模型调用、智能体编排、会话管理仍在云端。文件读写与 shell 不收平台费用,但 ipython、图片搜索、产物保存暂不支持,技能与记忆也不会挂载过去。
多智能体编排在同一个会话里开子线程,协调智能体通过 spawn_subagent 委派。同步会等结果,异步先返回一句带子线程 ID 的说明;子线程不能再往下开线程,会话级覆盖配置也不会传给它们。
定时运行用 cron 五字段表达,最小粒度一分钟。运行记录的 completed 只说明会话已创建、初始事件被接受;要确认结果得拿 session_id 去查会话。复用会话模式下撞车会记成 skipped。
会话是智能体的一次运行实例。创建时固定智能体版本、执行环境版本和资源绑定,environment_id 之后不能改;集合字段有三种状态,空数组表示清空而不是继承。
智能体是持久化、版本化的配置对象,每次更新都生成不可变新版本,旧版本完整保留;已创建的会话继续跑创建时冻结的那一版。字段上限与 version 的并发校验也一并说明。
官方 PPT 助手把设计收敛成四条约定:技能分方法类与产物类、说明按需读取、产出统一写到 output/ 目录、回复只讲产出和位置。四条都围绕「可编辑、可程序化取回」展开。
巡检与报告、告警、问答三个智能体各自定时运行:巡检每小时读新消息并登记待办,告警每半小时筛风险反馈,问答回应运营提问。采集进度只在两张表都写成功后更新。
模型请求遇限流会自动重试,间隔从半秒逐步拉长到固定五秒,最多二十次;所有线程结束后会话进入空闲并停止累计沙箱时长。取消、归档、删除是三件不同的事。
自建一套 Agent 运行框架通常要几个月:会话历史、工具执行、沙箱、失败恢复、超时重试。托管智能体把这五件事收走,留下的是任务定义和业务工具。
自托管智能体平台通过官方 Moonshot Provider 接入 Kimi,手写模型条目时有三项兼容配置决定了工具调用与流式用量能否正常工作。
Hermes 用自建提供方的方式接入中国区 Kimi,密钥存进本机环境变量;模型名不带前缀,视觉能力要在条目里显式开启。
托管智能体的 REST 接口需要带版本头,控制台则不需要密钥。无论走哪条路,执行顺序都是选智能体、建环境、建会话、发消息、取产物。
百炼的智能体应用版本号从 V1.0 开始递增,每个应用最多保存 10 个版本,发布是通过 API 或 SDK 调用应用的前提条件。
知识库里找不到答案时,模型倾向于编。百炼的做法是开启干预智能体回复功能,为知识库无结果的情况单独设置一段干预回复。
百炼的智能体应用支持在系统提示词里嵌入变量,点提示词右上角的新建变量设置,然后在提示词里输入斜杠即可引用已配置的变量。
Qwen-Image 走 DashScope 原生接口,不支持 OpenAI 兼容模式,无法直接充当 OpenAI Agents SDK 的推理模型;官方路径是封装成 function tool,由 qwen-plus 调度。
name 最长 256 字符、description 最长 2048、metadata 最多 16 对且键值各有上限,model 可以写字符串也可以写配置对象。此外这一族端点必须带管理智能体的 beta 头。
mcp_servers 最多 20 个且名字要在数组内唯一,但更严格的是另一条:每个服务器都必须被 tools 里的 mcp_toolset 引用,未被引用的会被直接拒绝。
effort 在创建与更新时的省略语义相反,而 inference_geo 会因为 model 采用整对象替换而丢失。想只改一个字段,必须把整个对象重新写全。
Memory Core 把记忆拆成指令、策展核心、情节、预期、复核五层,写入者和注入时机各不相同。持久记忆只有一个主写入者——dreaming 合并,其它路径都是给它供料。从情节层到策展层要过两道闸:先规则打分,再模型合并。
内置引擎把 MEMORY.md、已存在的 USER.md 和 memory/*.md 切成 400 token、重叠 80 的块,存进每个代理自己的 SQLite。换嵌入提供方或分块实现都会改变索引身份,搜索会被暂停或触发一次重建。
溯源分三张表:块级来源用于信任门控,条目来源用于找回派生条目,文件级写入记录只供人工复核。选择器选中的是会话而不是事实,命中的条目整条删除,混合来源的条目也会一起走。
向量与关键词两路并行,合并时关键词分会被缩放:最强的那条关键词命中最多只能拿到最佳语义分。加上新近度衰减与重要性、再过一道 MMR,才是最终顺序。
内置压缩把旧历史压成一条摘要,摘要请求的输入被限制在 16 万字符左右。这个预算按「最新消息一半、更早的用户消息四分之一、最旧消息十分之一」分配,中间的空白会被明确标注条数而不是让模型猜。
上下文引擎在摄取、组装、压缩、回合结束四个点介入。插件声明自己拥有压缩后,走 OpenAI Responses 直连的会话默认关掉原生压缩与检查点回放;不声明就维持原样。
OpenClaw 没有运行时的默认提示词,全部由自己渲染。组装分三层:纯渲染器、配置门面、运行时适配器。稳定内容放在提示缓存边界之上,工具目录与逐轮指引放在下面,这样刷新目录不会让缓存前缀变动。
一次 agent RPC 先落会话元数据并立刻返回 runId,真正的回合在后台跑。流式开始之前会登记一个持久的 writer claim,之后每次抄本追加都要核对它,被取代的运行因此写不进旧数据。
所有渠道的入站自动回复都要经过一条进程内队列。未配置的通道默认 mode 为 steer、防抖 500ms、上限 20 条、溢出时摘要化。优先级不是无限的:前台最多超车老任务 15 秒,之后就得排队。
steer 模式不打断正在跑的工具,也不会跳过并行批次。顺序模式下第一条工具调用照常启动,之后每个调用前才检查转向;被跳过的调用会拿到一条「为处理新消息而跳过」的合成结果,而不是凭空消失。
重试是按单个 HTTP 请求做,不是整条流程重来。模型侧限流允许最多 16 次尝试,共享组织 TPM 耗尽只给两次同模型重试就得换模型,其它瞬时故障是 90 秒窗口内 8 次。
第一段在当前提供方内部轮换认证配置,第二段才前进到 fallbacks 里的下一个模型。但如果错误明确点名「模型不存在」,OpenClaw 会跳过换凭据直接换模型;反过来,本地写入冲突与会话状态变更则完全不触发回退。
OpenClaw 没有真正的 token 级流式到渠道消息。块流式发的是完整块,预览流式靠编辑临时消息实现。提供方的快速增量在 75 毫秒节拍上被合并,最终回复与抄本仍然保留完整文本。
配额与用量直接取自各提供方的用量接口,不做估算。测不到账户对应关系时,界面显示「配额账户未知」而不是借用别人的套餐名;订阅凭据下连 token 费用估算都会隐藏。
修剪针对累积的工具输出,不动正常对话文本。Anthropic 直连走服务端清理,其余路由走客户端:等缓存 TTL 过期、用量低于三成跳过,超长结果先软修剪再硬清。最近三轮助手消息永远不修剪。
多个会话同时干活时,谁改了什么都得让对方知道一次。OpenClaw 用一张类型化信号日志加游标,只发一条去重后的失效通知,再由接收方用 changesSince 拉精确差量。通知本身不带消息内容。
审批通过之后,真正被绑定的是执行上下文:工作目录、精确参数、环境绑定与可执行文件路径,可写的可执行文件还带内容哈希。批准与执行之间文件被改掉,这次运行就直接拒绝。
工具很多但一轮只用几个时,OpenClaw 把工具模式推迟,换成一份受限目录加搜索、描述、调度三个控制。空间紧张时先缩短描述,绝不删掉授权目录里的条目。
goal 是挂在当前会话上的持久目标,跨多个回合继续推进。它有六种状态,其中 paused 会因为运行报错或超时而自动进入;换目标时替换语义按状态分三种,只有模型侧的创建工具能设 token 预算。
没有图 DSL,也没有独立的工作流格式,程序本身就是编排。Swarm 给代码模式的脚本加上可等待的收集子代理、结构化结果、有界并发与进度上报,默认开启,每个组有自己的执行通道。
CLI 后端是把本地已装好的 AI CLI 当作推理执行体,ACP 管的是会话控制面。两者的适用场景在官方文档里分得很清楚,混用会丢功能。
OpenClaw 的运行时钉选作用在模型条目上,所以主模型与降级模型不能是同一个模型。这条约束会直接改变你写降级链的方式。
会话标题、摘要、进度旁白这些短任务走辅助模型,而它们要求一次完全不带工具的补全。CLI 后端能否满足这个合同,会在校验时被告警。
同一把 exec 工具,三种存活性。分不清这三层,就会出现"命令还在跑但会话已经被重置"或者"以为活过了重启其实没有"的误判。
单会话 16 个、整机 64 个后台服务上限。到顶时新的启动直接失败,旧进程不会被杀来让路,前台留下的进程也不占额度。
你在命令里写 amp、nohup、setsid,或者跑一个自己 fork 走的守护进程,OpenClaw 都会把它登记成一个可管理的后台会话——macOS 有例外。
同一会话里多条后台命令几乎同时结束时,OpenClaw 不会一轮一条地叫醒模型,而是把等待中的结果并进一个回合,超出部分留给下一个回合。
Gateway 重启时仍在运行的普通后台命令,会在下次启动时给会话发一条通知。通知的措辞取决于平台,也决定了你要不要先查副作用再重跑。
一个会话身上挂着三层身份信息,权限锚在最不可变的那一层。把"负责人"当成"创建者",是多人共用一个 agent 时最常见的误判。
归属、可见性、在线状态都是可用性功能。真要互相隔离,得拆成独立 agent 或独立 Gateway,而不是调头像和过滤器。
共享、只读、建议、草稿这四档只对已登录的人生效。真正让人不登录就能读的,是创建者单独打开的公开访问,而且它排除的东西比你想的多。
共享一个 Gateway 时,每个人可以绑自己的模型账号。四个概念必须分开看,否则会出现"我改了默认,为什么这个会话还是花在别人账上"。
身份、顺序、动作、状态、结果码会留下;提示词、消息正文、工具参数、命令输出一律不存。这个取舍决定了审计在事故复盘里的位置。
一个 runId 下面可能挂着多次执行。查错时用错号,会得到"没有记录"或者"有歧义",而不是错误提示。
全新安装和升级都不会自动开启,也没有环境变量能偷偷打开。开了不回溯,关了立刻停,已留下的证据按 30 天过期。
把 safeBins 当"可信命令白名单"用,是最常见的配置错误。它只允许只读标准输入的工具,连 grep 都要额外条件。
这套设计刻意避免"文件存在性预言机",代价是通配符和 $HOME 这类写法在快车道里等于字面文本,用法要相应调整。
安全严格度与未命中是否提示,两个轴的组合产生了五档。搞清映射关系,就不用背模式名,也不会误以为 full 能绕过严格内联求值。
会话还是那个会话,编码工作可以跑在别处。凭据永不下发远端,但"把工作派到租来的机器"要管理员权限,派到自己的设备只要写权限。
一人一行而不是一标签一行,在线含闲置页面,名字或 IP 相同从不构成设备与人的关联。三条语义决定了这套状态能用来做什么。
operator.write 自带 operator.read,operator.admin 覆盖所有 operator.*;但 session 级 scope 不向上包含,拿到它仍然看不到日志、配置与别家活动记录。
从 none 到 write 五档,决定别人能看到你的哪些会话;成员身份能抬高访问,但撤回之后重放旧消息也换不回来。
声明头先被设备授权收一次,再与服务端身份授予求并集,最后被会话上限与角色上限各裁一次;每一层都只能减少,不能凭空增加。
设备审批只能铸造调用者已有的 scope;节点审批按待批请求声明的命令清单派生,出现 system.run 就一路升到管理权限。
sandbox: required 覆盖 agent 的 off 模式,按创建人而不是按 agent 或会话隔离;创建来源戳不可修改,后端不可用就是错误,不回退到主机。
none 让工具用自己的隔离目录,ro 把 agent 工作区只读挂到 /agent,rw 挂到 /workspace;技能还会被镜像成只读指令根。
主机后来新增的路径要 git add 之后才被准入;改忽略规则不让主机文件进来;构建缓存与 scratch 目录不同步,单文件上限 64 MiB。
三个设置互相独立:mode 管哪些会话沙箱化,scope 管容器数量,backend 管谁来跑。主会话的 key 是固定的,群会话在 non-main 下永远算非主。
host:container:mode 三段式,ro 与 rw 只作用于那一条挂载;系统路径、Docker socket 与家目录凭据子路径默认拒绝,symlink 父目录还会被二次解析。
sandbox 决定运行位置,tool policy 决定工具存在与否,elevated 只是 exec 的逃生口。deny 永远优先,allow 非空则其余全禁。
一个端口复用 WebSocket 与 HTTP,默认 18789;容器发布端口走 Docker 自己的转发链,规则写进主机 INPUT 是拦不住的。
带转发头但来源不在 trustedProxies 里,网关不会当成本地连接;HTTP 得到 proxy_attribution_required,WebSocket 直接鉴权失败。
能调 /v1/chat/completions 的共享密钥,等于该网关的完整 operator 权限;按请求收窄 scope 只在带身份的模式下才算数。
握手并发、鉴权失败、浏览器来源、webhook、控制面写、ACP 建会话与重启冷却各有一套限额;loopback 豁免在浏览器来源那条路上被关掉。
根限定的读写、原子替换、解包与密钥文件都走 @openclaw/fs-safe,它是库级护栏而不是沙箱;off、auto、require 决定缺能力时是回退还是失败。
提供方凭据、任何 OPENCLAW_ 前缀的键、以及端点路由与可执行搜索根,都不能从工作区 .env 里生效;凭据要放在网关进程环境或全局 dotenv。
同一个 {source, provider, id} 形状,env 要大写下划线、file 要 JSON 指针、exec 允许井号选择器、store 只解析团队作用域;file 提供者还拒绝硬链接。
pnpm-lock.yaml 是唯一入库的评审边界,npm 格式锁不进 tarball;漏洞通报只记警告,被标记为遭入侵的包才会阻止发布。
注入不需要公开私聊,只要机器人读到不可信内容就成立。模型抗性有量化差距,但仍有超过八成的自适应攻击成功率,硬约束必须另配。
sessionKey 是路由键不是授权令牌;默认跨 agent 的会话可见与 agent 间消息是设计而非缺陷;互不信任的人必须拆网关。
bot loop protection 限的是两个机器人身份之间的来回速度,不是机器人能不能说话;五个层级的覆盖顺序、Telegram 一个群主题共享一份预算、以及重启就丢的内存账本。
广播组把一条入站消息分给多个 agent,每个 agent 各持独立会话;预算按「轮」与「回合」双闸计,摘要按 4000 与 16000 字截断,账本存在内存里。
把未提及的群聊当成安静上下文处理,最终回复默认不外发;两个前置条件会让它静默失效,一个是提及门槛,一个是工具画像。
外部 agent 通过 A2A 1.0 提交任务时,取消请求会被明确拒绝;任务续跑、同号重投、斜杠命令各有自己的错误码与边界。
提及模式的四种触发信号、群白名单与三种 groupPolicy、按群隔离的会话键,以及只注入未触发过的那 50 条消息。
论坛频道发帖的两种方式、线程与父频道的会话继承关系、20 条的自动读历史上限,以及把线程绑到某个子 agent 会话上的四个命令。
基础清单对 Socket Mode 与 HTTP 两种模式只有 settings 与命令 url 不同;权限按读历史、写消息、文件、表情四组展开,命令数受平台 25 条限制。
配对只是让设备进来,不等于给了命令;平台默认白名单是一张天花板表,危险命令还要一次性显式开门,拒绝永远优先。
语音会话在加载画像、启动提供方之前就要解析出归属;转向不是靠运行 id 授权,而是靠调用方当前的工具策略与权限。
路径必须是归一化的 HTTP 请求路径,完整 URL、相对路径、点段与未编码空格一律拒绝;共享网关端口的账号还共享同一套未鉴权限额。
文件传输不是一条通道而是一组边界:单文件大小、模型可见文本预算、目录抓取的后代上限,以及必须逐条给出的路径授权。
会话目录能列出别的机器上的 Codex、Claude、OpenCode 会话,导入是显式同步:只追加没见过的条目,超限时从最近往久处保留并标记不完整。
回复只是最显眼的一项;媒体理解、图片视频生成、记忆嵌入、联网搜索、压缩摘要、语音与技能都在各自的路径上取凭据,成本口径也各不相同。
同一张事件表里混着被等待的钩子与只做观察的钩子;订阅父族与具体键会重复触发,而关停等待有时间上限却不终止处理器。
文件到数据库的迁移由修复命令负责;重跑是幂等的,冲突会保留原文件并标记校验失败,而改写凭据之前一定会先留一份可验证的备份。
同一个缓存保留档位在不同提供方落成不同的 TTL 与写入费率;写长窗口比写短窗口贵,而 TTL 从请求开始计时,生成本身也在消耗它。
授权状态与权限桶是两套东西:截图能用不代表点击能用;把辅助功能授予通用 node 二进制,等于把界面自动化权限发给所有经过它的脚本。
设置一个前向代理地址就能接管运行时的 HTTP 与 WebSocket 出网;它替换掉调用方自带的连接器,让显式指定的客户端也无法悄悄绕过。
只要有一个凭据且没显式定义提供方,本地服务上的模型就会被自动列出来;能力来自服务端探测,拉一个新模型不用改配置也不用重启。
每个任务可以带一份私有草稿当上下文,用修订号做比较交换;结果有五种枚举,其中「无变化」不写摘要也不发通知。
同一个 computer.act 命令可以由三种履行者实现,但选谁是在会话层定的;一旦某条供给线失败,结果是「不可用」,而不是悄悄换另一条路再试一次。
电脑控制的每个坐标动作都要回显一个帧标识;帧、显示器身份、执行标识三者任一变化都会让动作被拒,而不是被重定向到看起来一样的位置。
能点鼠标不等于被允许点:工具策略、命令清单、配对审批、节点本地开关、系统授权五处必须同时为真,而一条 deny 可以整体撤销,且全程没有租约。
SQLite 反复改写同一批页,落在写时复制的 btrfs 上会碎成一地;修法是给目录设 NOCOW,而这件事必须停下来做、逐字节复制、用原子交换收尾。
打开数据库时做的格式、schema、索引与完整性校验,按「每个物理库每进程一次」计;封印还能跨重启复用,但它永远盖不过一条已记录的腐败拒绝。
2026.7.2 起数据库在首次启动时被单向迁移;降级二进制不会降级数据,而错误里点名的是安装根,不是版本号——一个版本串能横跨多个 commit 与 schema 级别。
为了让还在跑的旧更新器把话说完,2026.9.2 这条线把「迁移内容已应用」与「版本号已公布」拆成两件事,中间隔着五分钟到三十分钟的宽限。
迁移默认做整文件备份,但所有者可以按「库种类 + 目标版本」声明自己只改哪些表,于是得到一个小得多的 scoped 归档;它只能按表还原,永远不能直接替换源文件。
客户端凭据从共享库搬进本地库时,先复制再验证记 copied,最后才退役共享记录记 complete;中间这段路一旦回滚,窗口里发出的凭据会丢,客户端只能重新配对。
会话行与创建回执在同一个事务里提交;回执记得原始幂等摘要、请求指纹与当时的角色作用域,但存储的身份永远不构成重放授权——现在是谁,由现在判定。
老库删掉的行不会把空间还给文件系统,因为 auto_vacuum 是 NONE;普通 VACUUM 只缩一次不改模式,而 doctor 的 compact 会把模式改掉,让后续删除也能回收。
节点默认给每个可用 CPU 核心一个工作器槽,超额的启动最多等十秒等一个持久槽;没有空槽时节点仍能应答状态与取消,但不会被选去跑新回合。
回合结束后工作器可以被留两分钟,好让紧接着的追问省掉一次运行时加载;代价是每个保留的工作器及其监管进程要吃掉几百 MiB。
入站图片、音频、视频会先被摘要成短文本再进回复管线;每次处理都是一次「选附件、选模型、失败换下一个」的过程,而理解失败并不会挡住这条回复。
没配模型时,OpenClaw 按「当前回复模型、已配置提供方鉴权、本地 CLI」三段顺序探测;配好的 API key 永远排在 PATH 上的二进制之前。
Gateway 保留了六个健康检查路径与一个内部命名空间,Telegram 回调不能落在那里;换路径时旧监听器要一直开着,直到平台接受新的 setWebhook。
平台收到的确认由持久队列准入决定,不由插件钩子或回合完成决定;「offset 已排队」只说明写入被调度,不是已提交,所以崩溃后可能重投。
每个说话人一条独立的提供方连接以保留身份,但一个房间最多八条;加入、重连、静音定稿各有自己的超时默认值,别把它们混成一个。
Teams 能把 exec 与插件审批投成自适应卡片,但卡片只列出这次请求允许的决定;审批人必须是稳定的 AAD 对象 ID,显示名、邮箱、组条目都不授予审批权。
MCP 注册表命令管的是保存下来的服务器定义,多数子命令根本不连接目标;而 Gateway 对带连接的托管运行时有一个 256 的准入上限,额度按会话与请求方分区计。
策略读的是已存在的配置,但字段缺失时并不都算「中性」。沙箱模式的缺省被当成 off,执行审批的缺省安全模式被当成 full,两边恰好反着。
同样是「装不下」,有的报错可以压缩后重试,有的连摘要请求本身都会被同一个上限拒掉。区分点在于被点名的是每请求上限还是窗口。
执行审批的策略检查只读姿态与白名单模式,明确排除命令文本、解析路径与时间戳。审计要回答「跑过什么」,得换另一份证据。
一个是按 transcript 字节数在回合开始前动手,一个是按估算压力在新工具结果追加之后动手;后者发现问题时只发信号,由外层决定截断还是压缩。
注册一个压缩提供方会让模式被迫切到 safeguard,但提供方出错或返回空时,内置摘要会接手;降级摘要会留下一个持久字段。
内存落盘发生在压缩之前,它自己有一套阈值:软边距与预留都按窗口比例封顶,另有独立的字节闸。同一台机器上这几个数字会互相牵制。
静默回合靠一个约定 token 实现,判定是「整个最终回复去空白后等于大写 NO_REPLY」。大小写、标点、引号、JSON 与尾随内容都会让它失效。
同一个 SQLite 文件里放着两种东西:可变的会话行与只追加的树状事件。压缩摘要和 token 测量都留在 transcript 里,没有单独的检查点副本。
带限定的身份可以往裸行追加而不改名,但两种写法同时存在就构成歧义:写操作报错,读操作仍把两个地址分开。
文档里的测试用例把矛盾摊开了:严格的字节预算不可能同时保留任意完整行。要报告「删了零条」,必须先证明选中的尾巴里确实没有匹配项。
历史读取把目标、分支、版本与下一位置一起写进续游标,并且永远不跟到最新的活跃分支上;缺上下文或权限失效,也不会返回一个空的成功结果。
唤醒词由网关拥有,任何客户端都能改,但没有按节点区分的自定义列表。写入时会去空白、丢空项、截断过长的词,清空则回到内置的三个默认值。
唤醒词清单只做去空白,而路由匹配还会统一小写、剥掉每个词首尾的标点并压缩空白。于是两条看起来不同的路由会互相当成重复项。
支持 UVC 的 USB 相机只有在出流时才服务云台控制,所以连读取位置都会短暂开流。水平与变焦是两次独立写入,无法原子完成。
同一条拍照命令在不同平台上有着不同的默认值与钳制区间,录像还要过一道原始体积上限。超限的报错各不相同,处置方式也不同。
节点命令的可用性由「设备权限」与「网关命令白名单」共同决定,两者独立。给了系统权限不会改写网关策略,反之亦然。
scopes 里的条目是叠加而不是覆盖:全局规则照常运行,作用域可以基于同一份证据再加一条发现。重复声明同一字段时,只允许同样严或更严。
容器姿态检查只针对后端能看到的证据。给一个无法暴露该证据的后端启用规则,结果不是通过,而是报不可观测,并要求把规则收敛到合适的 agent 组。
策略证明里 checkedAt 只进日志不进稳定哈希,于是策略、证据与发现集都不变时,attestationHash 逐字相同,可以直接当作准入凭据。
policy watch 反复检查并在证据与已接受哈希不符时报出来。它默认每两秒轮询,区间有上限,被信号打断时的退出码与正常结束不同。
openclaw database preflight 拿一份拷贝出来的状态库与目标版本自己的 schema 契约比对,只给一个状态。exact 之外都不是放行信号,而带 -wal 兄弟文件的拷贝会让结果变成 indeterminate。
OpenClaw 的轨迹写入器在事务之前准备 Brotli quality 3 负载,但只有同时越过体积、节省比例与上限三道闸的值才真的被压缩,超过 256 KiB 的反而保持文本。
轨迹保留读不再先做物化聚合,而是直接从 (session_id, run_id, created_at, octet_length(event_json)) 这条覆盖索引上汇总。代价是索引大了约 1.06 MiB,收益是同一批分组从四百多毫秒降到三四十毫秒。
OpenClaw 规定运行时 SQL 一律在 worker 里跑,网关主线程只 await 结果并安装已发布事实。例外只有四类,而已经存在的主线程访问算遗留——不得新增,改到哪迁到哪。
写者回执让相关缓存失效,但没被覆盖的读仍走直读。覆盖不完整时唯一正确的动作是向读 worker 要新快照,而不是改成写者扫描,也不是加一个外部提交探测。
OpenClaw 的写事务回调是同步的。个人账户变更、审批操作这类路径在 BEGIN IMMEDIATE 之前先拿初始授权,进事务后重读权威行,把异步准备全部提到事务外面。
缓存的数据与权限是两份契约。凭据、审批、命令执行与跨用户披露必须在效果边界上持有当前权威,而这份权威由一个四态发布模型表达:pending、committed、unknown、settled。
agent schema 从 1 走到 41,中间缺了 3,而 2、4、5–6、7 都只是开发期中间态。已装版本的 openclaw update --dry-run 不会揭示目标版本的迁移计划,回滚也不是重装旧包就能完成。
update_runs 每次更新存一行,每个 JSON 列硬上限 16 KiB,驱动身份最多记 8 个,而抓不到进程身份时留下的那个标记会永久把这条运行排除在自动对账之外。
网关在就绪后采样 Linux 文件缓存驻留,每 15 分钟复检一次。冷样本会触发一轮后台预热,它有字节速率、单轮总量与单库时长三重限制,而且计时结果不代表一次 chat.history 请求的全貌。
iOS 与 macOS 的输入框草稿存在同一个 client-state.sqlite 里。单条草稿的附件上限 40 MB,同一网关的所有草稿共享 50 MB,而超预算时的回收顺序是「先删别人的附件,不删任何文字」。
新命令与它们的回复重放有一个不可变的 48 小时截止,而旧版导入留下的只有哈希的回执没有定时过期。同一张表里,两种记录的生命周期完全不同。
sessionKey 是会话桶,sessionId 是当前那份转录的身份。/new 与 /reset 在已存在的会话里记录一条重置边界并保留原 sessionId,而默认情况下根本不会自动重置。
sessionStartedAt 管每日重置,lastInteractionAt 管空闲重置,updatedAt 只是行变更时间,lastActivityAt 标记未读活动。心跳能改 updatedAt,却不能让会话续命。
自动父分叉、操作者分叉、消息分叉走三条不同的路径。同样撞上容量上限,自动父分叉会改用隔离上下文继续,操作者分叉则被拒——差别在于谁在发起。
snoozedUntil 与 markedUnreadAt 都只以时间戳存在,服务端不提供 snoozed 布尔,也不跑定时器。客户端要自己拿唤醒时间去对表——这套设计把「什么时候算醒」交给了时钟。
自定义的 Bedrock provider ID 会用同一个插件,但区域不再继承默认 provider 的设置。它按「provider 的运行时 URL、解析后的模型 URL、插件发现区域」依次回退,最后才用 AWS SDK 自己的环境与 profile。
Vertex AI 走的是应用默认凭据。要让 OpenClaw 发现用户 ADC,得跑 gcloud auth application-default login,而且要以网关的系统用户身份跑;单独一次 gcloud auth login 不产生这个文件。
把 talk.realtime.mode 设为 stt-tts 之后,浏览器 Talk 不再用实时语音到语音的提供方,而是每句话都过一遍当前聊天会话。两分钟的答复超时会停掉采样与播放,但不会取消已经接受的运行。
Discord 的跟随模式让机器人在语音频道之间跟着指定用户走。它只控制语音驻留,不授予发言权限也不给 owner 权威;这两件事要分别用 commands.ownerAllowFrom 与公会、频道成员配置。
入口跑出插件根目录、路径 world-writable、归属与当前 uid 不符,这三条会在运行时之前就挡下候选。内置插件多一次就地 chmod 修复,第三方没有;被拒的候选仍会带着 id 出现在诊断里。
一个 PluginCache 服务一代插件事实,运行时读取不会触发目录扫描或清单重读。缺失的文件在新代际之前一直是缺失;失败的原生 ESM 求值由 Node 留到进程结束,换账号重启也修不回那张模块图。
清单里的 activation 与 setup 只是控制面描述,不替代 register()。CLI、渠道、provider、agent 运行时各按自己的 id 收窄候选;请求 all 作用域时若推导出的集合为空,OpenClaw 保持为空而不是放宽成全部插件。
provider 插件分清单元数据、配置期钩子、运行时钩子三层。envVars、providerAuthAliases、providerAuthChoices 各有各的用途,选错就会为了一个登录标签把整个 provider 运行时拉起来。
模型 id 归一化只走匹配到的那个 provider,空结果就保持原样,不会回头重试别家或再套一遍清单规则。传输归一化多一条豁免:只有没改动 api/baseUrl 且没有 models.providers 条目时才试别的钩子。
catalog.order 决定 provider 目录相对内置隐式 provider 的合并次序,四档分别是 simple、profile、paired、late,同名键后者胜。discovery 这个旧别名已在 2026.4.26 连同弃用警告一起移除,仍注册它的插件不会发出任何目录行。
resolveUsageAuth 的返回值决定 OpenClaw 是去调 fetchUsageSnapshot,还是回落到通用凭据解析。给 token、给 handled:true、给 null 三种回答对应三条不同分支,混用会让 /usage 要么查不到、要么查错凭据。
block:true 是终结性的,会跳过后续低优先级处理器;block:false 视为没有决定。每个处理器看到的是原始事件的独立副本,最后一个 params 生效到有人要求审批为止,而首次 requireApproval 会冻结参数快照。
ctx.requester.deviceId 来自网关对该连接签名的校验,不是请求参数也不是客户端名字。一旦有另一台设备或无设备来源把输入转向这次运行,该字段就会被丢弃;缺失字段代表未证实,不等于否定。
resolve_exec_env 只在 OpenClaw 自己的 exec 工具上生效,不是给所有 harness 原生 shell 用的。返回的键会先过一遍宿主策略:PATH 一律丢弃,LD_*、DYLD_*、NODE_OPTIONS、代理与 TLS 覆盖变量也全部丢弃。
插件的依赖只在安装与更新阶段处理,运行时不跑包管理器、不修依赖树、不改 OpenClaw 包目录。npm 与 git 的安装根是持久状态,删掉就等于删掉所有外部插件,部署清理脚本必须留着它们。
网关进程带 --preserve-symlinks 时,外部插件可能每次启动都在注册阶段失败,报缺一个嵌套依赖里的包。包本身是全的,重装和更新都没用;要查的是服务命令与 NODE_OPTIONS。
关闭运行时依赖内联之后,每一个打过工作区补丁的直接依赖都必须在 bundleDependencies 或 bundledDependencies 里显式列出。漏一个,打包直接停止;写成 true 也不算选择性声明。
可选工具控制模型能不能看见工具,插件授权请求控制某一次调用要不要问人,执行审批管宿主命令,Codex 原生权限与 MCP 征求各自有归属。选错闸的结果是每次都问、或者根本没人问。
title 上限 80 字符、description 上限 512 字符,超时默认 120 秒且最高 600 秒,与请求里写多少无关。severity 省略按 warning,allowedDecisions 省略按三种全给。
requireApproval.scope 是带类型、可选、纯展示的字段,永不授权也不改变决定。渠道不会从命令或标题里推断它;一旦清洗后越界,OpenClaw 会把 scope 整段省略,只保留原本的审批提示。
configContracts 里的 dangerousFlags 用 path 加 equals 精确标记某个配置字面量,path 相对 plugins.entries.<id>.config 且支持 * 通配。同组的两个 compatibility 路径字段决定通用配置读取要不要跳过该插件的 setup 面。
secretInputs 的每条路径可以声明 ownerKind。capability owner 在 provider 不可用时冷失败,避免旧凭据继续生效;route owner 在全量插件配置与 provider 定义未变时可以保留上次可用值。
清单是控制面的真相来源,负责身份、声明、配置校验、界面标签与安装元数据;原生插件的运行时模块才是数据面。activation 与 setup 只是元数据描述符,不替代 register(...) 或 setupEntry。
Slack 侧审批人名单按工具、插件、默认三级覆盖,只有精确匹配的那一级生效。名单在路由请求时查一次、接受决定时再查一次;改名单不会撤回旧卡片,被移出的人仍能看到但批不了。
删掉一个已经发出去的 SDK 子路径,需要一条覆盖它的兼容记录,且 removeAfter 必须严格早于当前 UTC 日期;只有 removalGate 并不构成授权。deprecated 与 removal-pending 两种状态在到日子之后的后果完全不同。
只有同时具备 types 与 default 导出目标的子路径才算 typed-public 契约,private-local 条目即便能被 import 也不是第三方可依赖的面。command-auth 退休后,它的五类职责分散到了五个不同子路径。
草稿预览的收口函数从一个变成两个,结果形态也从字符串变成带 kind 与 liveState 的对象,preview-retained 不再被折叠成 normal-skipped。同一批迁移里还有同名搬家、改名搬家与只换归属三种不同性质的变化。
异步版的抄本归属查找覆盖了会话重置后仍保留的历史窗口,数据库缺失时返回 undefined 且不建库。极易被当成替代品使用的 getSessionEntryByIdAsync 读的是当前条目,对历史窗口无效。
PreparedTtsPreferences 属于回合范围的准备结果,下一轮要重新准备;它保存机器路径而偏好文件内容仍在调用时读取。宿主缺少异步能力时应报升级,而不是退回同步读数据库。
api.registrationMode 报告插件是以哪种方式被加载,六种模式允许注册的东西各不相同。cli-metadata 与 setup-only 两种模式下访问运行时能力会抛错并点名插件与模式。
待定的插件状态迁移会同时扣住普通入口与 cli-metadata 入口,此时连 CLI 元数据都采不到。显式恢复要走单独声明的 Doctor 恢复 CLI 子树,注册只装 handler,真正执行需要命令动作与插件方同意。
extensions 与 setupEntry 是源码入口,runtimeExtensions 与 runtimeSetupEntry 指向构建产物,两组按位置一一对应。声明了产物却缺失时安装直接失败,不会静默回退到源码。
createToolPolicyMatcher 的 deny 项优先,空 allow 列表等于不受限,write 放行 apply_patch 的兼容可以关掉。授权判断不应跨 await 保留,匹配器是为单次同步操作准备的。
resolveExecModePolicy 在投影到后端权限标志之前解析 exec 策略。显式 mode 带来配套的 security 与审批设置;反过来显式 security 或 ask 会替换对应字段并清掉继承的 mode。
fsBridge 的 pathMappings 由后端准备好的挂载决定,容器根同时声明路径语法:POSIX 根保留字面反斜杠,Windows 盘符与 UNC 根按 Windows 语义并保留大小写。空列表不放行任何路径,未匹配的路径也不回退到宿主根。
readDirectory 的条目记录可以带 isFile、size 与 mtimeMs,文件浏览器据此省掉每个子项的 stat;但列举元数据从不授予读取权限,未知类型也绝不从 isDirectory 反推。
语音、实时转写与实时语音 provider 接受描述符或同步工厂,工厂里不该加载执行 SDK、读凭据或开会话。用工厂参数发布的插件要把 compat.pluginApi 下限调到支持它的宿主版本,minHostVersion 不能替代。
registerComputerUseProvider 由 helper 负责两条命令的注册与网关调用策略,provider 负责可用性、执行、帧状态与清理。capabilities() 是同步声明读,不能在里面探测驱动;同一节点的命令对只接受一个 provider。
这个入口从 TypeBox schema 推断配置与参数类型,把普通返回值包成工具结果,并把静态元数据交给插件构建写进清单。execute 的返回值会成为 details 的原始值,不会被字符串化。
同一个工具的不同 action 可以返回不同结构,靠的是带版本号的 x-openclaw-input-discriminator 注解。失败结果也要写进对应变体,而带引用或超界的声明会退回保守的伞形契约。
该开关为 true 时,即使在机器人自己开的线程里、即使全局 requireMention 为 false,也必须显式 @。回复机器人、引用机器人与此前参与都不算满足,而且「参与」不等于「拥有」。
群线程的参与者提及事实要算一次并带进派发;ACP 专属路由应返回 undefined,路由变化后用专属判定丢弃旧事实。参与者选择必须是 @ 式匹配,裸名或表情不会选中某个 agent。
路由归属解析器返回 agent、plugin、unavailable、null 或 undefined 五种结果,其中 null 与 unavailable 的差别最容易写错:前者是无效或无权,后者只是暂时不可用、应当重试。
成功连接后掉线应发布 connected:false、lifecycle:recovering 与首次断线的 lastDisconnect 时间;共享健康策略给两分钟宽限,而 terminalDisconnect 与 blocked 只留给需要人工修的情形。
网关在 hello 交付前最多排队 15 帧、每帧 64 KiB;默认 connect 期限 30 秒是总预算而非空闲超时;附件按 base64 传输,20 MB 的单附件在线上约 26.7 MB,本身就超过默认 25 MiB 的帧上限。
audit.activity.list 排除 30 天以前的记录,共享 SQLite 账本封顶十万条;消息行刻意不含会话键,所以 sessionKey 过滤只对运行行与工具行有效;有界异步队列会丢记录,缺证据也不能反推「没发生」。
声明 presence-deltas 后收到重置或增量两种载荷;key 是进程内不复用的不透明身份,不可持久化;行序由 order 决定而非变更集;dropIfSlow 一丢帧就必须发重置。
节点连上后立即上报一次、之后每 60 秒一次 node.host.stats;节点从不发送时间戳,网关用自己的接收时间盖;Windows 三项负载均值全零时省略字段,macOS 的空闲内存含可回收部分。
AUTH_TOKEN_MISMATCH 只允许受信端点做一次有界重试;AUTH_SCOPE_MISMATCH 是令牌已识别但范围不够,不是坏令牌;OPERATOR_ACCESS_DENIED 是访问策略当前不授权,应当退避重连而不是改凭证。
device.token.rotate 只在对端本身用该设备令牌认证过时才回显替换令牌;令牌变更被锁在配对批准的角色集内;重连复用已存令牌时要保留它原有的作用域,别收窄成仅管理员。
PAIRING_REQUIRED 加 waitForResolution 只是把等待绑定到 requestId,期间不能发 RPC、不能订阅;被取代的请求只关 socket 不报批准也不报拒绝;批准后仍要重新做一次已认证连接。
sessions.subscribe 传非空 list 参数可在一次请求里订阅并加载名单;includeMessageBodies 决定是否保留消息正文;compact 与 sidebar 省略的字段表示未请求,不得用来清除已准入的详情。
host=node 的 exec 审批请求必须带 systemRunPlan,缺了直接拒;批准后转发的 system.run 复用这份计划作权威上下文;准备与转发之间改动命令、目录、agent 或会话键,网关拒绝运行而不是信任被改的载荷。
AI 快照用 f 前缀引用、角色快照用 e 前缀、无障碍树用 ax 前缀;引用在导航后失效,未知或陈旧的 ax 引用立即失败;批量动作在已提交的主框架导航或页面关闭后中止并报告第几个动作被跳过。
全局设置缺失时等同 auto,但写了 Code Mode 对象却没写 enabled 就是关闭;auto 只看提供方目录里的 compat.codeMode 是否标为 preferred;启用后执行器加载失败会停止运行,而不是回退到普通工具暴露。
timeoutMs 默认十秒,由 worker 准备、访客计算与内联工具等待共享;审批等待暂停这份预算,外层运行与工具的截止照常推进;阻塞计算耗尽预算报 timeout,未完成的工具调用则返回 waiting 并可被后续 wait 续跑。
嵌套工具调用跨桥重入后保留 agent、会话、渠道、沙箱与审批策略;完成的调用作为仅显示的活动持久化,被钩子抑制也只是不显示;持久化失败既不能撤销已知效果,也不能让重放变安全。
选中即独占记忆位,未选中的记忆插件被禁用;搜索按关键词而非向量,只声明 memory 一个源,因此对会话的请求在到达前就被拒;引用携带版本与哈希但不授予访问,版本一变读就失败。
八个内置技能是 agent 过程而非摄取引擎;只有摘要的输入不是已验证的会议摄取;共现不能证明雇用或出席;一个事件是一条带日期的断言列多个实体;来源里的指令从不授权动作。
纠正要求版本与哈希双围栏,原件保留内容只加被取代标记;撤回不删任何东西且没有取消撤回;替换件已存在时用取代而不是纠正,取代关系不可能成环,撤销取代只对取代工具做过的操作有效。
配对节点与其 worker 运行原生循环与编码工具,对同一操作系统用户下的代码不构成隔离;真实提供方密钥必须留在工作负载之外的托管服务里;原生提供方请求强制 HTTPS、拒绝一切重定向,Windows 上尚未提供。
所有者链接短期单次、只在同一浏览器身份有效;改过角色或公钥会换掉 requestId;作用域升级受角色上限限制,设备批准无法越过;被收窄的令牌再批准也不会被恢复。
威胁模型把渠道访问、会话隔离、工具执行、外部内容与供应链分成五层;私信配对给 1 小时、节点配对只给 5 分钟;仅提示注入而不跨边界的链条被明确列为误报模式。
应用自带运行时,不需要装 Node 或全局命令行;创建的命令只在不会替换操作者已选默认时才装上;从下载目录或临时目录运行不改 shell 配置;暂停不改变谁在管理网关。
微软Copilot集成Word/Excel/PowerPoint/Designer/Clipchamp,描述想法即可生成专业文档和设计。
同一个命令有两种形态。交互会话适合边聊边改,一次性的 -p 适合塞进脚本。分清它们,才不会把交互式任务写成跑完就退出的批处理。
hooks 跑的是代码,不是提示词。八个生命周期事件里,preToolUse 是唯一能直接决定「这次调用放不放行」的一个,也是安全策略最该落地的位置。
文本搜索找得到字符串,找不到符号。接上语言服务器之后,代理的跳转、引用、重命名都变成结构化查询,省下来的不只是时间,还有上下文预算。
这个能力让代理去点按钮、填表单、跨应用搬数据,专门对付没有 API 的老软件。默认关闭、按面授权、企业策略可覆盖,这三条决定了它能不能在团队里落地。
minimal、medium、xhigh、ultra 这些值不会报错,它们会被悄悄折进 low、high、max 三档;三套协议里开关参数的位置还各不相同。
发布不是上传完就上线:ClawHub 先校验令牌、元数据、名称、版本与文件,再把这次发布记为待审并针对该产物跑安全检查;未通过前不会出现在搜索、安装与下载里。
指令、上下文、验收标准三层写清楚,比堆形容词有效;官方文档里关于 rules、@ 引用与上下文窗口的做法。
Tour 会读 diff、把相关改动分组,贴着代码解释每组在干什么;按 T 切换,可定制深度与范围、按 commit 或「上次评审以来」看,写好的 tour 不占用量。
先下预构建的 clone kit 再补差量,成功时打印 mode: clone-kit、失败默认回落普通 clone;令牌最多 15 分钟不可续期,目标目录必须为空。
镜像后 GitHub 仍是唯一源头,Origin 只做副本;issues 与 Actions 配置不同步,名字为 origin 的分支也不同步,GitHub 挂掉时用 origin push local 继续写。
从 cursor.com/codebase 点 New 建空仓,团队仓要选 Internal 或 Private,个人仓一律私有且不显示可见性选项;建完用 Code 按钮取 clone 地址推首个提交,已有 GitHub 项目应走 Sync from GitHub。
HTTPS 地址形如 origin.cursor.com/{owner}/{repo}.git,SSH 用已注册公钥认证;镜像仓的 GitHub 才是事实来源,origin/* 分支只留在 Origin,靠 origin push local 推送。
Code 标签页能浏览目录、切分支、看提交历史;按 T 直接跳到文件,用搜索框找内容;作者筛选只在分支历史里可用,看单个文件或目录的历史时不提供。
批处理适合不急着要结果的活。要点在四处:jsonl 一行一个请求、custom_id 负责回填、八个状态里只有四个是正常推进、结果分成功与失败两个文件且只留 30 天。
智谱的上下文缓存是隐式的,不需要额外开关,但命中条件不宽松:重复前缀要够长,内容要完全一致,且只对标准 API 计费生效。命中量在 usage 里查得到。
同一个文件解析接口下挂了三档工具,格式、体积上限和输出形态都不同。选错的代价不是报错,而是拿回一堆丢了版面的文本,下游问答直接失准。
智谱给编程套餐用户做了一个本地 MCP 服务,把截图、图表、视频变成代理能读的输入。八个工具各管一类视觉任务,Claude Code 用户有个已内置的例外要留意。
智谱提供了 Claude API 兼容层,现有 Anthropic SDK 代码改动很小。但兼容不等于等价,请求头、地址与模型编码这三处必须一起改,否则报错很难定位。
大模型接口的限流通常卡的是「同一时刻有多少请求在处理」,而不是每分钟多少次。分清 1302 与 1305,才知道该退避重试还是该降级。
同样的企业微信后台,能生成好几种凭据。接托管智能体时只有智能机器人的 Bot ID 与 Secret 有效,选错类型会卡在连接建立这一步。
四类渠道里,个人微信是唯一需要扫码的,也是唯一把引用做成限时快照的。两个时限决定了它的运维节奏。
接口层允许一条事件带 50 张图,聊天渠道却只给 6 张。两套上限并不通用,混着用会在入队或处理阶段报错。
渠道不是把所有消息倒进一个会话,而是按稳定范围复用 Session。这个范围怎么划,直接决定了「记忆」到底记住了谁。
托管智能体的事件流不回放历史。断开十秒,缺的就是那十秒里发生的全过程,而补法有明确的锚点和去重规则。
会话停在等工具结果的状态时,输入通道是关着的。理解这一点,才能解释为什么「明明连着却收不到新消息」。
x-events-encrypted 只加密业务内容。状态、用量、模型请求区间这些照旧明文落库——这既是设计,也决定了密钥管理该怎么做。
用初始事件预置任务很省事,但创建响应还没回来,执行可能已经开始。这段缝隙正是最容易丢首轮进展的地方。
同一个沙箱里两个目录的寿命完全不同。搞混这点,第二轮复盘时就会发现中间文件凭空消失。
limited 模式的主机名写法很挑:写 https://github.com 会被拒。还有一个开关不开,声明了软件包就直接 400。
apt 先于 pip,npm 先于 pip?顺序写在实现里,不由你决定。同时自定义 registry 一律拒绝——这条常常卡住企业环境。
省略 tools 字段不是「用默认值」,而是空数组。第一次接托管智能体最常见的困惑,就出在这条空数组上。
tool_stream 只是把参数改成边生成边返回,不会替你执行工具。没拼完就解析 JSON,拿到的一定是语法错误。
clear_thinking 设成 False 只完成了一半,另一半是每轮把上一轮的思考文本按原顺序回传,顺序错了缓存就白费。
response_format 里能填的只有一个值,schema 得自己写进 system,再自己校验。把两件事当成一件,字段缺失就没人管了。
规范该进指令层,经验该进学习层。两者写在同一个文件里,经验就会慢慢污染规则,行为开始不可预测。
一次请求里真正耗时的多半是串行的多次调用、过长的输出和无效上下文,单次推理速度反而排在后面。
同一个档位字符串,走开放平台 API 和走编程套餐会被翻译成不同的实际推理强度。
增量内容、结束原因和用量统计出现在不同的块里,把它们当成同一个块来解析就会丢数据。
Web Search API 返回结构化网页结果,对话内搜索把结果直接揉进回答并标来源。选错接口会多写一层胶水。
传统 RAG 把文档切碎后,代词指代、章节归属和文档名一起消失;上下文增强给每个切片补一段可检索的描述。
全模态版、文本版、QA 版的判定取决于向量模型和导入格式,选错之后检索参数和切片策略都跟着错。
识别结果的单位是行,每行带左上角坐标与宽高,还能单独返回置信度均值、方差和最小值。
同一份格式清单里,不同文件类型的上限并不相同;越过这条线就该换异步任务,而不是继续重试。
团队套餐的限制大多不是软性建议,而是买完之后改不了的结构:席位不能减、标准版不能升高级、三种 Key 互不通用。
账号共享、用在非支持工具、异常高频调用都会触发风控;三次以上违规可能直接封号,而订阅本身不支持退款。
联网搜索、网页读取、开源仓库是三个独立服务,工具名和端点都不同,其中两个在 Claude Code 里已经内置。
改 base_url、换 Key、换模型编码就能跑通大部分代码,但思考参数、温度区间和确定性开关的写法并不一样。
基址不同、store 默认关闭、流式结束不发 [DONE]、没有 cancel 接口。这四点决定了迁移时要改哪几行代码。
一个是开关,一个是强度。把温度调到 0 不等于关闭采样,真正决定贪心解码的是 do_sample。
开关 1M 上下文要给模型编码加后缀并同步压缩窗口,而思考强度按「显式 effort 优先于开关」的规则落地。
外部文档、网页、工具结果只是材料,里面出现指令式语句也不该被当成新任务;结构的作用就是划清这条线。
任何语言都能调,关键是把 Bearer 头、JWT 签名和 stream 参数这三件事弄对。
不需要专门的 provider 包,把 ChatOpenAI 的 base_url 指过去即可。版本门槛、环境变量与记忆链是三个最容易出错的地方。
审核命中不会静默失败,而是带着错误码、角色与严重程度返回。同步与流式两种形态的处理方式不同,混着写会漏掉一半。
面向要在国内上线生成式 AI 应用的团队。备案号是合规材料里最容易被漏掉的一项,而它对应的主体未必是你签约的那家公司。
知识库不是把文件塞进提示词,而是在生成之前先检索、再把片段当背景送进去。调用侧只需要一个知识库 ID 和一段模板。
问题改写、QA 干预、重排、召回数量与分数、混合检索配比——调错哪一个,都会让「答非所问」看起来像模型的问题。
实时通话走 WebSocket,鉴权靠请求头而不是查询参数。会话配置、音频上传、响应生成三段事件分开,混着发就会听到断句。
base_url 换成 /anthropic 之后,claude-opus 系列会被接到 v4-pro,claude-haiku 与 claude-sonnet 接到 flash,而不以 claude 开头的未知模型名会直接返回 400。
不带 tools 时传了也被忽略;带 tools 时少传一轮就会 400。这条规则决定了多轮对话与智能体两条代码路径必须分开写。
strict 模式要求每个 function 都显式声明 strict: true,且只能跑在 /beta 地址上;object 里所有属性必须 required、additionalProperties 必须 false。
内联 base64 计入 48MiB 请求体,外链必须在 8192 字符以内且 60 秒内下载完,Files API 的 file_id 才允许单图到 64MiB。
小于约 544×544 的图会被放大,更大的图被缩到约 1300×1300 的像素总量,所以 2000×2000 与 5000×5000 花的 token 一样。
purpose 只能是 user_data;expires_after 的 anchor 只能取 created_at,秒数在 3600 到 2592000 之间,两项都不传则永久保留。
query 里的搜索语法会原样下发,支持 site: 限定、-site: 排除、-词 与 -短语 否定、lang: 语言、after:/before: 时间;结果里 rerank_score 与 authority 是两个不同的质量信号。
两条通道的配额互相独立,Fetch 还额外受按域名的 QPS 限制;搜索返回空数组、抓取没拿到正文,都不计费。
每个事件带 event 名与递增的 sequence_number,结束只有三种:completed、incomplete、failed;incomplete 表示被截断而不是出错。
previous_response_id、store、background、metadata 都不支持,store 恒为 false、parallel_tool_calls 恒为 true;超出上下文窗口直接 400,不会自动截断。
flash 并发 2500、v4-pro 500,按账号算而不看 API Key;user_id 同时承担内容安全、KVCache 与调度三重隔离,空 id 也算一个特殊用户。
400 与 422 是请求本身的问题,重试没有意义;402 要充值;429 是并发或 QPS 到顶;500 与 503 才是「等一会儿再来」。
1 个英文字符约 0.3 token、1 个中文字约 0.6 token,但不同模型分词方式不同,预算只能按返回的 usage 校准。
prefix completion 要求最后一条消息是 assistant 且 prefix 为 true;FIM 给前缀和后缀、让模型补中间,输出上限 4K。两者都要走 /beta 地址。
新版是 pip install zai-sdk 配 from zai import ZhipuAiClient,旧版是 zhipuai 配 ZhipuAI;类名、返回结构、解码方式都不同,迁移要改三处。
groupId 是 ai.z.openapi、artifactId 是 zai-sdk,示例版本 0.3.5;文档同页还写着最新版 0.3.3,接入前应以仓库实际发布为准。
赠金消耗不计积分,退款当月倒扣;等级按最近三个月的最高积分定,T+1 日 06:00 更新,所以一次大额消费能顶住三个月。
个人人脸识别即时通过,企业对公打款最快 30 分钟,企业法人人脸与营业执照授权各需 7 个工作日;企业账号不能改成个人账号。
Qoder 的模型选择器里本来就有 DeepSeek,直接用会消耗 Qoder Credits;想按自己的 DeepSeek 账户结算,得在「自定义模型」里填 API Key,而这条路只在个人版可用。
三个终端类代理都能接 DeepSeek,差别不在能不能用,而在三处:装之前要什么、Key 存在哪里、想换模型时改的是哪一层。
模型列表接口返回的不只是 id 和归属方,还带上下文窗口、单次输出上限、输入模态、思考档位,以及 Anthropic 协议下系统提示词怎么更新的两种语义。
这条路走的是 OpenAI 兼容的 Chat Completions。配置本身很短,但文件位置、UTF-8 无 BOM、环境变量展开这三件事任何一件错位,模型都不会出现在选择器里。
DeepSeek 的模型名分两类:稳定的别名,和已经退役但暂时还能路由的旧名。写死版本号看起来稳妥,实际会在某次升级后悄悄落后一个版本。
同一批 400 里既有「参数名写错」也有「模型不存在」,光看外层状态码分不清该改什么。业务码才是处置依据,而它按号段分组这件事本身就是线索。
三种响应方式不是新旧关系,而是三类场景:要打字机效果用 SSE,要一次拿全量用同步,要跑批用异步。另一个常被搞混的点是输入上限怎么算。
把函数调用、知识库检索、网络搜索都塞进 tools 里,并不会让模型同时拥有三件事。它们互斥,且有明确优先级;tool_choice 也不像别的平台那样有那么多种取值。
订阅类产品的坑大多不在功能上,而在时间与额度的规则里:重置卡会刷新周期、退订要提前三天、再次购买不叠加时间而是折算价值、套餐不能共享。
上传完不等于能检索,中间要过两个状态;音视频各有自己的时长上限;而「上下文增强」一旦开启就不能回退。欠费超过七天,数据会进入删除计划。
联网搜索与开源仓库这两个 MCP 都是远程服务,不用本地安装。但装进不同客户端的方式差别很大:Claude Code 有内置的、Cline 要分新旧版本、Goose 得手工加扩展。
批处理最容易出问题的地方不在提交,而在提交之后:单文件有请求数与体积双上限,模型有排队上限,文件只留 30 天,过期批次里已完成的请求照样计费。
智谱的模型清单里,文本模型的限制用 token 计,OCR 用页数和文件体积计,视频与语音用时长计。搞混口径,比选错模型更容易出问题。
K3 系列把 temperature、top_p、n 全部固定,k2.6 是唯一保留非思考档温度差异的模型。同一份请求体换掉 model 字段后,哪些参数会从「无效」变成「报错」,需要提前看清。
思考内容不在 OpenAI SDK 的类型定义里,读要靠 hasattr 判断;它和正文共享 max_tokens 预算;多轮里传不传由 thinking.keep 决定,K3 与 k2.7-code 则必须传。
K3.1 Pro 始终推理,reasoning_effort 有 low、high、max 三档且默认 max。默认值不是「中庸」,而是最贵最慢的一档;换档还会打断前缀缓存。
缓存按请求前缀逐字匹配,写入单独计费、命中按十分之一计价。两档 TTL 互不通用,而且首次写入时就被锁定,改不了。
把几十个工具塞进顶层 tools 会让每个请求都背着全部定义。Kimi 支持在 messages 里追加带 tools 的 system 消息,但注入位置决定了缓存还能不能用。
auto、none、required 之外还能直接指定函数对象,但指定函数与思考开启不兼容,会返回 400。另外它不破坏前缀缓存,可以按请求粒度调。
同一个 429 可能意味着节点过载、并发超限、RPM 超限或余额不足,处理方式完全不同。Kimi 的错误类型分得比状态码细,排障应该先看 error.type。
带上一个随机 nonce 调用模型接口,响应头会返回时间戳与签名,再提交四个值即可校验。它证明的是「谁在何时以哪个模型接了请求」,不证明请求成功。
sites 最多 5 个且不能带空白与括号,time_window 接受三种日期格式并按周期第一天归一化。参数边界很清楚,踩线就是 400。
只接受 http 与 https,命中风控返回 403,页面没有可提取正文返回 404。返回的是标题加 Markdown 正文,图片以占位符形式保留在正文顺序里。
每行四个必填字段,所有行的 model 必须相同,一行的参数写错整批都会在校验阶段失败。任务从 validating 到 completed 中间还有几个容易被误读的中间态。
base64 与文件 ID 是两条可用路径,SVG 与图片 URL 都会被拒。content 必须是数组,序列化成字符串不保证被当成视觉输入。
前者只保证是合法 JSON,字段名、类型、是否多字段全凭模型;后者靠约束解码在采样阶段过滤非法 token。要接下游系统,差别就是写不写防御代码。
在 messages 末尾加一条 partial 为 true 的 assistant 消息,模型会以这段内容开头继续生成。用它续写截断输出时,要先确认截断发生在正文而不是思考阶段。
purpose 设为 file-extract 拿到的是抽取后的 Markdown 正文,不是文件 ID。多个文件就发多条 system 消息,别忘了组织存储配额只有 10 GiB。
Dreams 会开一个普通会话去读写记忆库文件。活跃会话数与每日计划相互独立,任一满足就触发;失败不会自动回滚,恢复只能逐文件处理。
金额单位是毫分(1 元等于十万毫分),查询时间用 epoch 毫秒、响应时间用 RFC 3339。按秒传时间不会报错,只会返回空数据——这种错最难发现。
每个会话一个独立沙箱,预装 Python 3.12、Node 24、.NET 8、Go 1.26、Rust 1.97,还有 LibreOffice 与 Chromium。上传文件、技能、插件全是只读挂载。
同名工具、同一组参数、连续多次、结果没有新信息——四条同时成立才算重复调用。多数情况下问题不在模型,而在 tool 消息没有正确回填。
模型列表页把「可用」「停新」「已下线」三种状态混排在一起,只看表格容易漏掉停新与全面下线之间的窗口期。迁移的关键不是换 model 字段,而是 thinking 与 reasoning_effort 的取舍。
Kimi API 没有记忆,历史全靠每次请求带上。截断策略的关键是把 system 消息抽出来单独保管,只对对话轮次做尾部裁剪,否则第一轮就会丢掉角色设定。
开启 stream 后返回的 chunk 用 delta 取代 message,reasoning_content、content、tool_calls 三类增量各有拼接规则。tool_calls 的 arguments 是分片字符串,覆盖写入会得到残缺 JSON。
ZDR 让请求内容在响应返回后即被清除,是企业客户按需开通的模式。它不改接口也不改计费,但批处理、直接上传的图片视频、托管智能体和第三方服务都不在范围内。
评测结果的方差很大程度上由题量和 max_tokens 决定,而不是模型本身。官方给出的推荐是推理类每题留足 128k 输出、总题量 500–1000,代码类 256k。参数不统一,两次评测的数字就没法比。
项目消费独立统计,但余额与组织限速共享。项目 TPM 设得比组织还高也无效,实际按组织上限走。预算达到后请求被拒,而消费提醒只发短信、不拦请求。
MoonPalace 在本地起一个 HTTP 服务,把 base_url 指过来就能录下每次请求。它按 request_id、chatcmpl_id 检索,还能在流式输出里检测并中断重复内容,避免白烧 token。
Kimi Code CLI 可以直接用开放平台的 API Key,但登录时要先在平台列表里选对来源。选错的话 Key 校验不过,看起来像 Key 失效。切换不需要重启,当前会话会直接换成新模型。
先上传提取文本,再把文本作为 system 消息放进 messages。文件内容、身份设定、作答规则都属于稳定前缀,必须排在对话前面;顺序一乱,Context Caching 就命中不了。
官方工具通过 Formula 暴露:先取工具声明,再让模型产出 tool_calls,然后按原样透传执行,最后带结果再请求一次。web-search 的结果包在加密字段里,可以直接塞回 tool 消息。
工具按执行方分为内置、MCP 与自定义三类。不声明 agent_toolset 时平台默认加载全套沙箱工具,但想单独关掉某个工具或改权限策略,就必须显式声明整个工具集。
每个会话都要绑定执行环境,且各自独享沙箱。依赖按五类包管理器预装、每类最多 128 条;网络默认放行但有安全黑名单,生产环境建议改成只允许指定主机。
会话事件分用户、智能体、会话三类;agent.delta 只在实时流里下发,必须显式加 include_deltas=true,历史事件列表里不会出现。续读时用哪个 id 做游标也有讲究。
会话状态只有 idle、running、terminated 三种,取消当前轮次回到 idle,归档才进入 terminated。stop_reason 说明本轮为什么停下,列会话时的过滤参数比翻页更省事。
官方金融投资分析助手采用 1 个路由主智能体加 13 个子智能体的结构:6 个执行角色按工作类型分工,7 个复核角色只给视角不下结论。委派时携带同一份上下文信封。
官方财务建模智能体把建模压成取数、规范化、预测、估值、质检五步,顺序不可跳;假设集中放在 Assumptions 表,改一处假设全模型联动,Checks 表逐期核对差额。
官方金融深度研究智能体在任务内部切两个阶段:研究阶段统一口径并定稿,产出阶段只使用定稿结论生成 Word 与 PPT。四个插件按阶段分工,两个 PPT 技能各管一件事。
晨报智能体的核心不是提示词,而是三层分离:触发器只管什么时候跑,工作流技能管板块与顺序,数据源插件管从哪取数。换数据源不动工作流,换工作流不动取数。
港股 IPO 扫描智能体把外部 PDF 当作纯数据源:其中的指令性文字一律不执行,按固定字段抽取,事实与推断分段,未披露字段行内标注,且不输出任何申购或回避的结论。
持仓可以口述、传文件或描述风格,三条路径收敛到同一张结构化持仓表。记忆库保存截止日与关键结论,有历史状态就走增量模式,换基准或大幅调仓则退回全量。
投行法律建议智能体的第一步不是检索,而是判断事项类型与适用板块。引用要落到文号、条款、页码,检索不到官方依据的一律进「待核实」,不许用笼统表述替代出处。
处罚记录是事实,日报是派生产物。官方监管处罚日报智能体先按文号查重落库,再从记录库取数生成草稿;缺文号的记录用机关、日期、当事人拼成查重键。脚本负责下载,模型负责语义解析。
主智能体撮合总账与子账、对账单读取员只碰外部文件、独立复核员自行重读源导出。拆分依据是信任等级而非工作类型,工具白名单按角色逐项裁剪,同一会话内的隔离靠提示词约定。
SRE 事故响应助手要求每条根因都带出处:文件行号、commit、指标时间点。变更要成为根因必须同时满足两个条件——在故障起点之前部署到受影响服务,且内容能解释观察到的问题。
游戏知识规模大且全玩家共享,要按需查询;玩家状态每人只有几 KB,可以每轮整份读取。防剧透不靠提示词劝阻,而是由业务后端在返回数据前完成裁剪。
创意、制作、营销、发布四岗各自定时触发、独立会话,通过记忆库交接;三道闸的结论落在岗位只读的闸口记录里。条件不满足就跳过并如实记录,而不是伪造完成状态。
智能体、环境、凭据库、记忆库、会话、触发器之间存在固定的依赖顺序。搞错顺序的典型症状是创建会话时报环境未就绪,或者凭据在会话运行后才想起来要加。
控制台把观测拆成会话工作区与智能体详情页两块。会话只有运行中、空闲、已结束三种状态;触发器暂停后恢复会跳过错过的时间点,不会补跑。
托管智能体的文件接口按请求头分成两套格式:带版本头返回 201/204 与 FileMetadata,不带则返回 200/200 与 FileObject。两套的成功码、字段名、列表范围都不同,混着解析必然出错。
会话文件通过 filesystem 接口逐层浏览、按 path 下载,一次返回该目录全部子项、不分页。但这套文件系统不保证持久化,需要长期保存的产出应该走产物接口。
托管智能体的 mcp_servers 只放连接信息,不放任何凭据;服务声明成功后全部工具默认可用,需要单独开关才用 mcp_toolset。每个智能体最多 20 个服务。
凭据按 MCP 服务地址匹配,多个凭据库命中同一地址时按绑定顺序取第一个;没有匹配就匿名连接。单个服务连不上不会让会话失败,只是本轮看不到它的工具。
记忆文件的每次创建、修改、重命名和删除都生成版本,但删除版本不含正文。要恢复被删的文件,只能取删除前的版本按原路径重建,重建后 memory_id 会变。
Basic 给标题加摘要,Pro 给与问题最相关且排好序的正文片段,fetch 给指定页面的 Markdown。选错接口的代价是白花调用费,或者把导航和广告当上下文喂给模型。
接口按 text_query 原样搜索,不会自动补全或改写。把实体、时间、限定词写全,再配 sites、time_window、limit、timeout_seconds 收窄范围,比反复重发同义查询有效。
迁移分三步:把提示词与工具定义收进智能体配置、删掉自建循环与历史存储、改成创建会话加订阅事件流再加发送事件。最容易漏的是订阅顺序——先订阅,再发消息。
Kimi 同时兼容 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。换地址与密钥即可迁移,但 thinking 和 partial 这类扩展参数不在标准字段里,要按各协议的方式传。
个人认证与企业认证的先后顺序、充值方式与账户等级的绑定关系、发票抬头受认证类型限制,以及几件做了就无法回退的操作。
同一份官方文档提供目录、全量与接口规范三种机器可读形态,体积差两个数量级。选错的代价是多花上下文,或者拿不到需要的细节。
提示词写不好往往不是措辞问题,而是缺了结构。用角色定视角、用分隔符切输入、用步骤约束流程、用示例定风格,四件事各自解决一类偏差。
控制台批量推理面向不想写脚本的场景,按项目组织,只对一定等级以上的账户开放。任务提交后可以离开页面,回来下载结果即可。
工作台把提示词、参数、工具调用和 token 消耗放在同一屏,适合在写代码前先验证方案;导出与 rerun 有几条需要提前知道的限制。
Playground 与 ModelScope 打通后,用魔搭令牌即可把已托管的 MCP 服务批量带进来;后续增删服务要走增量同步,而不是重新授权。
开源编程 Agent 通过内置认证接入中国区 Kimi,密钥不落配置文件;模型与推理强度分别用两条斜杠命令切换,状态栏会给出最终确认。
response_format 只保证输出是合法 JSON,不保证字段符合预期。三步用法里,真正决定可用性的是提示词里那份带字段含义的示例。
管理面密钥与推理密钥互不通用,每个密钥固定绑定一个组织,权限域在创建时选定。理解这三条边界,能避免大半权限类报错。
同一个字段三种写法对应三种行为:省略是保持不变,null 是清除限额恢复不限,数值是设置新上限。混淆它们会让预算被意外清空。
接口返回空列表不等于组织里没有操作。审计功能默认按组织开关启用,开启前的事件不会回溯,未开启时「空」与「没有事件」形态相同。
中断请求明细按写入即时可查,不受出账延迟限制;把自家网关的请求 ID 放进请求头,就能与计费明细逐笔对齐,不必靠时间加 token 数推断。
工作行被认领后进入租约状态,靠心跳续期、靠确认推进、靠停止释放。三元组对不上时返回 412 并带回当前 generation,重同步只能重新轮询。
同一个请求,两套口径。速率限制把 max_completion_tokens 全额计入,计费只认实际生成的 token。理解这点,才能解释「额度没满却被限速」。
为需要 OAuth 的 MCP 服务器授权时,平台开出的是一段可轮询的会话,授权成功后在凭据库里落一条凭证。重复发起与重复授权各有不同的返回。
向会话发消息返回 202,不等于模型已经开始处理。输入先进入待处理队列,按轮次投递或在步骤边界注入,排队上限与撤回条件都有明确规则。
会话停下来之后并不是只有一种状态。中断是请求,继续有前置条件,归档要求先空闲,删除又要求先归档,四步各自的错误码含义完全不同。
产物按版本管理:不指定版本拿到最新,指定版本拿到那一份确切内容;删除会连同全部版本一起消失,但已经上报过的事件不会跟着撤回。
会话创建时就把凭据库、记忆库和智能体版本钉死,之后只能追加文件。绑定数量有上限,重复绑定和文件名冲突都以冲突响应拒绝,移除文件会连带删掉工作区链接。
环境每次更新都会冻结不可变版本并触发构建,哪怕只改了元数据;新版本只对之后创建的会话生效。归档与删除各有前置条件。
更新智能体时,数组和元数据整体替换,但 mcp_servers 的请求头按服务器身份合并:缺省继承、非空替换、空串删键,唯独认错身份就会把配置冲掉。
凭据靠唯一键去重:OAuth 与静态令牌按规范化后的服务地址,环境变量按变量名。批量写入一次最多二十条且全成功或全失败,删除前必须先归档。
插件归档不是改个状态位:读取接口全部返回找不到、项目内名称被释放、后续唤醒与挂载解析时会把已固定版本的存量智能体一并过滤掉。
记忆库归档没有回退接口,删除要求先归档且不绑定任何会话。删除会连同全部文件、版本历史和 Dreams 策略一起清掉,策略持有的触发器被归档但运行记录保留。
降级或移除最后一名管理员会被拦住,创建者不可移除;移除成员会让他的 Admin Key 立即失效。邀请接口还会校验调用者此刻是否仍是管理员。
重复归档已归档的项目会成功返回当前状态,不刷新归档时间、不重复写审计;项目下的推理密钥随即被拒,成员与密钥元数据仍然保留。归档之后没有回退接口。
账单类接口通常要等次日早间才出数,中断请求明细不受这个限制,当天随写入即可查,按摄入时间正序,只给 token 量不给金额。
吊销立即生效但记录仍在,重复吊销报找不到;改名要求这把密钥同时属于指定项目与当前认证组织,名称长度有硬限制,响应里永远不含秘密值。
托管智能体与开放平台的上限分三类:单件体积、集合容量、分页与批量条数。超限时的状态码并不统一,配额类与限流类要分开处理。
技能版本内容返回的是 SKILL.md 原文,版本号必须是数字;插件版本内容返回压缩包,官方插件不给下载。两者对归档状态的反应一致:找不到。
会话更新只接受标题与智能体覆盖配置,其余字段一律不动;覆盖配置要到下一个轮次才生效,名单类覆盖只能在创建时给。列表接口看不到资源绑定,得取单条。
队列统计返回待认领数、租约中数量、持有租约的 worker 数、以及最老待认领行的入队时间。四个数字按活跃行实时计算,终态行则作为审计轨迹保留。
开放平台、Kimi Code 与会员是三套独立账户:余额不互转,Key 不通用,境内境外还是两套。混用时报的 401 与 404 各有各的指向。
非流式请求要等整段生成完才发响应头,中间网关以是否收到状态码判断连接是否有效,等待过久就直接断开。这就是 Connection Error 的一个常见来源。
这个参数只决定模型最多能生成多少 Token,它甚至不会进入提示词。想控制篇幅,得靠提示词、二轮纠正或分章节填模板。
这个接口的入参与 chat completion 基本同构,可以先算出输入占用,再从上下文窗口里扣出可用的输出余量,避免撞上 finish_reason=length。
OpenAI SDK 默认会对连接错误、408、409、429 与 5xx 自动重试两次,一次失败调用在服务端会变成三次,全部计入 RPM。tier0 账户一次就能把额度用完。
客户端不显示不等于请求失败。超时、代理断开、自动重试与工具循环都可能让服务端已经完成调用。排查要走五步,申诉要备齐七样材料。
这个错误在输入与输出两个方向都会触发。第三方平台还可能套用自己的安全策略与话术,报同样的字样却与 Kimi 无关。
文本类文件才抽取文字,图片与纯图片 PDF 已不再抽取;file_id 不能当上下文引用;base64 编码文本会带来巨量 Token。
把 base URL 指向 /anthropic 就能用 Anthropic SDK 调 Kimi。但缓存开关只在顶层生效,usage 里 input_tokens 的算法也与 Chat Completions 相反。
store 固定 false、background 固定 false、previous_response_id 与 conversation 固定 null。想在多轮里接着上一轮,只能自己拼 input 数组。
搜索接口按单独的 QPS 列限速,两个搜索接口分别计数。超限返回 429 并带三个限速响应头;另有风控限速一旦触发就无法解除。
触发器处于 reuse_session 时,托管会话沿用创建时的智能体、环境与资源,改这四个字段直接返回 400。要改,先把 session_mode 换掉。
手动运行可以强制启动已暂停的触发器,但已有运行在进行时返回 400;reuse_session 模式撞上还在跑的会话,则返回 skipped 与 overlap_in_flight。
同一个插件下,manifest 里声明过的语义版本不能再发;2.0.0-rc.1 这类预发布版本只有被精确固定引用时才生效,且不会顶掉正式版。
创建记忆就是往记忆库里放一个文件并记为第一版。同路径已有未删除文件返回 409,重建已删除的路径会成功但生成新的文件 ID。
删除记忆版本正文会永久抹掉该版本的内容,但保留版本记录本身。当前版本不能这么删,重复执行则是空操作。
这个接口按请求顺序报告每个 MCP 服务器地址在哪些凭据库里有活跃凭据。只有 OAuth 与静态 Bearer 计入覆盖,URL 规范化失败则一条都不匹配。
MoBA 把 MoE 的门控思路搬到稀疏注意力上:上下文切块、按 query 动态选块、保持因果性。官方技术文章给出的数字是 1M 上下文 6.5 倍加速。
官方技术文章给出的两个关键改动是加权重衰减、按参数调整更新比例,使矩阵与非矩阵参数的更新 RMS 一致。扩展性实验里约用 52% 算力达到 AdamW 的水平。
成员、邀请、项目、项目推理密钥这些集合端点一次性全量返回,连排序方向都不统一;账单、用量、审计才用游标。给全量端点传 page_size 不会报错,只会被静默忽略,于是你以为在翻页,其实一直停在第一页。
读端点每分钟六十次、写端点每分钟二十次,计数维度是组织加端点,同一组织下所有 Admin Key 共享同一份额度。请求明细、中断请求、用量聚合另有一套五并发的限制。超限返回 429,且不带 Retry-After。
用量聚合支持按分钟、小时、自然日三种粒度,单次窗口上限分别是二十四小时、三十一天、九十三天,桶按上海时区对齐。没有数据的桶不返回行,所以「少了几行」不等于「那段时间没调用」。
产品账单把费用拆成现金与代金券两列,合计才是实收。而外层总额减去模型明细合计,剩下的并不是误差,而是缓存调用、工具调用、缓存存储、批处理这类只计入外层汇总的非 token 费用。
调用推理接口时在请求头带上自己的请求标识,计费明细会把它落成 client_request_id。之后拉请求明细,用这个值精确对行,不必再靠「时间加 token 量」去猜是哪一笔。
输入必须是 jsonl 扩展名、非空且不超过一百兆,每个组织最多一千个批处理文件,同一批次内只能用同一个模型,文件里的 custom_id 必须唯一。任一条不满足,任务会停在校验阶段。
从校验到完成,批处理任务会经过八个状态。只有校验中、执行中、准备结果中这三种可以取消,取消后先进入「取消中」再落到「已取消」,中间那一步不是终态。
成功的输出落在输出文件,失败的行落在错误文件,两者分开。部分成功的批次两个文件都有,必须合并处理;只取输出文件,会静默丢掉所有失败行。
顶层只声明一个搜索工具,用 tool_choice 强制首轮检索,再把命中的工具定义通过一条 system 消息注入对话。工具从那条消息的位置开始可见,且按请求生效,服务端不会记住。
每个 tool_call 都必须有一条对应的 tool 消息,数量与 ID 都要对上;而那条携带 tool_calls 的 assistant 消息必须原样留在对话里,否则会报找不到调用 ID。流式输出下还要按 index 把参数字符串拼回去。
以内容抽取用途上传的文件,取回时是 Markdown 格式:加粗、标题、列表、表格都以语法呈现,列表中还会夹着空注释块。下游要纯文本,得自己解析后再剥离。
错误响应统一包在 error 对象里,含类型、错误码、说明、参数名与请求 ID。参数名指向出问题的字段而不是位置;请求 ID 是找平台排障的唯一凭据。另有一类「静默忽略」,它不报错。
组织成员接口返回的 role 是组织角色,项目成员接口返回的是项目角色,两者都叫 admin 或 member,权限范围却完全不同。看字段前先看是哪个接口,否则会把「项目管理员」当成「组织管理员」。
打开 logprobs 后,响应里会多出每个输出 Token 的对数概率;top_logprobs 再给出该位置的前几名候选。两个参数有依赖关系,且只覆盖模型自己写出来的字。
当响应的大部分内容可以预知时,把预期文本放进 prediction.content,官方给出的收益是降低响应延迟。它只有一个类型、两种写法,也不改变最终输出由模型决定这件事。
这个字段的用途是让平台在需要时判断「是不是同一个用户」,因此它要求稳定且不可反查。填明文邮箱、每次请求换随机值、多个用户共用一个值,三种做法都会让字段失效。
stop 最多五个字符串、每个不超过三十二字节,按完全匹配触发,命中词本身不会出现在输出里。中文按 UTF-8 计字节,一个三字词就占九个字节,长句很快越界。
这个字段不存内容,只决定哪些请求算同一组前缀。Coding Agent 里它通常是会话或任务 ID,退出再恢复必须保持不变;Kimi Code Plan 场景下它是必填项。
工具定义的 parameters 默认按严格模式约束,不符合 MFJS 规范时会报错或给警告;想放宽成「只要合法 JSON」,要显式关闭 strict。上线前可以用官方的 walle 自检 schema。
available_balance 是现金与代金券之和,但当现金为负(欠费)时,可用余额会等于代金券余额。余额单位是元,而 Admin 账单的单位是毫分,混用会让对账差两个数量级。
/v1/models 除了返回模型 ID 与上下文长度,还带图片、视频、推理三项能力布尔值。调用前查一次,比在代码里写死模型能力表更稳,也能解释 404 与 401 的两种成因。
这三个能力都不是「发出请求就收费」。搜索要有非空结果、抓取要有非空白正文才会记一次;批量推理按折扣单价结算且缓存命中不保证;托管智能体则是沙箱时长、模型 token 与插件次数三段相加。
列表、详情、创建三处返回的被邀请人联系方式都经过同一套脱敏;昵称只能中文、字母、数字,缺省时按联系方式类型自动生成。写操作还要求调用者此刻仍是组织管理员,否则返回 owner_not_admin。
官方承诺破坏性变更只随新的带日期版本发布,当前版本内的条目都属于非破坏性,客户端需要容忍新端点、新字段与枚举新值。问题在于,默认值调整也归在非破坏性里。
temperature 只在非思考模式下有意义;top_p 则要按模型和模式分四种情况看,flash 在非思考模式下直接忽略传入值,v4-pro 在开启工具调用时把值锁成 0.95。frequency_penalty 与 presence_penalty 已被标记弃用,传了也不生效。
不传 max_tokens 时,非思考模式按 8K 计,思考模式按 64K 计,reasoning_effort 为 max 时按 128K 计,上限统一是 393216。stop 最多 16 条;被长度切断与输出不成 JSON 是两种完全不同的失败。
stream_options 必须与 stream: true 同时出现,只传它会返回 400。include_usage 只决定中间帧有没有 usage 字段,最后一次统计始终存在,并且骑在最后一个内容块上,不是独立一帧。
logprobs 是开关,top_logprobs 是每个位置多给几个候选,取值 0 到 20 且必须先把 logprobs 打开。思考内容另有单独的概率数组,落在前 20 名之外的 token 用 -9999 标注,不是概率为零。
对话补全里 required 与具名写法在思考模式不被支持,接口返回 400,必须先关掉思考;Anthropic 端点更宽松,any 会被当成 auto,具名客户端工具同样报错,disable_parallel_tool_use 则完全不生效。
在 DeepSeek 的 Anthropic 兼容端点上,system 是顶层字段、不在 messages 里;工具结果块要排在文本与图片块之前,每个待处理调用只能有一个结果;thinking 块必须原样回传,签名却不做校验。
显式给出 thinking.type 时它优先,没给才看 output_config.effort;两者都不设置时思考默认开启。adaptive 等同 enabled,budget_tokens 被忽略,只有 effort 这一项真正决定档位。
在 Anthropic 兼容端点上开联网搜索,靠的是 tools 里的 web_search 服务端工具,type 有两个等价取值。max_uses 默认通常是 5,Claude Code 搜索子代理场景是 1,超出后返回 max_uses_exceeded。
同一个模型家族,三个协议端点对图片位置的容忍度不同。能把图放进 assistant 消息的写法在这里会被拒;files 上传的图片在 Anthropic 端点要额外带头,在 Responses 端点则完全不支持文件输入。
input 可以是一句字符串,也可以是条目数组,支持的七种条目类型之外一律被忽略。思考条目与函数调用条目会被并入相邻的助手消息,web_search_call 回传能恢复上次的搜索结果。
中段补全接口要换 beta 地址才能用;echo 打开后就不能再给 suffix 或 logprobs,logprobs 最多会返回比请求多一个元素,max_tokens 允许写 0,停止序列不会出现在返回文本里。
列文件接口用 file_id 做游标,limit 默认 1000,order 默认按创建时间升序,purpose 只能按 user_data 过滤。文件对象里的过期时间字段只在当初设了过期才会出现,删除返回的是状态而不是对象。
搜索接口返回的每条结果都带相关性分与权威等级两条质量线,摘要分短长两种长度、分别给界面和模型用。正文默认不返回,need_content 不打开时 content 恒为空字符串。
查余额返回的是「是否可用」加一组按币种分开的金额。可用性的判断交给服务端,客户端不必自己比较大小;三个数字里总额等于赠送与充值之和,赠送部分只算未过期的额度。
Base URL 必须与同一计费方案的 API Key 配套,各地域的 Key 互不通用;三类域名的可见范围不同,同一域名下三种协议只差一段路径。
地域决定数据存放位置,服务部署范围决定推理在哪算,接入域名决定超时、协议与 SLA;三者混为一谈会在合规和容量规划上同时踩坑。
这个参数不是 OpenAI 标准字段,Python 要放 extra_body、Node.js 放顶层、Java 走 extraBody;只思考模式的模型则根本没有开关。
思考长度上限到点即停、立刻转去写答复,只有越界才 400;把历史思考回传给模型会让它计入输入 Token,两件事常被混着配。
看响应里有没有 reasoning_content、用量里 reasoning_tokens 是否大于 0;如果开关前后耗时几乎一样,那就是参数没送进去。
流式与非流式的正文位置不同,结束符是 data: [DONE];非流式超时后服务端会返回半截内容并加一个响应头,这类「成功但不完整」最难察觉。
OpenAI 协议默认不返回 usage,要显式打开 stream_options;思考阶段则靠 reasoning_content 与 content 谁为空来判断,空字符串和 null 是两套规则。
增量输出每块只带新内容,非增量每块重复全部已生成内容;DashScope 的 Python SDK 2.0 已默认增量,而思考模式要求它必须为 true。
这是硬条件不是建议,缺了直接报错;JSON Object 只保证是合法 JSON,不保证结构,键名和类型都可能随提示词漂移。
multipleOf、uniqueItems、patternProperties 这些关键字不被支持,提交即 400;另外开结构化输出时不要设 max_tokens,否则 JSON 会被截断。
最后一条消息的 role 设成 assistant、content 放前缀、再加 partial 为 true;它也是修补截断输出与超时半截结果的正确工具。
每次请求都要把历史消息重新拼进 messages;官方给了截断、滚动摘要、向量召回三种上下文管理策略,各自丢的东西不一样。
Responses 用上一轮响应自动串上下文,有效期七天;传错层级会变成「新会话」,模型表现成记不住上文。
MCP 工具在 tools 数组里配置,server_protocol 目前只有 sse 一个取值;调用涉及多次外部交互,文档建议一律开流式。
401 查 Key 与域名是否同源,404 查模型是否在该地域可用,429 分限流与额度两种;Request ID 不在手上时还能从监控日志里捞回来。
enable_search 之外还有策略与来源返回等进阶能力,DashScope 全支持而 OpenAI 兼容少了来源返回与角标;多模态模型走错端点会直接 400。
wan3.0-video 用同一套参数覆盖文生、图生、参考、编辑、延长五类任务,靠 input.media 里的 type 与提示词意图自动分派;但不同任务允许的 type 不能混用。
duration 支持 2~30 秒与 -1 智能时长,但带视频输入时输入加输出不能超过 30 秒;分辨率、宽高比与音频开关也各有默认值。
编辑和延长都不靠单独接口或参数,而是靠 reference_video 加上含编辑或延长意图的提示词触发;不写意图,同一段素材就变成参考生成。
SDK 的 videos.generate 会提交并等待,HTTP 则要先建任务拿 task_id 再查询;两者都要求模型、Endpoint 与 Key 同地域,SDK 版本也有下限。
百炼文生图里 negative_prompt 只覆盖部分模型,wan2.7-image-pro、wan2.7-image 与 qwen-image-2.1 系列都不支持,只能把否定写进正向提示词。
文生图能在画面中生成中英文,但长文本易错字漏字;prompt_extend 默认开启、额外耗时 3 到 5 秒,两种改写模式还各有限制。
size 统一是「宽*高」格式,但 qwen-image 系列给的是像素区间,wan2.7-image-pro 给的是 1K/2K/4K 缩写;4K 只在纯文生图场景可用。
enable_sequential 默认 false,只有 wan2.7-image-pro 与 wan2.7-image 支持;开启后 n 取 1~12,且 thinking_mode 与 color_palette 同时失效。
单文件不超 5 万条请求与 500MB、单行不超 1MB、同文件同模型同思考模式、custom_id 不超过 256 字符、四个字段必填。
即使 enable_thinking 设为 true,结果文件中的 message 也只有 content 与 role;enable_thinking 还必须放在 body 顶层,放进 extra_body 不生效。
百炼智能路由用 auto-model 前缀加 8 位随机字符作为调用入口,只支持两种地域、三类协议与 maas 域名,备选模型至少选两个才能部署。
内置切换默认开启、整请求重发而非中途换模型;限流、确定性错误、超时与流式已开始返回都不触发切换,错误会原样透出。
创建预留后要替换请求里的 model 参数才生效;超出预留可选降级按量或直接 429,容量费按购买量计费,与是否调用无关。
百炼的模型压缩特指量化,产出模型不支持继续微调也不支持再压缩;仅华北2可用,且只接受平台微调产出的自定义模型。
百炼的 Prime 模式靠 model 参数指定支持模型的 model ID 即生效,TPS 提升到标准的 1.5 到 2 倍,限流规则也与标准模式不同。
语义搜索按存储与精度在 256、512、1024、1536、2048 维之间取舍;跨模态检索要先决定用融合向量还是独立向量。
auto、required、指定函数、none 四个取值在百炼并不是通用能力:Qwen 拿不到 required,Kimi 只有部分模型认,MiniMax 只认 auto,GLM 还得额外开 tool_stream。
parallel_tool_calls 默认开启,一轮可返回多条 tool_calls 并各带 index 与 id;把它设成 false 只对一部分模型有效,另有三家不论怎么设都可能一轮多返回。
工具定义去掉 function 外壳、调用结果从 output 数组里筛、结果回传换类型名、最终回复用 output_text。四处都要改,改一处必然跑不通。
工具集膨胀会同时推高选择难度、输入 Token 与延迟。文档给的解法是加一层路由:语义检索、混合检索、或用一个便宜的小模型先筛,最终交给主模型的不超过二十个。
默认只读、危险工具隔离、不可逆操作必须有人确认;再加上失败重试上限与超时提示,才算把一条工具链路放进生产环境。
除 messages 之外,工具描述本身也按输入 Token 收费;官方推荐用 tools 参数传工具,System Message 只在特殊场景用,而且要按模板写。
非实时的 Omni 走 Chat Completions 或 Responses,思考开关用 reasoning_effort;实时的 Realtime 走 WebSocket 事件,工具定义靠 session.update 下发,两个老参数直接不存在。
一张图的成本不按文件大小算,而按缩放后的像素数算。公式是 h_bar × w_bar ÷ token_pixels + 2,那两个 Token 来自图像序列的首尾标记。
尺寸、宽高比、格式、体积、请求体总量,以及那个容易被忽略的 DashScope 域名 16MiB 上限——六项里任何一项不过,请求都到不了推理。
公网 URL 与本地路径最多 2048 张,Base64 只剩 250 张;做视频帧理解时又是另一套数字,从 80 到 8000 不等。
fps 既控制抽多少帧,也告诉模型帧与帧之间隔了多久;max_frames 只在 DashScope SDK 里存在,走 OpenAI 兼容就没有这个参数。
百炼去下载你给的图片链接时,要求响应头里必须有 Content-Length 和 Content-Type;OSS 内网地址一律不行,报错是 Failed to download multimodal content。
公网 URL、Base64、本地路径三条路各有代价:前两条走兼容接口,第三条只有 DashScope Python 与 Java SDK 认;选错方式,代码能编译但请求发不出去。
它限制的是单帧像素乘以总帧数,而不是某一帧的大小。超限时系统缩放帧,但仍会把单帧留在 min_pixels 与 max_pixels 之间。
use_multichannel 默认 false,所有音频按单通道解析。想保住左右声道或四通道 FOA 的空间信息,得显式打开,而且只对 qwen3.8-omni-flash 的音频输入有效。
n 的取值范围是 1 到 4,n=0 等价于 1;但只有 Qwen3 非思考模式与 qwen-plus-character 支持设成大于 1,而且一旦传了 tools 就必须设回 1。
默认只出文本。要让 Omni 模型返回语音,得先把 modalities 设成 ["text","audio"],再用 audio 指定音色与格式——格式只有一个选项:wav。
DeepSeek、Kimi、GLM、MiniMax、Ling 在百炼上有一部分是第三方直供,只能在北京地域调用,用之前要单独开通,模型名还带供应商前缀。
百炼的 Token Plan 用 Credits 统一计量,分个人版与团队版,个人版 Standard 与 Pro 都附赠 Harness 权益且不占用 Credits。它面向的是在 Claude Code、Codex 这类工具里连续对话的人。
订阅制和按量付费在百炼里是两套凭据加两个域名:Token Plan 的 Key 带 sk-sp- 前缀,接入地址走 token-plan 的专属主机,而不是常见的 dashscope 兼容域名。
Token Plan 提供的百炼 CLI 用 bl config agent 一条命令完成接入,参数是 agent 名、地域、API Key 和模型,model 固定写 auto 交给平台路由。
订阅制覆盖 Claude Code、Codex、Qwen Code、OpenClaw、OpenCode、Qoder、Trae、千问办公、Hermes Agent、DeepSeek Harness、WorkBuddy 等入口,但工具原生只处理文本协议。
百炼 Harness 把图像、视频、代码解释器、搜索、网页解析、语音等能力包装成八个 MCP 服务,统一是 HTTP Streamable 类型,鉴权头用 Bearer 加 DASHSCOPE_API_KEY。
知识库、记忆库、托管智能体这三项在 Harness 里不是 MCP 服务,而是靠 bl knowledge、bl memory、bl managed-agent 三个命令族调用,文档也指向独立的 API 站点。
大模型答不了私有知识,是因为训练数据里没有这些内容。百炼的零代码方案把文档切块、用嵌入模型转成向量存库、提问时检索 Top-k 片段再拼进提示词。
百炼建知识库时,类型选文档搜索、场景选基础文档问答、来源选上传文件,格式支持 PDF、Word、Markdown 等,索引设置保持默认即可,状态变为已就绪才能检索。
新版智能体不直接关联网知识库,而是关联知识检索服务。一个检索服务可以绑定多个知识库,每个库能设权重,权重越大检索结果在最终排序里越靠前,配置完必须发布。
百炼文档把 RAG 答不准的原因归到三个环节:分块破坏语义、嵌入模型没抓住核心语义、检索没召回相关片段。对应的调优方向是结构化文档与自定义配置。
百炼同时提供 Responses、Chat Completions 与 Anthropic Messages 三套协议。前两者在 compatible-mode/v1 下,Anthropic 那套在 apps/anthropic 下,SDK 的 base_url 写法也不同。
百炼的 skill 参数可以让对话模型直接产出 PPT,仅 qwen-doc-turbo 支持,分模板模式与创意模式,模板有四套,且使用 skill 时 stream 必须为 true。
百炼在千问 API 自带的内容安全能力之外,还能通过 X-DashScope-DataInspection 请求头调用 AI 安全护栏,用 input 与 output 两个键分别控制检测方向。
百炼的 max_tokens 已标记为即将废弃,替代者 max_completion_tokens 始终限制思维链加回答的总长度,但只支持一批较新的模型,且 Java SDK 暂不支持。
百炼的 reasoning_effort 在不同模型上支持的可选值完全不同,从只认 max 到默认 xhigh 一共五组,其中两组还会把 low 和 medium 静默映射成别的档位。
qwen3.8 系列不允许 reasoning_effort 与 thinking_budget 同时设置,同时设会报错;两者之间有一张双向映射表,low 对 4096、medium 对 16384、xhigh 对 262144。
DashScope 原生协议把纯文本与多模态分成两个端点,前者走 text-generation,后者走 multimodal-generation,messages 里的 content 一个是字符串一个是数组。
它只对「复杂工具」生效,默认关闭以保住精度,开启后换的是超时风险;支持范围只有 Qwen 与 GLM 两系,且要按系列逐个核对。
auto、none、required 与「钉死某个函数名」是四种不同写法,但 required 和强制指定在 Qwen 系列上并不总能生效,思考模式下更是一条都不通。
同一个字段,qwen-math 默认 0、qwen-vl 默认 0.01、思考模式 0.6、非思考 0.7、qwen-long 1.0;照抄别人的 0.7 很可能把模型推出了它自己的默认区。
top_p 的区间是 (0,1.0],默认值按「非思考 0.8 / 思考与三方直供 0.95」两档分布,QVQ 又是特殊的 0.5。
QVQ 10、QwQ 40、qwen-math 与 qwen-audio-turbo 1、其余 20;DeepSeek、Kimi、MiniMax 三系不支持它,传了也不会按你写的走。
qwen-max、qwen-math、qwen-audio-turbo、QVQ、QwQ、qwen-coder 是 1.1,其余 1.05,GLM 阿里云直供是 1.0;这个参数没有严格取值范围。
区间 [-2,2],正值降重复、负值增重复;非思考的 Qwen3 系与 Qwen3-VL 给 1.5,qwen-plus 思考模式 0.5,其余 0.0,部分三方模型未声明默认值。
取值 [0, 2^31-1],其余模型默认 1234;文档用的是「尽可能返回相同结果」,也就是给倾向不给承诺。
Qwen3-Max、Qwen3-VL、QwQ、Qwen3 开源与 Qwen-Long 默认 message;千问 VL/QVQ/Audio 设 text 不生效;Java SDK 调 Qwen3 开源传 text 仍返回 message。
它把像素上限抬到 16384 Token 对应的量,两套模型分别对应 16777216 与 12845056 像素;开启后 max_pixels 失效。
默认 false;开启后返回缩放后的高与宽,流式调用时这份信息在最后一个数据块里才出现。
默认 false,开启后模型可在服务端执行代码;HTTP 要放进 parameters,Java SDK 没有对应设置项。
华北2、新加坡、中国香港已推出业务空间专属域名,旧域名仍可用;各地域 API Key 不同,端点、region 与凭据要一起改。
在消息上标 cache_control 才开显式缓存,type 只有 ephemeral 一个值;用量里能看出命中量与五分钟档的创建量。
validating 失败不执行任何请求、finalizing 在控制台看不见、expired 与 cancelled 同标签不同因——批量推理的状态机决定了轮询逻辑该怎么写。
批量推理靠 custom_id 把响应绑回原始请求,这个字段有长度上限;需要回传更长信息时,metadata 的自定义字段才是通道。
五万条、五百兆、单行一兆、不超过模型上下文——四条限制里最容易越界的是单行体积,而不是文件总量。
extra_body 是 SDK 的透传机制,在 JSONL 文件里完全无效;而且即使开了思考,批量结果文件也不会返回 reasoning_content。
单价减半只是表层差异,真正的成本差别在于批量是独立计费项——不支持上下文缓存,也不吃预付费与免费额度。
dashscope.BatchInference 这类写法并不存在;跑批量要换 openai 包,把 base_url 指到兼容模式路径,五步流程串成流水线。
本地路径与内网地址能提交成功、状态也会流转,但那几条请求永远不会被处理完成;另外视觉模型的消息角色与思考预算也有例外。
文本与多模态模型填对话补全路径,向量模型填嵌入路径;两者请求体结构不同,套用同一份模板会整批失败。
auto-model 前缀加八位随机字符就是路由入口;域名只能走 maas,用原来的 dashscope 域名会得到「模型不存在」的假象。
两者都按每条请求单独判断,区别在优化目标;策略不是一次定终身,路由配置可改且几分钟内生效。
只勾一个模型部署不了;子账号只能勾有权限的;候选池由路由版本划定,不能跨版本拼装,配额不足还会被限流。
切换发生在请求级而非推理中途;限流、确定性错误、超时、流式已开始输出都不触发,因为换模型并不能解决问题。
携带结构化输出参数就只路由到支持它的模型;采样温度、工具选择、思考预算等在路由场景不可用,设了会报错而非忽略。
按量、资源包、吞吐预留、专属部署,差别在计费单位与容量保障强度;资源包只是折扣,不解决限流。
买下即计费,一条请求都不发也全额产生;到期后两小时仍可用、十四小时后彻底释放,这段窗口是续费的最后机会。
自动溢出保服务连续、超出部分转按量;仅用预留容量则超出返回限流错误且不计费。本质是「怕掉线」还是「怕超支」。
把模型字段填成对应的加速版编号即可,没有单独的加速开关;限流规则留了弹性——达到标称值后若平台有余量仍继续服务。
我的模型页面把调优产出与 OSS 导入两类模型放在同一张列表里,但两类的能力边界并不一样:导入目前只认 LoRA 与全参两种微调产物,其中全参导入还要账号在白名单内。
存储类型不能是归档类、加密只能用 OSS 完全托管、桶可以是私有、但不许把文件放在根目录。我的模型的 Bucket 下拉框只列已打上访问标签的桶。
adapter_model.safetensors、adapter_config.json 与 config.json 缺一不可,且必须直接铺在所选子目录下;训练一般留下 best 与 last 两个检查点,我的模型要求从中挑一个导入。
我的模型对 LoRA 有三条硬约束:rank 必须是 8、16、32、64 之一且所有层统一,训练中改过词汇表或 chat_template 的模型一律无法导入。
视觉语言模型导入前的自查只需要一步——枚举 safetensors 里的参数键。出现 visual 前缀说明未冻结,只剩 lora_A、lora_B 则说明冻结到位。
在我的模型里选中模型目录后,系统立刻调校验接口检查格式与完整性,失败会在目录字段下方标红并卡住提交,最常见的失败码是文件缺失。
模型名称、基础模型、训练方式、Bucket、模型目录是必填项,导入来源与模型加密则是只读项——前者恒为对象存储,后者由平台强制开启服务端加密。
创建中、创建成功、创建失败、已失效构成了导入模型的生命周期。已失效不代表模型坏了,而是桶里的源文件在导入之后被改动过,需要重新导入。
我的模型每行固定三个动作,但能点的很少。从 OSS 导入的模型不支持增量训练,量化模型要回模型压缩界面删除,创建中的记录连删都不让删。
调优模型部署成功后,我的模型只接受所在业务空间的 API-KEY,且只支持 DashScope 协议,OpenAI 兼容方式调不通;推理超参还要与离线微调时保持一致。
我的模型首次导入需要开通 OSS 服务关联角色,并给目标桶加上 bailian-datahub-access=read 标签。标签没加时导入会报 10041495,子账号还额外缺一条创建服务关联角色的权限。
PENDING、QUEUING、RUNNING、SUCCEEDED、FAILED、CANCELING、CANCELED 构成了压缩任务的全生命周期。停止只对等待与运行中的任务开放,删除只对终态开放。
选模板前必须先选源模型,因为不同模型支持的模板清单不一样;切换源模型会清空已选模板。产出模型名后缀限八位小写字母与数字。
只有当选中的量化模板带校准输入参数时,压缩表单才会出现校准数据字段。数据集上限五个,须先在数据管理里创建并发布,挂在 OSS 上的数据集不可选。
任务详情分详情与日志两页。日志可选显示最近 100 到 5000 行,开启后每 30 秒自动刷新,级别按颜色区分,全量日志可单独下载且不受行数限制。
百炼给出了按用途划分的替代关系:纯文本向量对位 text-embedding-v4,多模态对位 qwen3-vl-embedding 系列,重排对位 qwen3-rerank。已有 v3 索引的可以走维度兼容的 v3 型号。
重排序靠交叉注意力给候选打分,用来提升 RAG 的命中质量。它排在向量检索与拼装上下文之间,纯文本型号单次最多处理五百个文档,因此只适合精排。
首帧与尾帧各限一张,参考图十张、参考视频与参考音频各五段且总时长十五秒,文档与网页各限一个且彼此互斥。参考类素材与首尾帧不能出现在同一个请求里。
分辨率 480P 到 1080P,默认 1080P;宽高比七种,默认 adaptive 自适应输入素材;时长 2 到 30 秒,传 -1 表示智能时长。有声默认开启,视频地址只在 24 小时内有效。
万相3.0 允许把音频作为参考素材送进去,官方给了两条明确用途:按节拍驱动舞蹈动作,按语调驱动口型。参考音频最多五段且合计不超过十五秒。
万相2.7 有两套 HTTP 入口,异步端点强制要求 X-DashScope-Async 取值为 enable,缺头不会降级成同步而是直接报错;task_id 与图像 URL 都只有 24 小时有效期。
万相2.7 的框选编辑不是另一个接口,而是 bbox_list 参数:最外层长度必须等于图片数量,无框的图要放空列表占位,坐标用原图绝对像素,单图最多两个框。
万相2.7 的 content 可传 0 到 9 张图,格式支持 JPEG/JPG/PNG/BMP/WEBP 但 PNG 不带透明通道,宽高需在 240 到 8000 像素之间,单张不超过 20MB,数组顺序即图 1 图 2。
万相2.7 的 text 上限是 5000 个字符且超出部分自动截断而非报错,messages 仅支持单轮,想二轮微调必须重发完整请求。
万相2.7 的 size 可写 1K/2K/4K 缩写或具体像素,两者不可混用;4K 仅限专业版纯文生图,有图片输入时宽高比跟随最后一张输入图,无输入则输出正方形。
万相2.7 的 thinking_mode 默认 true,却只在同时满足「关闭组图模式」与「无图片输入」时生效,且仅两款 2.7 模型支持;color_palette 的门槛只有前者。
万相2.7 的 color_palette 需要 3 到 10 种颜色(推荐 8 种),ratio 精确到两位小数且总和必须等于 100.00%,仅在关闭组图模式时可用。
万相2.7 的 usage 含 image_count、size 与三个 token 字段,后三者不计费;n 在组图开关下有两套取值,任务数据只保留 24 小时。
查询万相2.7 任务时除 task_status 还会返回 submit_time、scheduled_time、end_time,三者相减可分辨排队耗时与执行耗时,超过 24 小时窗口会得到 UNKNOWN。
Qwen-Image 的正向提示词上限是 qwen-image-2.0 系列 1300 Token、其他模型 800 Token,negative_prompt 则是 500 字符,两者单位不同且都自动截断。
qwen-image-2.0-pro 与 qwen-image-2.0-pro-2026-04-22 能力相同,qwen-image-2.0 与 2026-03-03 同理;别名会随迭代漂移,需要复现时应锁带日期的完整名。
Qwen-Image 的 usage.image_count 文档标注为当前固定为1,即使 n 取到 6 也不会变;宽高另有 width/height 字段,task_metric 只在非 2.0 系列返回。
Qwen-Image 按成功生成的图像张数计费,调用失败或处理错误不产生费用也不消耗新人免费额度;n 在 2.0 系列可取 1 到 6,是最直接的成本杠杆。
Z-Image 的 prompt_extend 默认 false,设为 true 时价格高于 false,同时多返回优化后的提示词与思考过程;与千问默认开启、万相改用 thinking_mode 的口径都不同。
Z-Image 的 size 默认 1024*1536,总像素硬边界为 512×512 到 2048×2048,推荐区间是 1024×1024 到 1536×1536,官方按三档总像素给出十一种比例的推荐值。
百炼文生图返回的图片 URL 有效期 24 小时须立即转存;prompt 与 negative_prompt 都要过内容审核,违规返回 DataInspectionFailed;限流返回 Throttling 或 429。
万相文生图提示词指南给了基础与进阶两条公式,并把常用词按景别、视角、镜头类型、风格、光线五类整理成词典;V2 另有 prompt_extend 默认开启。
万相3.0 提示词指南给出一条可伸缩的七段公式,其中素材引用是唯一必须精确编号的一块,分镜块自带时间轴,后四块决定质感。
万相3.0 要求素材按上传顺序编号、图片视频音频分别计数,单素材可简写为参考图片,两件以上必须写明编号,同一素材可多处复用。
万相3.0 接口文档建议每镜头 4 至 6 秒,提示词指南建议每段 2 至 5 秒,两者交集在 4 至 5 秒;三种时间戳写法可任选,但要通篇统一。
万相3.0 提示词指南把镜头控制拆成六类大白话写法:声明单镜头、锁死机位、指定运镜、写转场词、标焦段景深、点高速摄影。
万相3.0 的台词格式是角色加说话动词加冒号加引号,多人对话须逐句署名,音色参考只需写一次即对该角色全部台词生效,无台词要显式声明。
万相3.0 的背景音乐分不写、点名、完全不要三档;环境音靠画面把动作材质气象写清即可自动补齐;音效可单独成句并带时间戳。
万相3.0 的负向清单按人物画面、文字水印、风格、声音、动作、运镜、空间、一致性八组组织,只写不希望出现的内容,可整块留空。
万相3.0 的白模参考把 clay render 视频当唯一蓝本,提示词要把镜头轨迹、剪辑点、构图、动作列为绝对保持不变,只放开材质颜色纹理。
万相3.0 的故事板参考有四条写法:开头声明仅作分镜指导、按宫格顺序逐格重述、分段数量不必与宫格对应、结尾统一画风并排除干扰。
万相3.0 把风格描述拆成画风、色调、情绪三块,位置可在开头或结尾,可展开也可只给关键词,缺一块画面就在对应维度上失控。
百炼文生图分万相、千问与 z-image 三个系列,千问内部又分旗舰、均衡、性价比三档;2.1 两档的图生图可传十张参考图,改写方向与选型顺序都要按档位确认。
wan2.7-image-pro、wan2.7-image 与 qwen-image-2.1 系列不支持 negative_prompt,排除元素要改成在正向提示词里写不要出现什么。
百炼文生图的 watermark 参数默认 false,开启后水印位于图片右下角且文案固定为 AI 生成;千问 2.1 系列还能按提示词自动输出透明通道。
万相3.0 把参考生视频拆成主体、运动、风格、音频四类用途,并给出只借某一层的写法,避免模型把整段参考素材连风格一起照搬。
万相3.0 的参考编辑用 reference_video 加 reference_image 组合,视频与图片分属两套编号,示例用三张图分别替换帽子与衬衫,并要求其余部分保持不变。
万相3.0 的动作示例把每个镜头拆成碰撞点、冲击波形态、介质层、破坏层与镜头反馈层五层,并给人声与环境音标出中心、环绕与左右声道。
Claude 的提示缓存有效期从写入或读取该条目的那次请求开始计时,不是从响应结束;生成耗时会吃掉寿命,命中读取则免费续期。
Claude 的最小可缓存长度按模型分四档,从 512 到 4096 个 token 不等;不足门槛时请求照常返回,只是既没写入也没命中。
Claude 的缓存按 tools、system、messages 三层向下包含,改上层会连带废掉下层;改 tool_choice 只废 messages,开关联网搜索则废掉 system 与 messages。
把 max_tokens 设成 0 可以只写缓存不产生输出,返回空内容与 max_tokens 停止原因;断点位置、思考配置与计费三处最容易出错。
cache_control 标在 tools 数组最后一项时,缓存覆盖从第一个工具到这个断点的整段定义;MCP 工具集与电脑操作工具集要把标记放在集合本身。
工具结果清理默认在十万 token 处触发、保留最近三对调用;clear_at_least 未设时没有最小清理量保护,工具入参默认随结果一起保留下来。
Opus 4.5、Sonnet 4.6、Haiku 5.5 及之后默认保留全部历史思考,更早的型号只保留当前回合;清理工具结果会让缓存前缀失效。
Claude 的计数接口免费但有每分钟上限,返回的是估算值;4.7 起换用新分词器,同一段文本约多出三成 token,迁移前必须重算。
Claude 一个批次上限十万条请求或 256MB;结果在全部完成或满 24 小时时开放,批次 24 小时不完成即过期,结果文件保留 29 天。
Claude 的 Files API 单文件上限 500MB、组织总量 1TB;文件不可改名,过期时间只能在创建时设一次,过期后下载返回 404 而元数据还留 30 天。
Claude 处理 PDF 时会把每页转成图片并另抽一份文字,因此 token 由两部分组成;单请求上限 128MB、600 页,上下文不足百万 token 时降到 100 页。
Claude 会把图片缩放到边与 token 双重限制之内,再补边到 28 的倍数;归一化必须用缩放后而非补边后的尺寸,否则每个坐标都会整体偏一点。
Claude 的结构化输出只接受 JSON Schema 的一个子集:数值与字符串约束、递归、外部引用都不支持;additionalProperties 必须为 false,所以字典要改成数组。
Claude 的停止原因有 end_turn、max_tokens、stop_sequence、tool_use、pause_turn、refusal 与上下文超限七种,只有 end_turn 是自然写完。
Claude 的努力度分 max、xhigh、high、medium、low 五档,多数模型默认 high,Opus 5.5 与 Haiku 5.5 默认 medium;它是行为信号而非硬性预算。
Claude 的 thinking 有 adaptive、enabled 加预算、between_tools、disabled 四种写法,各型号支持范围不同;新模型传 budget_tokens 会直接被拒。
Claude 的 MCP 连接器只支持工具调用,服务端必须是公网 HTTP;每个服务器只能被一个工具集引用,配置按工具级、集合级、系统默认三级合并。
计算机操作在新版里是一个工具集,截图、点击、键入被拆成 17 个成员;调用块里只有成员自己的参数,坐标永远按你回传的整屏截图计算。
计算机操作允许模型一轮返回多个动作块,执行必须按顺序且遇到首个失败即中止;漏答任何一个块,下一次请求会被判参数错误。
新版计算机操作没有显示宽高参数,回传的截图必须自己缩到模型的图像上限,否则整条结果校验失败;缩放比例还要留着换算坐标。
长循环里截图很快堆满上下文,单次请求超过 20 张图后每张都受更严的单边限制;裁剪要成批做,否则每轮都让缓存前缀变一次。
新版工具集删掉了名字与显示尺寸参数、把动作名搬到顶层、要求结果回显工具集名;最容易被忽略的是区域放大从默认关闭变成默认开启。
计算机操作的固定开销远大于普通工具:默认成员全开时约四千五百输入 token,其中放大约占四百一;旧版则是系统提示与每个工具定义分别计。
这个工具的定义只有类型与名字两个必填字段,参数结构由模型内置、外部改不了;会话重启会把工作目录、环境变量与进程一起清掉。
服务端不会替调用方截断命令输出,超限的请求直接失败;输出也只在下一轮请求里到达,没有流式,交互式命令一律跑不了。
查看、替换、新建、插入四个命令覆盖了改文件的全部动作;替换串必须与原文完全一致,命中多处会报错,撤销命令已在 2025 年 4 月的版本里移除。
搜索结果正文只能是文本块,来源可以是网址也可以是内部标识;引用默认关闭,且同一条请求里必须全开或全关。
搜索结果引用带三个下标:结果序号跨整条请求连续计数,起止块下标左闭右开,被引原文就是这段切片拼起来的结果,且不计入输出 token。
工具结果对内容块的要求比用户消息严:只要出现搜索结果块,同一结果里的其他块也必须都是搜索结果,否则整条请求校验失败。
纯文本与 PDF 会被自动切成句子,自定义内容不切;三者分别用字符下标、页码、块下标定位,粒度与格式互相绑定。
开启引用只小幅增加输入侧开销,被引原文在输出与回传输入两侧都不计费;文档标题与上下文说明会传给模型,却不进入可引用范围。
引用需要在正文里穿插引用块,与严格 JSON 模式互斥;想要每个字段都有出处,只能让模型按行输出再自己解析。
模型拒答不会返回错误码,而是空正文加一个专门的停止原因;细分原因带分类与说明,说明措辞不稳定,只能展示不能当分支条件。
出字前的拒答大多不计费,但生物、前沿模型、推理提取三类例外;流式场景里拒答发生在中途时,输入与已流出的输出照常计费。
服务端回退成功后,正文里会多出边界块,标明从哪个型号交接到哪个型号;顶层用量只统计最后作答的那一次,逐次明细在迭代数组里。
服务端会记住这段对话由哪个型号作答,后续带同样回退配置的请求直接路由过去;记录约保留一小时、按组织隔离,且只是尽力而为。
边界块的位置会被用来校验前后的思考块,因此必须留在原处;它之前产生的思考、连接器文本与客户端工具调用都不能回传。
同一份 OIDC 发行者登记里,jwks 字段由 type 决定密钥怎么来:走 OIDC discovery、走固定端点,还是直接内联。三者的差别不只是取法,还决定了 Anthropic 会不会去访问你填的 issuer_url。
发行者上有一个看起来不起眼的字段,取值区间是 1 到 176400 秒。它限制的不是 token 能活多久,而是签发方允许给出的最大时间跨度,而且断言里缺 iat 会被直接拒收。
重放保护看起来是「默认开启」的,实际效果却取决于签发方有没有写 jti。不带 jti 的断言会被接受,而且不触发单次使用校验。
发行者的密钥不是抓一次就结束,平台会持续轮询 JWKS。连续失败到一定程度,轮询会被暂停并记下时间;修好上游之后,还需要通过更新接口把暂停状态解掉。
归档不是软删除那么简单:archived_at 一旦有值,引用这个发行者的每一条联合规则都会拒绝 token 交换。而默认列表里已经看不到它。
联邦发行者的每一个端点都写着同一句话:需要 org:admin 作用域的 OAuth access token,Admin API key 不被接受。把这条认证差异搞清楚,能省掉一轮 401 排查。
注册一个遥测目标时,endpoint_url 填的是基础地址而不是完整投递地址。校验规则相当具体:必须 https、必须是主机名、端口只能是 443、不能带查询串或片段,末尾的信号路径由平台自己追加。
遥测目标的 headers 用来带采集器的鉴权信息,但它的校验比想象中严:数量、长度、大小写唯一性、字符集都有硬限制,host、cookie、user-agent 以及四个前缀的名字一律拒收。
遥测默认只导出标识、时间、状态与 token 数这类元数据;要连提示词与工具输入一起导出,得显式选 content。而有数据处理限制的组织,即使选了也只会拿到元数据。
工作区名单看起来是个数组,实际是被 type 三态驱动的规则。最危险的不是填错 ID,而是更新时切换了 type 却没给名单——include 会变成什么都不覆盖,exclude 会变成覆盖全部。
遥测目标的 delivery_health 只有三个字段,但足以判断链路是否恢复。关键在于:错误串只可能是那几种固定措辞,而且成功投递不会把错误清掉,要比时间戳。
mention_only 只是其中一档。automatic 会读在旁边并在觉得能帮上时插话,同时会在安静或繁忙的频道自行暂停;always_awake 取消了这种暂停;thread 则让每条新的顶层消息都得到一条线程内的回复。
访客策略只在频道里有 Slack 访客时才有意义,没有访客的频道完全不受影响。三档分别对应正常回答、完全不答,以及只用挂在该频道上的 Bundles 回答。
同一个值可能来自频道本身、Grid 共享频道、父频道、工作区、组织默认,或者内置默认。返回值里带着来源标识,排查「配置明明改了却不生效」时应该先读它。
分析接口里的指标分成两类:创建类计数在日期区间模式下是精确的,去重类用 HLL 估算、典型误差小于 2%,而且在聚合行上直接为 null。混着用会把报表算错。
产物维度只有两轴:规范 MIME 类型(8 个取值,含 other)与是否共享。所以接口返回的是全部非空桶的集合,不分页、不排序。另有一条时间分界需要记住:2026-08-17。
product 的取值有五个,但它并非在所有端点上可用:插件端点只有三个面会出现,产物端点只有四个面,而聊天项目端点直接不接受这个维度。
阈值型压缩在普通请求里开启,触发器的默认值是十五万输入 token,下限五万;触发器类型只有 input_tokens 一种,写给别的类型不会生效。
自定义摘要提示词是完全替换,不是叠加;而压缩块之前的思考块不会带到后面,摘要里没写的东西,模型之后就真的没有了。
pause_after_compaction 只让接口写完摘要就停,不保留原文;若随后把早先的助手轮次插回压缩块之后,部分型号的思考块会因前缀校验失败被拒。
压缩后继续对话必须把 compaction 块送回;Python 里直接 model_dump() 会补上 text: null 与 citations: null,接口以 Extra inputs are not permitted 拒收。
压缩多跑一次采样,这次采样的用量只出现在 usage.iterations 的 compaction 条目中;顶层 input_tokens 与 output_tokens 只统计非压缩迭代,直接读数会少算。
摘要步骤里模型偶尔会去调工具而不是写摘要,结果是 compaction 块 content 为 null、什么都没压;文档给的解法是在 instructions 里明确禁止调工具。
技能在请求里的形状只有一种,但两类来源的编号与版本格式完全不同:官方技能是 pptx 这类短名加日期版本,自建技能是 skill_ 与 skver_ 开头的编号。
创建技能新版本不是增量提交,而是完整文件集的快照,漏传的文件不会从上一版继承;新版本里 SKILL.md 的 name 还必须与技能现有名字一致。
省略 version 或写 latest,请求拿到的永远是最新版;工作区内任何人上传新版本,都会立刻改变生产环境的运行结果,还会顺带打掉技能那一层的缓存前缀。
响应里的 container 带着 id 与过期时间;下一轮不把 id 传回去,请求会跑在新容器里,之前生成的文件和铺好的技能目录全部丢失。
技能运行在代码执行容器内,不能访问外网、不能运行时安装包;加上单次 20 个技能、上传 30MB 与 SKILL.md 的字段上限,决定了技能该写成什么形状。
插件有 latest_version_id 与 served_version_id 两个指针,默认 served 跟随最新;一旦手动指定版本就进入钉住状态,而钉住是不可解除的。
安装偏好只有四档取值,组织级的值可能来自插件自身、也可能来自市场的默认;成员属于多个组时取最宽松的那一档,组设置是替代组织值而不是叠加。
扫描是组织开关,结果写在版本的 content_scan 里;null 表示这一版存于扫描开启之前,照常服务;而扫描结果是 fail 或 errored 时插件对会员隐藏,且不会退回上一版。
插件上传要求恰好一份清单文件、位于 .claude-plugin/plugin.json 且声明 name;请求体与解压后各限 200MB,超限返回 413 而不是 400。
owner.type 决定这个插件归组织还是归个人;成员个人市场里的插件可以读详情、下载文件、按条件删除,但上传版本与指定服务版本一律返回 403。
插件管理接口只对特定类型的企业组织开放,每次请求必须带 ce-plugins 的 beta 头;不带这个头不会返回 401,而是 404,与接口根本不存在时的响应一样。
部署的定时表达式必须是五段 POSIX cron,秒与年字段、L/W/#/? 这些扩展符号以及 @daily 这类简写都不被支持;时区是必填项,按 IANA 名称校验。
budget.max_list_cost 用货币最小单位的整数串表示,如 2500 代表 25 美元;上限在每次创建会话时复制进去,按标价而不是折后价触发,且只支持美元。
initial_events 会在每个新会话创建后立刻送入,条数范围是 1 到 50;其中 system.message 每次请求至多一条,并且必须紧跟在它所伴随的那条用户事件之后、排在末尾。
不出现的字段表示保持不变,显式写 null 才是清除这一层并存值并回落到继承。请求里只要一个值被拒,整份设置都不落盘;接口不接受幂等键,但同一份请求重复发是安全的。
这个模式约束的是 claude.ai 与 Slack 侧的人为改动,不是这套管理接口。打开后所有端点行为完全不变,只是人不能再改;模式本身也没有端点可以读写。
同一个字段名在查询参数里是 Slack 自己的 ID,在请求体与响应里是本接口发出的 slch_ 标识。混用直接 400;而 404 到底说明什么,需要另一条不带对象的请求来判断。
挂在工作的 Bundle 整个工作区可用,挂在频道的只在那一个频道可用。挂载记录的标识不随摘挂改变,而且它本身不带 Bundle 的 ID。on-call 设置管的频道一律 400。
只有被设置过的频道与工作区才有 ID,也才会出现在列表里——频道全集在 Slack 手上。没设置、不属于你、根本不存在,三种情况返回的是同一个 404,得靠另一条请求区分。
Slack 群组私信的 ID 与频道同形,于是 Claude 在里面被使用时它也会被设置成一条频道记录:能列、能读。改设置、挂 Bundle、删除一律 400,唯一放行的是摘 Bundle。
事件体里只有用户档案 ID 和 enac_ 开头的处置 ID,改了什么要自己回查档案。事件可能迟到、乱序,处置结束后还会从列表里消失,所以事实源是档案而不是事件。
一个组织最多 32 个端点,禁用中的也占位;更新时用空数组清不掉事件类型;要停投递只能禁用或删除;被系统自动禁用后必须显式发 enabled 才会恢复。
签名按 Standard Webhooks 验,5 秒内回 2xx,其余都算失败;重试几次后事件就被丢弃。端点还会因为跳转或非公网地址被系统停掉,停掉期间的记录不会补发。
只有在事件投递开启、且端点已注册之后发生的处置才有事件。更早的动作只能靠按状态列档案补,而这份列表可能在 next_page 变 null 之前就提前结束。
平台组织锁的是 Console 与一组 API 端点,企业组织锁的是应用。两套名单各自独立,且 Bedrock、Google Cloud、Microsoft Foundry 上的 Claude 完全不在覆盖范围。
IPv4 最宽到 /8,IPv6 最宽到 /32,整份名单最多 1000 条,且只能填流量真正离开网络的那个公网地址。写私网段等于永远不匹配。
保存前系统只比对当前浏览器的地址,不检查服务器、同事或明天的地址。改动最多要 15 分钟才生效,而找回的顺序是固定的四步。
null 表示角色数据暂时取不到,要重试才能与「确实没有角色」区分。而角色绑定在这套接口上是只读的,只能在管理后台改。
加人只要一个用户 ID,删除返回的对象只有组 ID 与用户 ID,既没有邮箱也没有加入时间。成员列表用 has_more 与 next_page 判断是否还有下一页。
服务账号的组织角色只有 developer 与 admin,默认 developer。创建 admin 角色必须用交互式凭证;工作负载本身只能建 developer 角色,这也决定了它能被授到多高的作用域。
name 只能是小写字母、数字与连字符,且在组织内唯一,重复创建返回 409。归档不是删除,列表默认看不到,要靠 include_archived 才会出现。
读取接口每次实时取值、不落库,多次调用返回同一个值;轮换只让新连接用新值,已建立的连接不断,重启后的连接器必须换成新值。
一次归档会把这个隧道上所有未归档的证书一起归档,主机名退役且永不再分配,令牌同时失效。对已归档的隧道重复调用会原样返回旧记录。
每个安装实例用 Apple 的设备校验证明自己是未被修改的正版构建,换来一枚一小时有效的令牌。它绑定工作区、只授权对话接口,且不携带任何终端用户身份。
Compliance Access Key 通吃全部端点,Admin API key 只到活动流;权限位建时定死、不能改,读写要拆两把钥匙。
开启在父组织一级生效并向下级联,同时禁掉浏览器直连 Claude API;关掉即停止记录,且缺口补不回来。
裸的 Not found 说的是认证或路径,点名资源的 404 才是已删除;本地会话那句本地不可用要保留队列而不是丢弃。
每次应用从服务器加载内容都会记一条,网页、桌面、移动的加载时机不同,计数不能当使用量或完整性依据。
保留策略清掉内容时活动流不记删除事件,只把策略变更记成一次设置更新;硬删除没有恢复窗口,要留证得先导。
活动流与聊天用游标,目录、项目与会话用 page token;游标绑定排序键,换 order_by 就报 400。
上界太靠近现在时,晚索引的事件落在已关闭的窗口里,之后任何窗口都读不到;解决办法是重叠窗口加周期对账。
七种 actor 各有字段,user_actor 可能是 Anthropic 代用户跑的后台进程,ip 还是 0.0.0.0;关联要用 user_id 不要用邮箱。
内容端点返回存储表示而非原件,size_bytes 与 md5 描述的是存储内容;格式要按字节判断,生成文件按 ID 前缀选端点。
每个文件名都用 RFC 5987 扩展形式返回,curl 的 -J 不认;把它当不可信输入,取基名、白名单字符、拒绝 - 和 . 开头。
同一个附件列表里混着上传文件与纯文本文档,靠 type 判别;不分支的消费者会在一半条目上拿到 400 或空内容。
项目里还挂着聊天时删除会被 409 拒绝;先列出该项目的聊天逐条删除或在 claude.ai 里移出,再重试删项目。
不带 user_ids 就是全组织范围,配合 updated_at 下界一次拿到新建、更新与已删除的聊天;重命名不保证复现。
本地会话按时间窗检索、无用户与组织过滤;远端会话可按组织与用户筛,但设了用户过滤就排除 agent 拥有的会话。
会话抄本有明确的排除面:非企业账号认证、经 Bedrock 等云平台、Claude Code 云会话、零数据保留,都不返回。
思考块、系统提示、工具定义、图片与 PDF 都不返回,各自用标记或占位符代替;引用元数据被抹掉但正文保留。
provenance 为空才是已验证捕获;非空时按原因分六类,其中 not_captured 也可能是策略不对外提供,而不是记录不存在。
两个字节上限默认 10,000,传 -1 取服务端上限约 1 MiB,传 0 直接 400;截断后的工具参数解析会失败。
超大会话会回两种不同的错,一个是页太大不能重试,一个是服务繁忙要原样重试;分页游标绑定会话与排序,24 小时后过期。
接受风险的说明在效期内让控制项判为通过;自动控制的检查失败时,即便有人证称已完成,结果仍是失败。