# Skill 机制详解 ## 目录 1. [Skill 机制简介](#一skill-机制简介) 2. [Skill 工作流程](#二skill-工作流程) 3. [Skill 比单纯 Prompt 更好用](#三skill-比单纯-prompt-更好用) 4. [Skill 典型文件目录结构](#四skill-典型文件目录结构) 5. [SKILL.MD 内容简介](#五skillmd-内容简介) 6. [Skill 各个目录作用](#六skill-各个目录作用) 7. [Skill 触发方式](#七skill-触发方式) 8. [Skill 在智能体整体架构的位置](#八skill-在智能体整体架构的位置) 9. [Skill 和 Tool / MCP / Prompt 的区别](#九skill-和-tool--mcp--prompt-的区别) 10. [例子：AI 安全评测报告 Skill](#十例子ai-安全评测报告-skill) 11. [Skill 设计关键点](#十一skill-设计关键点) 12. [Skill 目录位置](#十二skill-目录位置) 13. [Skill 的本质](#十三skill-的本质) 14. [最小可用模板](#十四最小可用模板) --- ## 一、Skill 机制简介 从原理上看，Skill 解决的是一个老问题：**大模型本身会推理，但不擅长长期稳定地重复执行固定流程。** 比如你希望一个智能体做到这些事： - 遇到"分析日志"类任务，就按固定排障流程来 - 遇到"生成周报"类任务，就套某个模板 - 遇到"改代码"类任务，要先跑测试、再改、再回归 - 遇到"处理 PDF"类任务，要调用固定脚本，而不是每次都靠模型自由发挥 如果你每次都把这些规则写进 Prompt，会有几个问题： - Prompt 很长，浪费上下文 - 每次都要重复写 - 容易漏规则 - 模型执行不稳定 所以 Skill 的核心思想是：**把某一类任务的"操作知识"模块化，平时只保留一个简短索引，需要时再展开。** OpenAI 的 Codex 文档明确提到，Skill 使用 **progressive disclosure（渐进式披露）**：系统先只看 Skill 的元数据，比如 `name`、`description`、路径等；只有模型判断当前任务匹配这个 Skill 时，才加载完整的 `SKILL.md` 内容。 ## 二、Skill 工作流程 你可以把一次调用想成 4 步： ### 1. 先注册技能 系统里有一批 Skill，每个 Skill 都是一个目录，最核心文件是 `SKILL.md`。其中至少会写两件事： - `name` - `description` 这两个字段是最关键的"索引"。OpenAI 和 GitHub Copilot 的文档都要求 `SKILL.md` 必须存在，并且要包含这些基础元数据。 > **百度搜索的 Skill 结构**：每次和大模型交互都会把 `name` 和 `description` 里的内容塞进大模型的 Prompt 里去，模型根据 `description` 判断是否需要使用这个 Skill。 ### 2. 运行时先做"技能匹配" 当用户提一个任务，比如： - "帮我排查 GitHub Actions 为什么挂了" - "把这个目录里的图片批量转 PNG" - "按团队规范生成发布说明" 系统不会把所有 Skill 全文都加载进模型，而是**先看 Skill 的 `description`**，判断哪些 Skill 可能相关。Codex 文档里说得很直白：隐式触发主要依赖 `description`。这个很关键，**节省大量不必要的 Token**（当轮对话不需要用到的 Skill 的详情描述）。 ### 3. 命中后加载 Skill 详情 一旦某个 Skill 被选中，系统会把该 Skill 的 `SKILL.md` 注入当前上下文。GitHub Copilot 文档也是类似说法：当 Copilot 选择使用某个 Skill 时，`SKILL.md` 会被注入到 Agent Context 中。 ### 4. 按技能说明执行，并调用配套资源 此时模型会： - 按 `SKILL.md` 的步骤执行 - 读取 Skill 目录里的参考文档 - 必要时运行 Skill 附带脚本 - 用模板、Schema、样例文件来约束输出格式 所以，Skill 其实是一个 **"模型推理 + 外部资源 + 固定流程"** 的组合体。 ## 三、Skill 比单纯 Prompt 更好用 它的价值主要有 4 个： ### 1. 减少上下文膨胀 不是每个任务都加载全部规则，只在匹配时展开。这个就是 Skill **最重要的工程价值**。 ### 2. 把流程沉淀成可复用资产 例如： - "发版检查 Skill" - "漏洞报告撰写 Skill" - "安全评测报告 Skill" - "日志排障 Skill" 这些都可以在团队里复用，而不是每个人都重新写 Prompt。 ### 3. 把不稳定的步骤外包给脚本 Skill 可以带脚本，模型负责理解和决策，确定性的机械操作交给脚本。OpenAI 的博客专门建议把 **mechanics** 放进 scripts。 ### 4. 更适合团队协作 因为它本质上是**目录和文件**，能进 Git 仓库，能评审，能版本管理，能 CI 化。 ## 四、Skill 典型文件目录结构 现在主流实现里，最常见的目录大致长这样： ``` skills/ └── my-skill/ ├── SKILL.md # 必需：技能定义、元数据、执行说明 ├── scripts/ # 可选：可执行脚本 │ ├── run.sh │ └── parse.py ├── references/ # 可选：参考文档 │ ├── API.md │ └── examples.md ├── assets/ # 可选：模板、静态资源、schema │ ├── template.md │ └── output_schema.json └── agents/ └── openai.yaml # 可选：某些平台的额外配置 ``` 这个结构和 OpenAI Codex 文档给出的结构基本一致：`SKILL.md` 必需，`scripts/`、`references/`、`assets/` 可选，另外还能有 `agents/openai.yaml`。 很多社区仓库也采用类似形态，比如 Streamlit 的 agent-skills 仓库同样把 Skill 定义为"一个目录 + 必需的 `SKILL.md` + 可选 supporting directories"。 ## 五、SKILL.MD 内容简介 最小可用版本一般是： ```markdown --- name: github-actions-failure-debugging description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows. --- 按照下面流程排查： 1. 先查看最近 workflow run 2. 总结失败 job 日志 3. 必要时再拉完整日志 4. 输出根因、影响范围、修复建议 ``` GitHub Copilot 官方文档明确说 `SKILL.md` 是 Markdown 文件，前面带 YAML frontmatter，至少包含： - `name` - `description` 正文则写给 Agent 的执行说明、示例、约束。 OpenAI 的技能文档也是同样要求：`SKILL.md` 必须包含 `name` 和 `description`。 ## 六、Skill 各个目录作用 ### 1. `SKILL.md` 这是**入口文件**，作用相当于： - 索引 - 触发条件说明 - 执行流程说明 - 输出约束说明 它最像"给模型看的 SOP"。 ### 2. `scripts/` 这里放真正可执行的东西，比如： - shell 脚本 - Python 脚本 - 小工具 CLI 适合做**确定性步骤**，比如： - 批量转换文件 - 解析日志 - 生成固定格式输出 - 校验 JSON/Schema - 调 API 拉取数据 OpenAI 博客建议把这种机械、确定的流程放到脚本中，而不是让模型自己"想办法做"。 ### 3. `references/` 这里是补充知识，通常不是每次都要读，但需要时可以读，比如： - 团队规范 - 接口说明 - 业务背景 - 样例文档 - Playbook 它的作用是**避免把大量背景知识硬塞进 `SKILL.md`**。 ### 4. `assets/` 放静态资源，例如： - 模板 - 示例输入输出 - Schema - 词表 - 配置片段 - 图片、表格等资源 这类内容通常不是"知识说明"，而是被 Skill 直接引用的材料。 ### 5. `agents/openai.yaml` 这是某些平台的额外配置文件。OpenAI 文档里提到它可用于 appearance 和 dependencies 之类的附加元数据。 你可以把它理解成**"平台相关配置层"**，不是所有 Skill 都必须有。 ## 七、Skill 触发方式 一般有两种： ### 1. 显式触发 用户或开发者直接指定： - 用某个 Skill - 在命令里点名某个 Skill - 在 UI 里选择某个 Skill OpenAI Codex 文档里就说了，Codex 可以被显式调用 Skill。 ### 2. 隐式触发 系统根据用户任务语义，**自动匹配 Skill 的 `description`**，命中后再加载。 所以 `description` **不能乱写**。它不只是"介绍"，实际上还是**一个路由规则**。 ## 八、Skill 在智能体整体架构的位置 如果把智能体系统拆层，Skill 大概在这一层： ``` 用户任务 ↓ 任务理解 / 路由 ↓ skill 匹配 ↓ 加载 skill 说明与资源 ↓ 模型推理 + 工具调用 + 脚本执行 ↓ 产出结果 ``` 所以它本质上不是"模型参数的一部分"，也不是"底层工具本身"。 更准确地说，它是：**位于提示层和工具层之间的一层"能力编排封装"**。 它把： - 任务说明 - 工具使用规范 - 执行顺序 - 输出格式 - 参考资料 这些原本零散的东西，封装成一个可复用单元。 ## 九、Skill 和 Tool / MCP / Prompt 的区别 这个很容易混。 ### Skill vs Prompt - **Prompt**：一次性的指令 - **Skill**：可复用、可管理、可按需加载的指令包 ### Skill vs Tool - **Tool**：具体能力接口，比如读文件、发请求、执行 shell - **Skill**：告诉模型"什么时候用哪些 Tool，按什么流程用" 所以 **Tool 更像"手"**，**Skill 更像"作业指导书"**。 ### Skill vs MCP - **MCP**：更像给 Agent 提供外部系统能力的**协议/接入层** - **Skill**：更像基于这些能力封装的**工作流** 可以简单理解为： - **MCP** 负责"接进来" - **Tool** 负责"能调用" - **Skill** 负责"怎么用得对" ## 十、例子：AI 安全评测报告 Skill 比如你做一个"AI 安全评测报告" Skill。 目录可能是这样： ``` skills/ └── ai-safety-report/ ├── SKILL.md ├── references/ │ ├── scoring-rule.md │ └── report-outline.md ├── assets/ │ ├── report-template.md │ └── labels.json └── scripts/ └── summarize_results.py ``` ### `SKILL.md` 里写： - **什么时候触发**：当用户要求写 AI 安全评测报告、测评结论、风险概览时 - **必须先做什么**：先读测试结果，再按模板归纳 - **输出格式**：先写总评，再写分维度结论，再写案例 - **禁止做什么**：不要编造分数，不要扩展未提供的测评样本 ### `references/` - 打分规则 - 你们团队内部术语规范 ### `assets/` - 报告模板 - 风险标签映射表 ### `scripts/` - 自动把 JSON 测试结果汇总成 Markdown 表格 这样模型就不会每次都"自由创作"，而是按你想要的方式干活。 ## 十一、Skill 设计关键点 ### 1. `description` 要能路由 `description` 不是广告文案，而是**"匹配条件"**。 应该写清楚： - 这个 Skill 做什么 - 什么时候用 - 什么时候不要用 OpenAI 文档明确建议把 **scope 和 boundary** 写清楚，因为隐式匹配依赖 `description`。 ### 2. `SKILL.md` 不要写成百科全书 主说明要短，细节拆到 `references/`。 ### 3. 把确定性逻辑放脚本 例如解析、转换、校验、汇总，都适合放 `scripts/`。 ### 4. 输出格式尽量明确 最好给： - 模板 - 示例 - Schema - 禁止项 ### 5. 让 Skill 可审计、可版本化 因为它本质是文件目录，所以非常适合进 Git 管理。 ## 十二、Skill 目录位置 "Skill 长什么样"比较一致，但"放在哪儿"会因平台不同而变。 例如 GitHub Copilot 文档里提到，项目级 Skill 可以放在： - `.github/skills/` - `.claude/skills/` 个人级 Skill 可以放在： - `~/.copilot/skills/` - `~/.claude/skills/` OpenAI 的博客示例里则提到 repo-local skills 常放在： - `.agents/skills/` OpenClaw 的 Skills 根据来源分了几个地方： - `~/.openclaw/skills` - `/skills` 所以你可以区分两层： - **Skill 内部结构**：大致统一 - **Skill 放置位置**：因平台而异 ## 十三、Skill 的本质 一句话概括： **Skill = 面向智能体的"能力插件包 / 工作流包 / 操作手册包"**。 它的重点不是"多一个文件夹"，而是把原本散落在 Prompt、文档、脚本、模板里的东西，整理成一个可以被模型按需调用的能力单元。 所以从工程视角看，它有三个核心价值： - **减少上下文浪费** - **提升执行稳定性** - **沉淀团队方法论** ## 十四、最小可用模板 你如果自己做 Skill，可以先用这个骨架： ``` my-skill/ ├── SKILL.md ├── scripts/ │ └── run.py ├── references/ │ └── guide.md └── assets/ └── template.md ``` ### `SKILL.md`： ```markdown --- name: my-skill description: Use this skill when the task requires XXX. Do not use it for YYY. --- # Purpose 这个 skill 用来处理 XXX。 # Workflow 1. 先读取输入 2. 按 references/guide.md 的规则分析 3. 如需批处理，运行 scripts/run.py 4. 按 assets/template.md 输出结果 # Rules - 不要编造输入中没有的信息 - 输出必须包含结论、依据、风险点 - 如脚本失败，明确报错原因 ```

