OpenClaw部署实战：从零配置Ubuntu服务器到接入AI模型的全流程指南

还是有不少朋友在问如何部署 OpenClaw（俗称“龙虾”），以及如何接入 AIGoCode 这类中转 API。为了解答这些问题，我特意准备了一台全新的服务器，从头到尾重新走了一遍完整的部署流程，并把每一步都截图记录下来。流程中的关键步骤和容易踩坑的地方都做了标记。核心流程可以归纳为六个主要步骤，跟着操作就能顺利搞定。

准备工作

开始部署前，请确保你的环境满足以下条件：

• 一台全新的 Ubuntu/Debian 服务器（推荐 Ubuntu 22.04 或更高版本）。
• 服务器已安装 Git。如果没有，可以使用 sudo apt update && sudo apt install -y git 命令安装。
  
• 服务器已安装 Node.js v22 或更高版本。可以通过官方提供的一键脚本安装：curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt-get install -y nodejs。
  
• 拥有一个 aigocode.com 账号，并获取到 API Key（格式为 sk-xxx）。
• 拥有一个 Telegram 账号。

第一步：安装 OpenClaw

在服务器终端执行以下命令，进行全局安装：

sudo npm install -g openclaw

安装过程可能会看到一些关于过时依赖包的警告，这通常是正常的。看到安装完成的提示后，核心程序就已就位。

第二步：申请 Telegram 机器人

在 Telegram 应用中搜索 @BotFather（请认准带有蓝色官方认证标记的账号），然后按以下步骤操作：

1. 向 BotFather 发送 /newbot 指令。
   
2. 根据提示为你的机器人起一个昵称（支持中文，后续可以修改）。
3. 设置一个唯一的用户名，必须以 bot 结尾，例如 my_ai_bot。
   
4. 创建成功后，BotFather 会返回一串 Bot Token（格式类似 123456789:ABCdefGHIJ...），请务必复制并妥善保存。
   

安全提醒：Bot Token 相当于机器人的最高控制权限密码，切勿泄露到公开场合。如果不慎泄露，可以在 BotFather 中发送 /revoke 指令来重新生成。

第三步：运行向导，完成基础配置

在终端中输入以下命令，启动交互式配置向导：

openclaw onboard

向导会以问答形式引导你完成初始设置。请按照以下策略进行选择：

• I understand this is powerful and inherently risky. Continue? → 选择 Yes。
  
• Onboarding mode → 选择 QuickStart（对于新服务器，使用默认配置最省事）。
  
• Model/auth provider → 翻到列表最底部，选择 Skip for now (configure later)。这是关键一步，因为我们要接入的 AIGoCode 不在官方提供的供应商列表中，所以先跳过，稍后手动配置。
  
• Filter models by provider → 保持 All providers，直接按回车。
  
• Default model → 选择 Keep current（保持默认即可，稍后我们会在配置文件里手动指定 AIGoCode 的模型）。
  
• Channels → 选择 Telegram，然后粘贴你刚才获取到的 Bot Token。向导会自动尝试帮你完成管理员配对。
  
  
• Configure skills now? → 选择 No（Skills 功能后续可以随时添加，先让核心服务跑起来再说）。
  
• Enable hooks? → 建议全选（boot-md、bootstrap-extra-files、command-logger、session-memory 都挺实用，尤其是 session-memory 能在切换会话时自动保存上下文）。
  
• 如果出现 Install Gateway service 选项，选择 Yes（这将开启服务开机自启）。

向导在后台默默完成了以下几项重要工作：

1. 生成配置文件：默认路径为 ~/.openclaw/openclaw.json，其中包含了刚才的所有设置。
2. 开启 systemd lingering：确保即使你退出 SSH 会话，服务也不会被终止，保持 Bot 持续在线。
3. 安装 systemd 服务：注册为开机自启服务（openclaw-gateway.service），服务器重启后 Bot 会自动拉起。
4. 验证 Telegram 连接：自动检测 Bot Token 是否有效，看到 Telegram: ok 即表示连接成功。
   
   • 如果出现 How do you want to hatch your bot? 选项，选择 Do this later（因为模型还没配置好，现在执行 hatch 会失败，等配好 AIGoCode 再说）。

“Hatch” 是 OpenClaw 的首次人格初始化流程，用于给 Bot 设定名字、性格和身份。配置好模型并重启后，直接在 Telegram 聊天即可。即使没有进行 hatch，Bot 也能正常工作，只是会使用默认的通用人格。

向导运行结束后会提示 Onboarding complete。至此，基础环境部署完成！

第四步：注入 AIGoCode 中转模型配置

