1. IronClaw 首次安装到底卡在哪从零跑通统一 Key 通道的真实路径IronClaw 是一个安全、私密、可自我扩展的个人 AI 助手所有数据本地加密存储工具跑在 WASM 沙盒里支持 REPL、HTTP、Telegram、Slack、Web 网关多渠道接入。它适合谁适合刚拿到项目、想在自己机器上快速跑通第一个示例的新手也适合需要把多个模型供应商收敛到一个 Key 通道的开发者。IronClaw 安装教程网上一搜一大把但真正让人卡住的往往不是编译而是模型通道配置——默认的 NEAR AI 认证在某些网络环境下会转圈换成 OpenRouter 又要单独管理 Key多套 Key 散落在不同配置文件里排查起来非常痛苦。我自己第一次装 IronClaw 时PostgreSQL 和 pgvector 都顺利过了ironclaw onboard走到模型认证那一步反复失败终端只给一个模糊的会话错误。后来把模型后端切到统一 Key 通道问题才彻底消失。这篇 IronClaw 安装教程就按“环境准备 → 依赖安装 → 统一 Key 配置 → 启动自检 → 报错排查”的顺序走一遍目标是一次安装即跑通首个示例。先明确 IronClaw 的安装骨架它依赖 Rust 编译环境如果用预编译包可跳过、PostgreSQL 15 和 pgvector 扩展配置目录在~/.ironclaw/Windows 是C:\Users\你的用户名\.ironclaw\核心文件是.env、settings.json、session.json。模型配置走环境变量支持LLM_BACKEND、LLM_BASE_URL、LLM_API_KEY、LLM_MODEL这一组。理解了这个结构后面所有操作都是围绕这几个文件和环境变量展开的。安装前你需要准备的东西不多一台能跑 PostgreSQL 的机器4GB 内存起步推荐 8GB、一个可用的模型 API Key、以及大约 20 分钟。Windows 用户建议用 PowerShell 管理员模式macOS 和 Linux 用户用默认终端即可。下面进入正式步骤。2. TaoToken 统一 Key 通道前置准备一个 Key 管住所有模型后端在动手改 IronClaw 配置之前先把统一 Key 通道准备好。TaoToken 的作用是把多个模型供应商的调用收敛到一个 Base URL 和一个 API Key 上IronClaw 只需要认这一个通道不用为每个模型单独配 Key。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。第一步拿到 API Key。打开控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建一个新的 Key。创建时给它起个能认出来的名字比如ironclaw-local方便以后在 IronClaw 的.env里对应。Key 只在创建时完整显示一次复制后先存到临时文本里等会儿要写进配置文件。第二步确认你要用的模型 ID。IronClaw 的LLM_MODEL字段需要填具体模型标识不同供应商命名不一样。你可以先在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 里试跑一下确认这个模型能正常返回再把它写进 IronClaw 配置。这一步很关键因为 IronClaw 启动时如果模型 ID 写错报错信息不会直接告诉你“模型不存在”而是给一个解析失败容易误判成网络问题。第三步理解 IronClaw 的模型后端类型。IronClaw 支持openai_compatible、anthropic、ollama等几种LLM_BACKEND。统一 Key 通道走的是 OpenAI 兼容协议所以LLM_BACKEND填openai_compatibleLLM_BASE_URL填https://taotoken.net/apiLLM_API_KEY填你刚创建的 KeyLLM_MODEL填你在对话页验证过的模型 ID。这四个字段凑齐IronClaw 就能通过统一通道调用模型。如果你后续要做长期编码或 Agent 类任务可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对高频调用场景做了额度优化。不过首次安装跑通示例用普通 API Key 就够了不用一上来就上套餐。这里有个容易忽略的点IronClaw 的.env文件里环境变量名是大小写敏感的。LLM_BASE_URL不能写成llm_base_url否则 IronClaw 读不到会回退到默认的 NEAR AI 后端然后你就看到认证失败的报错。我踩过这个坑排查了半小时才发现是大小写问题。3. 可复制配置IronClaw 的 .env 与 settings.json 完整片段这一节给出可以直接复制的配置片段。IronClaw 的配置分两层.env管环境变量模型通道、数据库连接settings.json管用户偏好界面、工具开关。首次安装重点改.env。先看.env文件的完整内容。路径在~/.ironclaw/.envWindows 是C:\Users\你的用户名\.ironclaw\.env。如果文件不存在手动创建# ~/.ironclaw/.env # 数据库连接 DATABASE_URLpostgres://postgres:你的密码localhost:5432/ironclaw # 模型后端统一 Key 通道走 OpenAI 兼容协议 LLM_BACKENDopenai_compatible LLM_BASE_URLhttps://taotoken.net/api LLM_API_KEYsk-你的TaoToken密钥 LLM_MODEL你的模型ID # 可选调试日志 RUST_LOGironclawdebug四个模型相关字段必须同时存在缺一个 IronClaw 就会回退默认后端。LLM_BASE_URL结尾不要加/v1IronClaw 内部会自己拼接路径加了反而会变成/v1/v1/chat/completions这种错误地址。再看settings.json。这个文件管的是非敏感配置首次安装可以保持默认但建议确认几个字段{ gateway: { enabled: false, port: 3001, auth_token: }, tools: { sandbox: true, whitelist_endpoints: [] }, session: { encryption: system_keyring } }gateway.enabled默认false首次跑通 REPL 不用开。tools.sandbox保持true这是 IronClaw 的安全设计工具在 WASM 沙盒里跑。session.encryption在 macOS 上是keychainLinux 上是gnome_keyring或kde_walletWindows 上是credential_manageronboard向导会自动检测一般不用手改。如果你用的是 Windows环境变量也可以走系统级设置但.env文件优先级更高建议统一写在.env里避免两处冲突。macOS 和 Linux 用户注意.env文件权限建议chmod 600 ~/.ironclaw/.env因为里面有 API Key。配置写完后先别急着启动 IronClaw用一条命令验证环境变量能被正确读取cd ~/.ironclaw cat .env | grep LLM_输出应该能看到你写的四行LLM_开头的配置。如果少了哪行说明文件没保存成功或者路径不对。4. 启动自检与验证请求确认统一 Key 通道真的通了配置写完进入验证环节。IronClaw 提供了ironclaw doctor做系统诊断先跑这个ironclaw doctor正常输出会逐项检查数据库连接、pgvector 扩展、模型通道、密钥环。重点看模型通道那一项如果显示LLM backend: openai_compatible且Base URL: https://taotoken.net/api说明配置被正确读取。如果显示NEAR AI说明.env没生效回去检查文件路径和变量名大小写。接着启动 REPL 做真实请求验证ironclaw启动后界面是Welcome to IronClaw! Type your message and press Enter to chat. Type /help for available commands. You:输入一句简单的话比如“你好请回复 OK”。如果统一 Key 通道配置正确几秒内会返回模型响应。第一次请求可能会慢一点因为要建立连接和加载会话。如果想更精确地验证通道可以在 REPL 里用/status命令You: /status输出会显示当前模型后端、模型 ID、会话状态。确认Model字段是你配置的模型 IDBackend是openai_compatible。再做一个带调试日志的启动观察请求细节RUST_LOGironclawdebug ironclaw在调试日志里搜索llm或request关键字能看到实际发出的请求地址。正常应该是https://taotoken.net/api/chat/completions这类路径。如果看到请求发往private.near.ai说明配置回退了回到第 3 节检查.env。验证通过后你可以试着让 IronClaw 调用一个工具比如问它“现在几点”看它是否能触发工具调用并返回结果。这一步能验证沙盒和工具注册表是否正常。如果工具调用报错但普通对话正常问题在工具配置而非模型通道分开排查。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错逐个拆解。IronClaw 安装教程里最容易翻车的就是这几个错误。报错一401 UnauthorizedError: LLM request failed: 401 Unauthorized原因通常是 API Key 写错或没生效。检查三步第一.env里的LLM_API_KEY是否完整复制有没有多余空格第二Key 是否已过期或被删除去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认状态第三LLM_BACKEND是否真的是openai_compatible如果写成anthropic但用的是 OpenAI 兼容 Key也会 401。报错二local proxy failedError: local proxy failed: connection refused这个报错和 IronClaw 本身无关通常是本机网络环境或端口占用导致。检查 PostgreSQL 是否在 5432 端口运行用sudo systemctl status postgresqlLinux或brew services listmacOS确认。如果数据库正常检查是否有其他程序占用了 IronClaw 要用的端口。注意不要尝试用任何网络代理工具去“解决”这个报错IronClaw 的模型请求走的是标准 HTTPS统一 Key 通道本身不需要额外代理配置。报错三error reading choicesError: error reading choices: unexpected end of JSON input这个报错说明请求发出去了但返回的响应体不是预期格式。常见原因是LLM_BASE_URL写错比如多加了/v1或者少了/api。正确写法是https://taotoken.net/api不要带尾部斜杠。另一个原因是模型 ID 不存在通道返回了错误页而不是 JSON。回到模型对话页确认模型 ID 拼写。报错四OAuth 认证失败Error: OAuth authentication failed: session expired这个报错只在用 NEAR AI 默认后端时出现。如果你已经切到统一 Key 通道不应该看到这个。如果看到了说明.env没被读取IronClaw 回退到了默认后端。检查.env文件是否在~/.ironclaw/目录下文件名是否是.env不是.env.txt以及LLM_BACKEND是否设置正确。报错五数据库连接失败Error: failed to connect to database: password authentication failed检查DATABASE_URL里的密码是否正确。如果 PostgreSQL 没设密码DATABASE_URL可以写成postgres://postgreslocalhost:5432/ironclaw去掉密码部分。Windows 用户注意密码里如果有特殊字符需要 URL 编码。排查完这些如果还有问题用ironclaw doctor的输出对照它会给出更具体的失败项。大部分首次安装的问题都集中在模型通道配置和数据库连接这两块把这两块理顺IronClaw 就能稳定跑起来。6. 跑通之后把统一 Key 通道用顺手的几个实操建议首个示例跑通后你可能会想接更多模型或者开 Web 网关。这里给几个实操建议。切换模型时只改.env里的LLM_MODEL一行然后重启 IronClaw 即可不用动其他配置。统一 Key 通道的好处就在这里换模型不用换 Key、不用换 Base URL。你可以准备几个常用模型 ID需要时快速切换。开 Web 网关的话在.env里加GATEWAY_ENABLEDtrue GATEWAY_PORT3001 GATEWAY_AUTH_TOKEN你自定义的token然后访问http://localhost:3001。注意GATEWAY_AUTH_TOKEN要设一个足够复杂的值因为网关会暴露到本机网络。如果你要做长期编码或 Agent 任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对高频调用做了优化。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例IronClaw 之外的项目也能复用同一个 Key。最后提醒一点.env文件里有 API Key不要提交到 Git 仓库。如果你把 IronClaw 配置目录做版本管理记得把.env加进.gitignore。备份配置时用cp -r ~/.ironclaw ~/.ironclaw-backup但备份文件也要注意权限。跑通第一个示例后你可以试着让 IronClaw 帮你做点实际的事比如整理一段文本、查一个本地文件、或者调用一个已安装的工具。从简单任务开始逐步熟悉它的工具调用和沙盒机制比一上来就配复杂工作流要稳得多。