web73页面模板更新 请使用/ai/wks/elec/skills/web73-template-updater工具对/ai/wks/web73/views/xuetu目录下以llm_开头的html页面进行更新 阅读/home/xt/wks/xy/skills/web73-template-updater这个技能 请使用web73-template-updater工具对web73/views/xuetu目录下以math_开头的html页面进行更新 - 交互式沟通 -------------------- ### 生成skills ``` 按照下面的要求，生成一个skills ``` ## 页面模板更新 ### 任务背景 web73(一个使用了模板的go gin html前端) 项目中的 页面需要统一引入必要的 JavaScript 库和模板组件，以支持 Markdown 渲染、数学公式显示和数据可视化功能。 ### 更新内容 对 `D:\wks\web73\views\xuetu\` 目录下所有以 `fibu_` 为前缀的 HTML 页面进行标准化更新： **Head 标签添加内容**: ```html <script type="text/javascript" src="/static/js/d3.711.js"></script> <script type="text/javascript" src="/static/js/page.js"></script> <script type="text/javascript" src="/static/js/marked.min.js"></script> {{template "header_css" .}} ``` **Body 结束标签前添加**: ```html {{template "header_js" .}} ``` ### 更新规则 1. **完整页面更新** - 如果 HTML 页面包含 `<head>` 标签，则进行更新 2. **组件模板跳过** - 如果页面没有 `<head>` 标签（如 `rust_tab.html`），则跳过，因为它们只是其他页面的组件部分 ``` 1. 我希望 `D:\wks\web73\views\xuetu\` 目录，即web73所在的目录可以 作为参数输入，或者能灵活指定， 2. 以 `fibu_` 为前缀的页面，以什么格式为前缀，我也希望可以灵活指定，比如在描述时可以改变为以其他的名称为开头，比如，以llm_为开头，以nlp_为开头 ，希望可以通过以自然语言的方式指定 3. 当我提到"web73页面模板更新"时应该触发该skills ``` ### 使用 ``` web73页面模板更新 请使用/ai/wks/elec/skills/web73-template-updater工具对/ai/wks/web73/views/xuetu目录下以llm_开头的html页面进行更新 ```