向导已经生成了一个完整的配置文件，但里面缺少模型配置（因为我们选择了 Skip）。现在需要手动将 AIGoCode 的模型信息添加进去。

首先，打开配置文件：

# 如果有 nano 编辑器：
nano ~/.openclaw/openclaw.json

# 如果没有 nano，可以使用 vi：
vi ~/.openclaw/openclaw.json

# 或者先安装 nano：sudo apt install -y nano

在文件的最外层对象内，找到一个合适的位置（例如紧跟在已有的 wizard 或 meta 块之后），插入以下两段配置 （注意：将 sk-这里填你的AIGoCode的APIKey 替换为你真实的 AIGoCode API Key）：

  "models": {
    "providers": {
      "aigocode": {
        "baseUrl": "https://api.aigocode.com",
        "apiKey": "sk-这里填你的AIGoCode的APIKey",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6 (AIGoCode)",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "aigocode/claude-opus-4-6"
      }
    }
  }

⚠️ 踩坑提醒：如果配置文件中已经存在 agents 字段（向导可能会生成一个默认的），你需要将新的 model 配置合并到现有的 agents 对象中，而不是直接粘贴一整段新的 agents。因为 JSON 格式规定，同一层级不能有两个同名的键，否则后面的会覆盖前面的，可能导致模型配置丢失或报错。

例如，从下面的初始配置文件截图可以看到，没有 models 模块，所以可以把完整的 models 模块粘贴进去。但已经存在 agents 模块，因此我们需要做的是把 "model": { "primary": ... } 这段内容粘贴到现有的 agents.defaults 里面，而不是再粘贴一整个新的 agents 模块。

编辑完成后，保存并退出编辑器（在 nano 中是 Ctrl+O 回车保存，Ctrl+X 退出）。

关于 api 字段的说明：

• anthropic-messages：用于 Claude 系列模型（如 Claude Opus 4.6、Claude Sonnet 4 等）。
• openai-responses：用于 GPT 系列模型（如 GPT-4o、GPT-3.5 等），以及大部分兼容 OpenAI API 格式的开源模型。

请根据你在 AIGoCode 上实际计划使用的模型类型，选择对应的 api 格式。

第五步：重启服务，开始对话

修改配置文件后，需要重启 OpenClaw 网关服务才能使配置生效：

openclaw gateway restart

重启完成后，可以运行以下命令确认服务状态：

openclaw gateway status

只要状态显示为 active (running) 就表示服务运行正常，可以继续下一步的配对操作。

第六步：Telegram 配对

服务重启成功后，打开 Telegram，向你的 Bot 发送任意一条消息（例如“哈喽”或“你好”）。Bot 会回复一段配对提示信息，类似：

OpenClaw: access not configured. Your Telegram user id: xxxxxxxx Pairing code: XXXXXXXX

这是正常现象，因为你还没有完成管理员身份绑定。复制最后一行提示中的命令，格式为 openclaw pairing approve telegram <你的配对码>，回到服务器终端执行该命令。

看到 Approved 提示后，返回 Telegram 再发送一条消息，此时 Bot 应该就能正常回复了。恭喜你，部署完成！

总结

整个部署流程清晰分为六步：安装核心程序 → 申请 Telegram 机器人 → 运行交互式向导完成基础配置 → 手动修改配置文件接入 AI 模型 → 重启服务 → 在 Telegram 中完成配对。向导主要负责搞定运行环境和通讯渠道，而配置文件则用于灵活接入第三方 AI 模型，两者各司其职。

核心目标就是先让服务跑起来，能和机器人正常对话。只要实现了这一步，后续无论是添加更多模型、更换通讯渠道，还是配置复杂技能，都可以直接与机器人沟通，让它来帮你操作。

常见问题

• No API key found for provider anthropic：请仔细检查配置文件，确认 models 和 agents 板块配置正确，并且 agents.defaults.model.primary 的值确实指向了 aigocode/claude-opus-4-6。
• 端口被占用（EADDRINUSE）：这说明有其他进程占用了 OpenClaw 的默认端口。可以使用 ss -tlnp | grep 18789 命令排查是哪个进程占用了端口。
• openclaw: command not found：请确认 npm 全局安装是否成功。可以运行 npm list -g openclaw 检查。如果显示已安装但命令找不到，可能是 npm 的全局二进制文件目录没有加入系统的 PATH 环境变量。运行 npm config get prefix 查看路径，并将其下的 bin 目录添加到 PATH 中。

希望这份详细的指南能帮助你顺利部署 OpenClaw。如果在实践中遇到其他技术难题，欢迎到 云栈社区 的 Node.js 或 运维/DevOps/SRE 板块与其他开发者交流探讨。