1. 为什么要在 Linux 上折腾 openclawopenclaw 是一个开源的 AI Agent 工具跑起来之后你能在终端里跟它对话、让它读写文件、执行命令、记住上下文还能通过 Web UI 在浏览器里操作。它适合谁适合那些不想被某个闭源客户端绑死、想自己掌控 Agent 运行环境的人尤其是手上有一台 Linux 机器本地虚拟机、云主机、家里的旧笔记本都行的开发者。但第一次接触 openclaw 的人大概率会卡在三个地方一是安装完不知道初始化该选什么二是初始化跑通了但 Web UI 一直报认证错误三是模型通道不知道怎么接。我试过一遍完整流程把踩过的坑都记下来这篇就按「安装 → 初始化 → 配置文件骨架 → Web UI 验证 → 报错排查」的顺序走一遍目标是让你一次跑通。本文用 TaoToken 作为统一的模型 API 通道一个 Key 就能对接多种模型省去在 openclaw 里反复切换供应商配置的麻烦。下面所有命令都可以直接复制环境是 Ubuntu/Debian 系的 Linux其他发行版把包管理命令换掉即可。2. 环境准备与 openclaw 安装openclaw 依赖 Node.js官方推荐 22.x。先确认你的机器上有没有 Nodenode --version npm --version如果版本低于 20或者根本没装用 NodeSource 的脚本装 22.xcurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs装完再验证一次正常会输出类似v22.22.0的版本号。这一步别跳过Node 版本太低会导致 openclaw 安装后启动直接报语法错误。接着全局安装 openclawnpm install -g openclawlatest openclaw --versionopenclaw --version能打印出版本号比如2026.2.25就说明安装成功了。如果提示command not found检查一下 npm 的全局 bin 目录有没有在 PATH 里npm config get prefix把输出的路径加上/bin追加到~/.bashrc的 PATH 里然后source ~/.bashrc。注意不要用sudo npm install -g否则全局包会装到 root 目录下普通用户调用时容易出权限问题。如果之前用 sudo 装过先sudo npm uninstall -g openclaw再重装。3. 初始化 openclaw 与配置文件骨架安装完成后执行初始化命令openclaw onboard --install-daemon--install-daemon会把 openclaw 注册成一个后台服务这样关掉终端它也能继续跑。初始化过程是交互式的会依次问你几个问题下面按顺序说明每个选项该怎么选。第一步会让你选启动方式为了快速跑通选QuickStart。接着选模型提供商这里先随便选一个能快速验证流程的比如 Qwen因为后面我们会用 TaoToken 统一接管模型通道这一步只是让初始化流程能走完。接下来会问渠道配置、skills 配置、各种第三方 API KeyGoogle Places、Gemini、Notion、ElevenLabs 等这些全部跳过或选否。它们对应的是地理位置查询、图像生成、笔记同步、语音合成等扩展能力不在本次跑通范围内选了反而会因为缺少对应账号而卡住。Hooks 那一步建议勾选session-memory作用是让 Agent 记住之前的对话上下文关掉终端再打开还能接着聊。最后问你用什么方式完成收尾配置选TUI终端界面会进入一个交互式配置界面按提示把机器人名字、基础设定填一下就行。初始化结束后openclaw 会在用户目录下生成配置文件。核心文件有两个ls -la ~/.openclaw/你会看到openclaw.json主配置和可能的config.toml。主配置的结构大致如下你可以用编辑器打开对照{ agent: { name: my-claw, memory: true }, model: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_Key, model: claude-sonnet-4-20250514 }, webui: { enabled: true, port: 18789 } }如果你更习惯 TOML 格式等价的config.toml骨架是这样[agent] name my-claw memory true [model] provider taotoken base_url https://taotoken.net/api api_key 你的_TaoToken_Key model claude-sonnet-4-20250514 [webui] enabled true port 18789两个文件保留一个即可openclaw 会优先读openclaw.json。改完配置后需要重启服务生效openclaw restart4. 接入 TaoToken 统一 Keyopenclaw 默认的模型通道需要你分别配置各家供应商的 Key切换模型时还得改配置。用 TaoToken 的好处是一个 Key 走统一 API 通道换模型只改model字段就行。先去 TaoToken 控制台创建一个 API Key。打开 https://taotoken.net/api-keys 登录后点创建复制生成的 Key形如sk-开头的一串字符。这个 Key 只显示一次记得存好。拿到 Key 之后把它填进上面配置文件的apiKey字段。baseUrl 固定填https://taotoken.net/api不要加多余的路径后缀。模型名按你实际想用的填TaoToken 支持的模型列表可以在文档里查https://taotoken.net/doc 。配置改完后用一条命令快速验证 Key 和通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的_TaoToken_Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 说一句你好}] }如果返回的 JSON 里有choices字段和正常的中文回复说明 Key 和通道都没问题。如果返回 401检查 Key 有没有复制完整返回 404检查 baseUrl 有没有写错。提示TaoToken 的 Key 建议放在环境变量里而不是硬编码进配置文件比如export TAOTOKEN_API_KEYsk-xxx然后在配置里引用${TAOTOKEN_API_KEY}。这样配置文件分享出去也不会泄露 Key。5. 启动服务并验证 Web UI配置就绪后启动 openclawopenclaw start或者如果你装了 daemon用系统服务方式启动sudo systemctl start openclaw sudo systemctl status openclaw服务起来后Web UI 默认监听 18789 端口。先在服务器本地验证端口有没有通curl -I http://127.0.0.1:18789/返回 200 或 302 都算正常。如果你是在远程服务器上跑需要用 SSH 端口转发把端口映射到本地ssh -L 18789:127.0.0.1:18789 你的用户名服务器IP然后在本地浏览器打开http://127.0.0.1:18789/。这里就是最容易踩坑的地方TUI 里配置成功了Web UI 却一直报认证错误。原因是TUI 和 Web UI 用的是两套完全独立的认证系统TUI 的登录状态不会自动同步到 Web UI。解决办法是把 token 手动补到 Web UI 的 URL 上。先从配置文件里取出 tokencat ~/.openclaw/openclaw.json | grep -o token: [^]*会输出类似token: 7da3f004ff2a1e700f229a87fb5ea12c150b37d58199295f的内容把引号里的那串字符复制出来。然后在浏览器地址栏这样访问http://127.0.0.1:18789/?token7da3f004ff2a1e700f229a87fb5ea12c150b37d58199295f如果访问根路径会自动跳转导致 token 参数丢失就用把参数拼在跳转后的地址后面。带上 token 之后页面就能正常加载之前在 TUI 里的聊天记录也会同步过来。6. 常见报错与排查清单跑这个流程时我遇到过几个典型问题整理成排查清单你按顺序对一遍基本能定位。报错一openclaw: command not foundnpm 全局 bin 目录不在 PATH 里。执行npm config get prefix拿到路径把路径/bin加进~/.bashrcsource一下。报错二启动后端口 18789 被占用用lsof -i:18789或ss -tlnp | grep 18789查是哪个进程占着杀掉或者改配置文件里的webui.port换一个端口。报错三Web UI 打开是白屏或一直转圈先看浏览器控制台有没有报错再看 openclaw 的日志openclaw logs --tail 50常见原因是前端资源没加载出来多半是端口转发没配对或者浏览器缓存了旧的认证状态清一下缓存重试。报错四模型请求返回 401 或 403TaoToken 的 Key 无效或过期。重新去 https://taotoken.net/api-keys 生成一个替换配置文件里的apiKey然后openclaw restart。报错五TUI 能聊Web UI 报 unauthorized就是前面说的认证不一致问题把 token 拼到 URL 上即可。如果 token 拼了还是不行检查配置文件里webui.enabled是不是true以及 token 有没有复制完整别漏字符。报错六session-memory不生效重启后上下文丢失确认配置文件里agent.memory是true并且~/.openclaw/目录有写权限。如果目录属主是 root之前用 sudo 装过改成当前用户sudo chown -R $USER:$USER ~/.openclaw/。排查完这些openclaw 在 Linux 上从安装到 Web UI 可用的链路就算完整跑通了。后面想换模型只改配置文件里的model字段Key 和通道都不用动这是用 TaoToken 统一接入最省事的地方。