https://mp.weixin.qq.com/s/Rrnh3civ6LN5kaWPqYeRtw ## python环境配置 ``` xt@u24:~/app/bin$ ll total 24 drwxrwxr-x 5 xt xt 4096 Mar 9 20:45 ./ drwxrwxr-x 3 xt xt 4096 Mar 9 20:35 ../ drwxr-xr-x 2 xt xt 4096 Dec 23 10:49 micromamba_arm64/ -rwxr-xr-x 1 xt xt 866 Dec 23 11:36 micromamba_setup.sh* drwxr-xr-x 4 xt xt 4096 Dec 23 10:54 micromamba_windows/ drwxr-xr-x 2 xt xt 4096 Dec 23 10:49 micromamba_x86_64/ xt@u24:~/app/bin$ xt@u24:~/app/bin$ ./micromamba_setup.sh ``` ``` export PATH=/home/xt/app/bin:$PATH $ which micromamba /wks/python/bin/micromamba export MAMBA_EXE='/home/xt/app/bin/micromamba'; export MAMBA_ROOT_PREFIX='/python/micromamba'; micromamba shell init --shell bash --root-prefix=$MAMBA_ROOT_PREFIX micromamba create -n py313 python=3.13 ```

### pg #### 安装 pg需要编译，因此需要重新安装 sudo apt install bison flex libreadline-dev sudo apt install -y libicu-dev pkg-config mkdir -p /wks/app/pg/pg17/{data,walback} adduser postgres chown -R postgres:postgres /wks/app/pg su - postgres cd /wks/app/pg wget https://ftp.postgresql.org/pub/source/v17.6/postgresql-17.6.tar.gz tar -xvf postgresql-17.6.tar.gz PGHOME=/wks/app/pg/pg17 PGDATA=$PGHOME/data ARCLOG_PATH=$PGHOME/walback PATH=$PGHOME/bin:$PATH export PGHOME PGDATA ARCLOG_PATH PATH cd /wks/app/pg/postgresql-17.6/ ./configure --prefix=/wks/app/pg/pg17 make make install $ pg_config --version PostgreSQL 17.6 $ which pg_config /wks/app/pg/pg17//bin/pg_config #### 初始化 initdb initdb -D /wks/app/pg/pg17/data -U postgres --encoding=UTF8 --locale=en_US.UTF-8 pg_ctl -D /wks/app/pg/pg17/data -l logfile start psql -U postgres postgres=# \password Enter new password for user "postgres":Book_1234 Enter it again: -- 创建用户 tpf，密码为 Book_1234 CREATE USER tpf WITH PASSWORD 'Book_1234'; -- 创建数据库 db1 CREATE DATABASE db1; -- 将数据库所有权授予 tpf（可选，根据需要） GRANT ALL PRIVILEGES ON DATABASE db1 TO tpf; postgres-# \q $ pg_ctl stop waiting for server to shut down.... done server stopped

