1. 刚装完 OpenClaw，为什么第一件事是搞懂 openclaw.json 和 workspace
OpenClaw 是一个把大模型能力落到本地文件系统上的 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/api，apiKey用环境变量引用，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，删掉旧的那个。
接着启动 gateway：
openclaw 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_PROFILE=prod，workspace 路径会变成~/.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，出问题能快速回滚。
