OpenClaw02_基础知识手册：openclaw.json 与 workspace 配置入门

1. 刚装完 OpenClaw为什么第一件事是搞懂 openclaw.json 和 workspaceOpenClaw 是一个把大模型能力落到本地文件系统上的 Agent 运行时。它和你在网页里用的聊天框最大的区别在于它能读写你机器上的文件、执行命令、调用技能包而这些行为全部围绕两个东西展开——openclaw.json和workspace目录。前者决定「Agent 能做什么、用哪个模型、走哪个网关」后者决定「Agent 在哪儿干活、能碰到哪些文件」。这两个概念没理顺后面装 skills、配 gateway、接第三方模型都会卡住。这篇面向刚接触 OpenClaw 的开发者把openclaw.json的核心字段、workspace的目录结构、skills与gateway的协作关系讲清楚并给出一份可以直接复制的最小配置再演示启动后怎么验证 workspace 加载成功、gateway 是否连通。你跟着敲一遍基本就能独立跑起第一个 Agent。先说清楚三个词的含义避免后面混淆openclaw.json是主配置文件采用 JSON5 格式支持注释和$include指令。它管的是 Agent 默认行为、Provider模型服务商、工具权限策略、gateway 监听端口这些全局设定。workspace是 Agent 的工作区目录默认在~/.openclaw/workspace。所有文件读写工具默认只在这个目录里操作。注意它不是硬沙箱除非你显式开启sandbox.enabled否则 Agent 仍可能通过绝对路径访问主机其他位置。skills是技能包目录每个技能是一个带SKILL.md的子目录从 ClawHub 安装或手动 clone 进来。gateway是本地网关进程负责接收请求、调度 Agent、把工具调用结果回传默认监听127.0.0.1:18789。适合谁看刚装完 OpenClaw、准备接自己的模型服务、想搞清楚配置文件每个字段含义的开发者。如果你还没装先按官方文档装好再回来对着这篇改配置。2. TaoToken 前置准备给 OpenClaw 配一个稳定的模型入口OpenClaw 本身不带模型它需要你提供一个兼容的 API 入口。TaoToken 提供的就是这样一个入口支持对话模型和编码模型OpenClaw 里通过providers节引用即可。这一步做完你的 Agent 才有「大脑」。先拿到两样东西API Key 和 Base URL。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制保存。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数直接填进配置。如果你打算长期跑编码类 Agent可以顺带看下 Coding Plan它针对高频代码生成场景做了额度优化只是偶尔验证模型连通性的话用模型对话页面手动测一次也行。这两个入口按需选不用都开。关键点在于OpenClaw 的providers节里apiKey建议写成$TAOTOKEN_API_KEY这种环境变量引用形式而不是把明文 Key 写进openclaw.json。原因很直接——配置文件可能被备份、被同步、被误提交环境变量则留在 shell 里。设置方式export TAOTOKEN_API_KEY你的Key echo export TAOTOKEN_API_KEY你的Key ~/.bashrc source ~/.bashrc如果你用 zsh把~/.bashrc换成~/.zshrc。设完用echo $TAOTOKEN_API_KEY确认能打印出来。这里有个容易踩的坑OpenClaw 读环境变量是在 gateway 启动时进行的如果你先启动了 gateway 再export配置不会生效。顺序必须是先设环境变量再openclaw gateway restart。另外providers节里每个 provider 都要指定defaultModel。TaoToken 的模型 ID 以你控制台实际展示的为准填错会报模型不存在。建议先在模型对话页面确认模型 ID 拼写再写进配置。3. 可复制的 openclaw.json 最小配置与 workspace 目录结构这一节给出一份能直接跑的最小配置路径和字段名与 OpenClaw 官方保持一致。先确认你的配置目录ls -la ~/.openclaw/正常应该看到openclaw.json、agents/、skills/、workspace/、logs/这些。如果只有旧版目录~/openclaw/说明你装的是老版本路径要相应替换。把下面这份配置写入~/.openclaw/openclaw.json{ // Agent 默认配置 agent: { workspace: ~/.openclaw/workspace, skipBootstrap: false, sandbox: { enabled: false, workspaceAccess: rw } }, // Provider 配置这里接 TaoToken providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: $TAOTOKEN_API_KEY, defaultModel: 你的模型ID } }, // 工具策略 tools: { policy: default-deny, allowedTools: [Read, Write, Glob], blockedTools: [Bash(sudo:*)] }, // 网关配置 gateway: { port: 18789, bind: 127.0.0.1, auth: { enabled: false } } }几个字段逐个说明。agent.workspace指定工作区路径支持~展开。agent.skipBootstrap为false时首次启动会自动创建引导文件IDENTITY.md、SOUL.md 等建议保持false省得手动建。agent.sandbox.enabled为false表示不启用隔离Agent 能访问主机文件系统生产环境建议改成true并把workspaceAccess设为rw或ro。providers.taotoken.baseUrl填https://taotoken.net/apiapiKey用环境变量引用defaultModel填你在控制台确认过的模型 ID。tools.policy设为default-deny表示默认拒绝所有工具只放行allowedTools里列出的。这是最保守的策略适合刚上手时用。gateway.bind默认127.0.0.1只允许本机访问别改成0.0.0.0除非你清楚暴露风险。workspace 目录结构长这样~/.openclaw/workspace/ ├── IDENTITY.md # Agent 身份定义 ├── SOUL.md # 人格与语气 ├── AGENTS.md # 操作规则 ├── USER.md # 用户画像 ├── HEARTBEAT.md # 定时自检任务 ├── MEMORY.md # 持久化记忆 └── TOOLS.md # 工具使用指南这些文件在skipBootstrap: false时首次启动自动生成。SOUL.md控制 Agent 说话风格想让它更简洁或更啰嗦改这里最快。AGENTS.md控制工具使用策略比如是否允许它主动调用子 Agent。skills 目录和 workspace 是平级的~/.openclaw/skills/ ├── weather/ │ ├── SKILL.md │ ├── scripts/ │ └── assets/ └── github/ └── SKILL.md每个技能必须有SKILL.md里面是 YAML frontmatter 加 Markdown 正文。加载优先级从高到低是工作区技能、用户全局技能、内置捆绑技能。也就是说同名技能放在 workspace 里会覆盖全局的。gateway 和 skills 的协作关系是这样的gateway 启动时扫描 skills 目录把每个技能的元信息注册进工具表Agent 运行时根据tools.policy判断某个技能调用是否放行放行后 gateway 执行技能脚本把结果回传给模型。所以 skills 装好了但 gateway 没重启新技能不会生效。4. 启动后验证 workspace 加载与 gateway 连通性配置写完先做语法检查再启动。OpenClaw 用的是 JSON5普通 JSON 校验器可能误报用官方命令最稳openclaw doctor这个命令会检测配置语法、重复 workspace、缺失字段等问题。如果输出里有workspace: OK和providers: OK说明基础配置没问题。如果报duplicate workspace说明你同时存在~/.openclaw/workspace和~/openclaw/workspace删掉旧的那个。接着启动 gatewayopenclaw gateway start预期输出类似Gateway starting on 127.0.0.1:18789 Loading workspace: /Users/you/.openclaw/workspace Registered skills: weather, github Gateway ready.看到Gateway ready.就说明起来了。如果卡在Loading workspace不动多半是 workspace 路径不存在或权限不对用ls -la ~/.openclaw/workspace确认。验证 gateway 连通性用 curl 打健康检查端点curl -s http://127.0.0.1:18789/health预期返回{status:ok,workspace:/Users/you/.openclaw/workspace,skills:2}skills数量和你实际装的对得上就对了。如果返回connection refused说明 gateway 没起来回去看~/.openclaw/logs/gateway.log。再验证模型连通性发一个最小请求curl -s http://127.0.0.1:18789/v1/chat \ -H Content-Type: application/json \ -d {model:你的模型ID,messages:[{role:user,content:ping}]}预期返回里包含模型回复内容。如果返回401说明TAOTOKEN_API_KEY没读到或 Key 无效如果返回model not found说明defaultModel填错了。最后确认 workspace 真的被 Agent 用上了。在 workspace 里放一个测试文件echo hello openclaw ~/.openclaw/workspace/test.txt然后通过 gateway 发一个读文件请求或者直接在 Agent 会话里让它读test.txt。能读到内容说明 workspace 加载链路完整。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一节对照真实报错逐个给排查路径。401 Unauthorized。最常见的原因是环境变量没生效。先确认echo $TAOTOKEN_API_KEY有输出再确认 gateway 是在设完环境变量之后启动的。如果都对了还报 401检查 Key 是否过期或被撤销去控制台重新生成一个。还有一种情况是apiKey字段写成了明文但带了多余空格JSON5 里字符串前后的空格会被保留用$TAOTOKEN_API_KEY引用形式可以避免。local proxy failed。这个报错通常出现在 gateway 尝试转发请求但目标地址不可达时。检查providers.taotoken.baseUrl是否写成https://taotoken.net/api注意结尾不要多加斜杠。如果本机有网络策略限制确认127.0.0.1:18789没被占用lsof -i :18789。被占用了就改gateway.port。reading choices 相关报错。这类错误一般出现在模型返回结构不符合预期时比如返回体里没有choices字段。先确认defaultModel是对话模型而不是嵌入模型。如果模型 ID 正确用 curl 直接打 TaoToken 的接口确认返回结构排除是 gateway 解析问题还是上游返回问题。OAuth 相关报错。如果你在providers里配了需要 OAuth 的 provider但没走完授权流程会报 token 缺失。OpenClaw 的凭证存在~/.openclaw/credentials/权限建议chmod 700。OAuth 流程走完后 token 会写进这个目录。如果报OAuth token expired重新走一遍授权即可。skills 不生效。装完技能后必须openclaw gateway restart否则 gateway 不会重新扫描 skills 目录。另外确认技能目录下有SKILL.md缺这个文件技能不会被注册。workspace 路径不对。如果你设了OPENCLAW_PROFILEprodworkspace 路径会变成~/.openclaw/workspace-prod而不是默认的workspace。用openclaw doctor能看到实际生效的路径。排查顺序建议先openclaw doctor看配置再openclaw status看进程最后tail -f ~/.openclaw/logs/gateway.log看实时日志。大部分问题在日志里都有明确提示。6. 把配置跑通之后下一步做什么配置跑通只是起点。接下来你可以做三件事按难度递增。第一改~/.openclaw/workspace/SOUL.md调整 Agent 的性格和语气。这是成本最低、体感最明显的改动。改完不用重启 gateway下次会话就生效。第二装一个技能试试。从 ClawHub 找一个你用得上的比如天气查询或 GitHub 操作装完重启 gateway然后在会话里让它调用。这一步能帮你理解 skills 和 gateway 的协作链路。第三把tools.policy从default-deny逐步放开。先加Bash但用blockedTools挡住危险命令观察 Agent 的行为再决定要不要开沙箱。生产环境建议开sandbox.enabled把workspaceAccess设成ro或rw按需选。如果你打算长期跑编码类 Agent去 TaoToken 控制台看下 Coding Plan 的额度方案比按次调用更划算。需要新建 Key 或管理多个项目的 Key在 API Keys 页面操作。接入过程中遇到配置问题接入文档里有各字段的完整说明。想先手动验证模型返回是否正常用模型对话页面发一条消息最快。配置文件建议纳入版本管理但credentials/和exec-approvals.json要加进.gitignore。openclaw.json本身不含明文密钥因为用了环境变量引用可以安全提交。定期备份配置cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.manual.bak出问题能快速回滚。