## 快捷键 - pg1: sudo docker start u24;sudo docker exec -it u24 su - postgres - pgs1: pg_ctl -D /home/postgres/app/pg17/data -l logfile start - pgs2: /home/postgres/app/pg17/bin/pg_ctl stop ## pg安装 ``` apt update apt install bison flex libicu-dev pkg-config wget sudo vim curl apt install libreadline-dev zlib1g-dev libz-dev git adduser postgres su - postgres mkdir -p ~/app/pg17/{data,walback} cd ~/app wget https://ftp.postgresql.org/pub/source/v17.6/postgresql-17.6.tar.gz tar -xvf postgresql-17.6.tar.gz PGHOME=/home/postgres/app/pg17 PGDATA=$PGHOME/data ARCLOG_PATH=$PGHOME/walback PATH=$PGHOME/bin:$PATH export PGHOME PGDATA ARCLOG_PATH PATH cd ~/app/postgresql-17.6/ ./configure --prefix=/home/postgres/app/pg17 make make install ``` ## pg初始化 ``` initdb pg_ctl -D /home/postgres/app/pg17/data -l logfile start psql -U postgres postgres=# \password Enter new password for user "postgres":Book_1234 Enter it again: postgres-# \q CREATE USER tpf WITH PASSWORD 'Book_1234'; CREATE DATABASE db1; GRANT ALL PRIVILEGES ON DATABASE db1 TO tpf; ``` ## vec插件安装 ``` $ pg_config --version PostgreSQL 17.6 tar -xvf pgvector0.8.1.tar.gz cd pgvector make sudo make install ``` ``` $ psql -U postgres psql (17.6) Type "help" for help. postgres=# CREATE EXTENSION vector; CREATE EXTENSION postgres=# SELECT vector_dims('[1,2,3]'::vector); vector_dims ------------- 3 (1 row) postgres=# SELECT * FROM pg_extension WHERE extname = 'vector'; oid | extname | extowner | extnamespace | extrelocatable | extversion | extconfig | extcond ition -------+---------+----------+--------------+----------------+------------+-----------+-------- ------ 16390 | vector | 10 | 2200 | t | 0.8.1 | | (1 row) ```

``` curl https://sh.rustup.rs -sSf | sh source "$HOME/.cargo/env" $ which rustc /home/xt/.cargo/bin/rustc $ rustc --version rustc 1.92.0 (ded5c06cf 2025-12-08) ``` alias xt1="sudo docker start u24;sudo docker exec -it u24 su - xt"

linux curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh ``` xt@u24:~$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh downloading ironclaw 0.16.1 x86_64-unknown-linux-gnu installing to /home/xt/.cargo/bin ironclaw ironclaw-update everything's installed! 启动pg数据库 postgres@u24:~$ pgs1 pg_ctl: another server might be running; trying to start server anyway waiting for server to start.... done server started xt@u24:~$ ironclaw onboard postgres://postgres:Book_1234@127.0.0.1:5432/db1 Select storage method: [1] OS Keychain (recommended for local installs) [2] Environment variable (for CI/Docker) [3] Skip (disable secrets features) > 2 1 Provider: [1] NEAR AI - multi-model access via NEAR account [2] Anthropic - Claude models (direct API key) [3] OpenAI - GPT models (direct API key) [4] Ollama - local models, no API key needed [5] OpenRouter - 200+ models via single API key [6] OpenAI-compatible - custom endpoint (vLLM, LiteLLM, etc.) > 1 ``` ``` xt@u24:~$ ironclaw onboard ╭─────────────────────────╮ │ IronClaw Setup Wizard │ ╰─────────────────────────╯ Step 1/9: Database Connection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Which database backend would you like to use? Select a database backend: [1] PostgreSQL - production-grade, requires a running server [2] libSQL - embedded SQLite, zero dependencies, optional Turso cloud sync > 1 ℹ Enter your PostgreSQL connection URL. ℹ Format: postgres://user:password@host:port/database Database URL: postgres://tpf:Book_1234@127.0.0.1:5432/db1 ℹ Testing connection... ✗ Connection failed: Database error: pgvector extension not found on your PostgreSQL server. Install it: macOS: brew install pgvector Ubuntu: apt install postgresql-17-pgvector Docker: use the pgvector/pgvector:pg17 image Source: https://github.com/pgvector/pgvector#installation Then restart PostgreSQL and re-run: ironclaw onboard Try again? [Y/n] Y Database URL: postgres://tpf:Book_1234@127.0.0.1:5432/db1 ℹ Testing connection... ✓ Database connection successful Run database migrations? [Y/n] Y ℹ Running migrations... Error: Database error: Migration failed: `error applying migration V1__initial`, `db error` xt@u24:~$ ironclaw onboard ╭─────────────────────────╮ │ IronClaw Setup Wizard │ ╰─────────────────────────╯ Step 1/9: Database Connection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Which database backend would you like to use? Select a database backend: [1] PostgreSQL - production-grade, requires a running server [2] libSQL - embedded SQLite, zero dependencies, optional Turso cloud sync > 1 ℹ Enter your PostgreSQL connection URL. ℹ Format: postgres://user:password@host:port/database Database URL: postgres://postgres:Book_1234@127.0.0.1:5432/db1 ℹ Testing connection... ✓ Database connection successful Run database migrations? [Y/n] Y ℹ Running migrations... ✓ Migrations applied Step 2/9: Security ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Checking OS keychain for existing master key... ℹ The secrets master key encrypts sensitive data like API tokens. ℹ Choose where to store it: Select storage method: [1] OS Keychain (recommended for local installs) [2] Environment variable (for CI/Docker) [3] Skip (disable secrets features) > 1 ℹ Generating master key... Error: Configuration error: Failed to store in keychain: Keychain error: Failed to connect to secret service: no secret service provider or dbus session found xt@u24:~$ ironclaw onboard ╭─────────────────────────╮ │ IronClaw Setup Wizard │ ╰─────────────────────────╯ Step 1/9: Database Connection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Existing database URL: postgres://postgres:****@127.0.0.1:5432/db1 Use this database? [Y/n] Y ✓ Database connection successful Step 2/9: Security ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Checking OS keychain for existing master key... ℹ The secrets master key encrypts sensitive data like API tokens. ℹ Choose where to store it: Select storage method: [1] OS Keychain (recommended for local installs) [2] Environment variable (for CI/Docker) [3] Skip (disable secrets features) > 2 ℹ Generate a key and add it to your environment: export SECRETS_MASTER_KEY=011fa46abd76316f85ad26a614b792edb4b421b1ed52da3004e68d7f86d5d6a8 ℹ Add this to your shell profile or .env file. ✓ Configured for environment variable Step 3/9: Inference Provider ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Select your inference provider: Provider: [1] NEAR AI - multi-model access via NEAR account [2] Anthropic - Claude models (direct API key) [3] OpenAI - GPT models (direct API key) [4] Ollama - local models, no API key needed [5] OpenRouter - 200+ models via single API key [6] OpenAI-compatible - custom endpoint (vLLM, LiteLLM, etc.) > 1 ╔════════════════════════════════════════════════════════════════╗ ║ NEAR AI Authentication ║ ╠════════════════════════════════════════════════════════════════╣ ║ Choose an authentication method: ║ ║ ║ ║ [1] GitHub (requires localhost browser access) ║ ║ [2] Google (requires localhost browser access) ║ ║ [3] NEAR Wallet (coming soon) ║ ║ [4] NEAR AI Cloud API key ║ ║ ║ ╚════════════════════════════════════════════════════════════════╝ Enter choice [1-4]: 2 Opening google authentication... https://private.near.ai/v1/auth/google?frontend_callback=http%3A%2F%2F127.0.0.1%3A9876 (Could not open browser automatically, please copy the URL above) Waiting for authentication... ✓ Authentication successful! ✓ NEAR AI configured Step 4/9: Model Selection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Available models: Select a model: [1] anthropic/claude-opus-4-6 [2] anthropic/claude-sonnet-4-5 [3] black-forest-labs/FLUX.2-klein-4B [4] deepseek-ai/DeepSeek-V3.1 [5] google/gemini-3-pro [6] openai/gpt-5.2 [7] openai/gpt-oss-120b [8] Qwen/Qwen3-30B-A3B-Instruct-2507 [9] Qwen/Qwen3.5-122B-A10B [10] zai-org/GLM-5-FP8 [11] Custom model ID > 4 ✓ Selected deepseek-ai/DeepSeek-V3.1 Step 5/9: Embeddings (Semantic Search) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Embeddings enable semantic search in your workspace memory. Enable semantic search? [Y/n] Y Select embeddings provider: [1] NEAR AI (uses same auth, no extra cost) [2] OpenAI (requires API key) > 2 ℹ OPENAI_API_KEY not set in environment. ℹ Add it to your .env file or environment to enable embeddings. ✓ Embeddings configured for OpenAI Step 6/9: Channel Configuration ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Tunnel Configuration (for webhook endpoints): ℹ A tunnel exposes your local agent to the internet, enabling: ℹ - Instant Telegram message delivery (instead of polling) ℹ - Slack, Discord, GitHub webhooks Configure a tunnel? [y/N] y Select tunnel provider: [1] ngrok - managed tunnel, starts automatically [2] Cloudflare - cloudflared tunnel, starts automatically [3] Tailscale - Tailscale Funnel/Serve, starts automatically [4] Custom - your own tunnel command [5] Static URL - you manage the tunnel yourself > 4 ℹ Enter a shell command to start your tunnel. ℹ Use {port} and {host} as placeholders. ℹ Example: bore local {port} --to bore.pub Tunnel command: date Health check URL (optional): URL pattern (substring to match in stdout) (optional): ✓ Custom tunnel configured. Which channels do you want to enable? (Use arrow keys to navigate, space to toggle, enter to confirm) > [x] CLI/TUI (always enabled) [ ] HTTP webhook [ ] Signal [ ] Discord (will install) [ ] Slack (will install) [ ] Telegram (will install) [ ] Whatsapp (will install) Step 7/9: Extensions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Available tools from the extension registry: ℹ Select which tools to install. You can install more later with: ℹ ironclaw registry install Which tools do you want to install? (Use arrow keys to navigate, space to toggle, enter to confirm) [x] GitHub [manual] - GitHub integration for issues, PRs, repos, and code search > [x] Gmail [oauth] - Read, send, and manage Gmail messages and threads [x] Google Calendar [oauth] - Create, read, update, and delete Google Calendar events [ ] Google Docs [oauth] - Create and edit Google Docs documents [x] Google Drive [oauth] - Upload, download, search, and manage Google Drive files and folders [ ] Google Sheets [oauth] - Read and write Google Sheets spreadsheet data [ ] Google Slides [oauth] - Create and edit Google Slides presentations [x] Slack Tool [oauth] - Your agent uses Slack to post and read messages in your workspace [ ] Telegram Tool [manual] - Your agent uses your Telegram account to read and send messages [x] Web Search [manual] - Search the web using Brave Search API Downloading tool 'GitHub'... ✗ Failed to install GitHub: Source fallback unavailable for 'github' after artifact install failed. Retry artifact download or run from a repository checkout. Downloading tool 'Gmail'... ✗ Failed to install Gmail: Source fallback unavailable for 'gmail' after artifact install failed. Retry artifact download or run from a repository checkout. Downloading tool 'Google Calendar'... ✗ Failed to install Google Calendar: Source fallback unavailable for 'google-calendar' after artifact install failed. Retry artifact download or run from a repository checkout. Downloading tool 'Google Drive'... ✗ Failed to install Google Drive: Source fallback unavailable for 'google-drive' after artifact install failed. Retry artifact download or run from a repository checkout. Downloading tool 'Slack Tool'... ✗ Failed to install Slack Tool: Source fallback unavailable for 'slack-tool' after artifact install failed. Retry artifact download or run from a repository checkout. Downloading tool 'Web Search'... ✗ Failed to install Web Search: Source fallback unavailable for 'web-search' after artifact install failed. Retry artifact download or run from a repository checkout. Step 8/9: Docker Sandbox ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ IronClaw can execute code, run builds, and use tools inside Docker ℹ containers. This keeps your system safe -- commands from the LLM run ℹ in an isolated sandbox with no access to your credentials, limited ℹ filesystem access, and network traffic restricted to an allowlist. ℹ Without Docker, code execution tools (shell, file write) run directly ℹ on your machine with no isolation. Enable Docker sandbox? [y/N] Y ✗ Docker is not installed. ℹ Install Docker Engine: https://docs.docker.com/engine/install/ Retry after installing Docker? [y/N] N ℹ Sandbox disabled. Install Docker and set SANDBOX_ENABLED=true later. Step 9/9: Background Tasks ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Heartbeat runs periodic background tasks (e.g., checking your calendar, ℹ monitoring for notifications, running scheduled workflows). Enable heartbeat? [y/N] Y Check interval in minutes (default: 30): Notify channel on findings (e.g., telegram): ✓ Heartbeat enabled (every 30 minutes) ✓ Configuration saved to database Configuration Summary: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Database: PostgreSQL (configured) Security: environment variable Provider: NEAR AI Model: deepseek-ai/DeepSeek-V3.1 Embeddings: openai (text-embedding-3-small) Tunnel: custom (managed, starts at boot) Channels: - CLI/TUI: enabled Heartbeat: every 30 minutes To start the agent, run: ironclaw To change settings later: ironclaw config set ironclaw onboard xt@u24:~$ ironclaw 2026-03-09T13:35:52.828716Z INFO Starting IronClaw... 2026-03-09T13:35:52.829027Z INFO Loaded configuration for agent: ironclaw 2026-03-09T13:35:52.829297Z INFO LLM backend: nearai 2026-03-09T13:35:52.839191Z INFO PostgreSQL database connected and migrations applied 2026-03-09T13:35:52.840529Z INFO Configuration reloaded from database 2026-03-09T13:35:52.840911Z INFO Loaded session from DB settings 2026-03-09T13:35:52.840944Z INFO Using NEAR AI (Chat Completions API) model=deepseek-ai/DeepSeek-V3.1 base_url=https://private.near.ai auth="session token" 2026-03-09T13:35:52.868284Z INFO LLM provider initialized: deepseek-ai/DeepSeek-V3.1 2026-03-09T13:35:52.868332Z INFO LLM retry wrapper enabled max_retries=3 2026-03-09T13:35:52.874312Z INFO Safety layer initialized 2026-03-09T13:35:52.902066Z INFO Registered 4 built-in tools 2026-03-09T13:35:52.902118Z WARN Embeddings configured but OPENAI_API_KEY not set 2026-03-09T13:35:52.902149Z INFO Registered 4 memory tools 2026-03-09T13:35:52.907516Z INFO Loaded embedded registry catalog (14 extensions, 3 bundles) 2026-03-09T13:35:52.907565Z INFO Loaded registry catalog entries for extension discovery count=14 2026-03-09T13:35:52.934995Z INFO Registered 7 extension management tools 2026-03-09T13:35:52.935061Z INFO Extension manager initialized with in-chat discovery tools 2026-03-09T13:35:52.988053Z INFO Seeded 8 workspace files 2026-03-09T13:35:53.015151Z INFO Registered 4 skill management tools 2026-03-09T13:35:53.015192Z INFO Tool registry initialized with 19 total tools 2026-03-09T13:35:56.954170Z INFO Starting custom tunnel on 127.0.0.1:3000... 2026-03-09T13:35:56.956424Z INFO Tunnel started: http://127.0.0.1:3000 2026-03-09T13:35:56.957136Z WARN Docker is not installed -- sandbox disabled for this session. Install Docker Engine: https://docs.docker.com/engine/install/ 2026-03-09T13:35:56.957207Z INFO REPL mode enabled 2026-03-09T13:35:56.958368Z INFO Lifecycle hooks initialized bundled=1 plugin=0 workspace=0 outbound_webhooks=0 errors=0 2026-03-09T13:35:56.958415Z INFO Registered 6 job management tools 2026-03-09T13:35:56.958888Z INFO Web UI: http://127.0.0.1:3000/ ╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶ ironclaw v0.16.1 model deepseek-ai/DeepSeek-V3.1 via nearai database postgres (connected) tools 25 registered features embeddings (openai) heartbeat (30m) sandbox (docker not installed) routines skills channels repl gateway gateway http://127.0.0.1:3000/?token=f266c8bdda30eda814e22c425686927f080d95f22bfa1338cd77daf6dde0c7a4 tunnel http://127.0.0.1:3000 (custom) ╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶ /help for commands, /quit to exit 2026-03-09T13:35:56.958934Z INFO Registered message tool 2026-03-09T13:35:56.959373Z INFO Started channel: repl › 2026-03-09T13:35:56.960383Z INFO Started channel: gateway 2026-03-09T13:35:56.960415Z INFO Registered 5 routine management tools 2026-03-09T13:35:56.960912Z INFO Starting heartbeat loop with interval 1800s 2026-03-09T13:35:56.961143Z INFO Routines enabled: cron ticker every 15s, max 10 concurrent 2026-03-09T13:35:56.961155Z INFO Agent ironclaw ready and listening 2026-03-09T13:35:57.283585Z INFO Loaded NEAR AI pricing for 29 model(s) ```

以下是 Ironclaw 安装选择的完整指南： | 安装步骤 | 新手推荐 | 说明 | |---------|---------|------| | **Tunnel Configuration** (隧道配置) | **N** (不启用) | 用于将本地服务暴露到公网，接收外部webhook。新手先用轮询模式即可，后续需要再配置 | | **Channels** (通信渠道) | **只选 Telegram** | • CLI/TUI: 必须保留
• Telegram: ✅ 推荐，API开放，文档多，易上手
• 其他(Discord/Slack等): ❌ 不选，配置复杂或国内用不上 | | **Tools** (工具集成) | **只选 Web Search** | • Web Search: ✅ 推荐，国内可用，配置简单
• Telegram Tool: ⭕ 可选，如需agent主动发消息
• 谷歌全家桶: ❌ 不选，需要翻墙
• GitHub: ❌ 不选，国内访问不稳定 | | **Docker Sandbox** (Docker沙箱) | **Y** (启用) | • ✅ 启用：安全隔离，防止AI代码破坏系统
• ❌ 不启用：代码直接运行，有安全风险 | ## 最终配置清单： ``` 已选配置： ├── Channels: Telegram（用于接收和回复消息） ├── Tools: Web Search（用于联网搜索） ├── Docker: 启用（安全隔离） └── Tunnel: 不启用（先用轮询模式） ``` 这样配置可以让新手： 1. ✅ 快速上手，配置最少 2. ✅ 国内可用，不需要翻墙 3. ✅ 安全性有保障 4. ✅ 后续扩展灵活

pg_ctl -D /wks/app/pg/pg17/data -l logfile start xt@qisan:/ai/wks/rust/ironclaw/ironclaw-staging/target/release$ ./ironclaw config get llm_backend xt@qisan:/ai/wks/rust/ironclaw/ironclaw-staging/target/release$ ./ironclaw - 你能做什么？ 我能做很多事情！以下是我的主要能力： 🔧 工具与自动化 任务管理：创建、监控、取消多步骤任务 HTTP请求：访问外部API，下载文件 数据处理：JSON解析、查询、转换 时间操作：时区转换、时间计算、定时任务 🖼️ 图像处理 根据文字描述生成图像 编辑现有图像 分析图像内容（识别物体、场景等） 📡 通信与集成 发送消息到各种平台（Telegram、Slack等） 安装和管理扩展（通道、工具、MCP服务器） 连接到外部服务（API集成） 🧠 记忆与上下文 持久化存储重要信息 搜索过去的对话和决策 维护每日日志和长期记忆 ⚙️ 系统管理 创建定时/事件驱动的例行任务 安装和管理技能（ClawHub技能库） 扩展系统功能（搜索和安装新工具） 📁 文件操作 读写工作空间文件 管理记忆数据库 🎯 实际应用场景 自动化日常工作流程 数据收集和处理 图像创作和编辑 消息通知和提醒 外部服务集成 信息记忆和检索 你有什么具体想做的吗？我可以根据你的需求提供更详细的指导或直接帮你完成！

sudo su - postgres pg_ctl -D /wks/app/pg/pg17/data -l logfile start cd /ai/wks/rust/ironclaw/ironclaw-staging/target/release ./ironclaw xt@qisan:/ai/wks/rust/ironclaw/ironclaw-staging/target/release$ ./ironclaw

``` $ cat /home/xt/.ironclaw/.env DATABASE_BACKEND="postgres" DATABASE_URL="postgres://postgres:Book_1234@127.0.0.1:5432/db1" LLM_BACKEND="deepseek" DEEPSEEK_MODEL="deepseek-chat" DEEPSEEK_API_KEY="sk-5369c5...432" ONBOARD_COMPLETED="true" ``` $ ./ironclaw Error: Configuration error: Missing required setting 'LLM_BASE_URL'. Set LLM_BASE_URL when LLM_BACKEND=glm. Run 'ironclaw onboard' to configure, or set the required environment variables. $ ./ironclaw onboard ╭─────────────────────────╮ │ IronClaw Setup Wizard │ ╰─────────────────────────╯ Step 1/9: Database Connection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Existing database URL: postgres://postgres:****@127.0.0.1:5432/db1 Use this database? [Y/n]